Skip to content

Commit

Permalink
io: document cancel safety of AsyncReadExt's primitive read functio…
Browse files Browse the repository at this point in the history 
…ns (#6337)
  • Loading branch information
@maminrayej
maminrayej committed Feb 11, 2024
1 parent db6929a commit 84e41d4
Showing 1 changed file with 132 additions and 0 deletions.
132 changes: 132 additions & 0 deletions tokio/src/io/util/async_read_ext.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -330,6 +330,12 @@ cfg_io_util! {
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Cancel safety
///
/// This method is cancel safe. If this method is used as an event in a
/// [`tokio::select!`](crate::select) statement and some other branch
/// completes first, it is guaranteed that no data were read.
///
/// # Examples
///
/// Read unsigned 8 bit integers from an `AsyncRead`:
Expand Down Expand Up @@ -368,6 +374,12 @@ cfg_io_util! {
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Cancel safety
///
/// This method is cancel safe. If this method is used as an event in a
/// [`tokio::select!`](crate::select) statement and some other branch
/// completes first, it is guaranteed that no data were read.
///
/// # Examples
///
/// Read unsigned 8 bit integers from an `AsyncRead`:
Expand Down Expand Up @@ -407,6 +419,12 @@ cfg_io_util! {
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Cancel safety
///
/// This method is not cancellation safe. If the method is used as the
/// event in a [`tokio::select!`](crate::select) statement and some
/// other branch completes first, then some data may be lost.
///
/// # Examples
///
/// Read unsigned 16 bit big-endian integers from a `AsyncRead`:
Expand Down Expand Up @@ -445,6 +463,12 @@ cfg_io_util! {
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Cancel safety
///
/// This method is not cancellation safe. If the method is used as the
/// event in a [`tokio::select!`](crate::select) statement and some
/// other branch completes first, then some data may be lost.
///
/// # Examples
///
/// Read signed 16 bit big-endian integers from a `AsyncRead`:
Expand Down Expand Up @@ -483,6 +507,12 @@ cfg_io_util! {
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Cancel safety
///
/// This method is not cancellation safe. If the method is used as the
/// event in a [`tokio::select!`](crate::select) statement and some
/// other branch completes first, then some data may be lost.
///
/// # Examples
///
/// Read unsigned 32-bit big-endian integers from a `AsyncRead`:
Expand Down Expand Up @@ -521,6 +551,12 @@ cfg_io_util! {
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Cancel safety
///
/// This method is not cancellation safe. If the method is used as the
/// event in a [`tokio::select!`](crate::select) statement and some
/// other branch completes first, then some data may be lost.
///
/// # Examples
///
/// Read signed 32-bit big-endian integers from a `AsyncRead`:
Expand Down Expand Up @@ -558,6 +594,12 @@ cfg_io_util! {
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Cancel safety
///
/// This method is not cancellation safe. If the method is used as the
/// event in a [`tokio::select!`](crate::select) statement and some
/// other branch completes first, then some data may be lost.
///
/// # Examples
///
/// Read unsigned 64-bit big-endian integers from a `AsyncRead`:
Expand Down Expand Up @@ -597,6 +639,12 @@ cfg_io_util! {
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Cancel safety
///
/// This method is not cancellation safe. If the method is used as the
/// event in a [`tokio::select!`](crate::select) statement and some
/// other branch completes first, then some data may be lost.
///
/// # Examples
///
/// Read signed 64-bit big-endian integers from a `AsyncRead`:
Expand Down Expand Up @@ -634,6 +682,12 @@ cfg_io_util! {
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Cancel safety
///
/// This method is not cancellation safe. If the method is used as the
/// event in a [`tokio::select!`](crate::select) statement and some
/// other branch completes first, then some data may be lost.
///
/// # Examples
///
/// Read unsigned 128-bit big-endian integers from a `AsyncRead`:
Expand Down Expand Up @@ -674,6 +728,12 @@ cfg_io_util! {
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Cancel safety
///
/// This method is not cancellation safe. If the method is used as the
/// event in a [`tokio::select!`](crate::select) statement and some
/// other branch completes first, then some data may be lost.
///
/// # Examples
///
/// Read signed 128-bit big-endian integers from a `AsyncRead`:
Expand Down Expand Up @@ -714,6 +774,12 @@ cfg_io_util! {
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Cancel safety
///
/// This method is not cancellation safe. If the method is used as the
/// event in a [`tokio::select!`](crate::select) statement and some
/// other branch completes first, then some data may be lost.
///
/// # Examples
///
/// Read 32-bit floating point type from a `AsyncRead`:
Expand Down Expand Up @@ -751,6 +817,12 @@ cfg_io_util! {
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Cancel safety
///
/// This method is not cancellation safe. If the method is used as the
/// event in a [`tokio::select!`](crate::select) statement and some
/// other branch completes first, then some data may be lost.
///
/// # Examples
///
/// Read 64-bit floating point type from a `AsyncRead`:
Expand Down Expand Up @@ -790,6 +862,12 @@ cfg_io_util! {
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Cancel safety
///
/// This method is not cancellation safe. If the method is used as the
/// event in a [`tokio::select!`](crate::select) statement and some
/// other branch completes first, then some data may be lost.
///
/// # Examples
///
/// Read unsigned 16 bit little-endian integers from a `AsyncRead`:
Expand Down Expand Up @@ -828,6 +906,12 @@ cfg_io_util! {
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Cancel safety
///
/// This method is not cancellation safe. If the method is used as the
/// event in a [`tokio::select!`](crate::select) statement and some
/// other branch completes first, then some data may be lost.
///
/// # Examples
///
/// Read signed 16 bit little-endian integers from a `AsyncRead`:
Expand Down Expand Up @@ -866,6 +950,12 @@ cfg_io_util! {
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Cancel safety
///
/// This method is not cancellation safe. If the method is used as the
/// event in a [`tokio::select!`](crate::select) statement and some
/// other branch completes first, then some data may be lost.
///
/// # Examples
///
/// Read unsigned 32-bit little-endian integers from a `AsyncRead`:
Expand Down Expand Up @@ -904,6 +994,12 @@ cfg_io_util! {
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Cancel safety
///
/// This method is not cancellation safe. If the method is used as the
/// event in a [`tokio::select!`](crate::select) statement and some
/// other branch completes first, then some data may be lost.
///
/// # Examples
///
/// Read signed 32-bit little-endian integers from a `AsyncRead`:
Expand Down Expand Up @@ -941,6 +1037,12 @@ cfg_io_util! {
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Cancel safety
///
/// This method is not cancellation safe. If the method is used as the
/// event in a [`tokio::select!`](crate::select) statement and some
/// other branch completes first, then some data may be lost.
///
/// # Examples
///
/// Read unsigned 64-bit little-endian integers from a `AsyncRead`:
Expand Down Expand Up @@ -980,6 +1082,12 @@ cfg_io_util! {
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Cancel safety
///
/// This method is not cancellation safe. If the method is used as the
/// event in a [`tokio::select!`](crate::select) statement and some
/// other branch completes first, then some data may be lost.
///
/// # Examples
///
/// Read signed 64-bit little-endian integers from a `AsyncRead`:
Expand Down Expand Up @@ -1017,6 +1125,12 @@ cfg_io_util! {
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Cancel safety
///
/// This method is not cancellation safe. If the method is used as the
/// event in a [`tokio::select!`](crate::select) statement and some
/// other branch completes first, then some data may be lost.
///
/// # Examples
///
/// Read unsigned 128-bit little-endian integers from a `AsyncRead`:
Expand Down Expand Up @@ -1057,6 +1171,12 @@ cfg_io_util! {
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Cancel safety
///
/// This method is not cancellation safe. If the method is used as the
/// event in a [`tokio::select!`](crate::select) statement and some
/// other branch completes first, then some data may be lost.
///
/// # Examples
///
/// Read signed 128-bit little-endian integers from a `AsyncRead`:
Expand Down Expand Up @@ -1097,6 +1217,12 @@ cfg_io_util! {
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Cancel safety
///
/// This method is not cancellation safe. If the method is used as the
/// event in a [`tokio::select!`](crate::select) statement and some
/// other branch completes first, then some data may be lost.
///
/// # Examples
///
/// Read 32-bit floating point type from a `AsyncRead`:
Expand Down Expand Up @@ -1134,6 +1260,12 @@ cfg_io_util! {
///
/// [`AsyncReadExt::read_exact`]: AsyncReadExt::read_exact
///
/// # Cancel safety
///
/// This method is not cancellation safe. If the method is used as the
/// event in a [`tokio::select!`](crate::select) statement and some
/// other branch completes first, then some data may be lost.
///
/// # Examples
///
/// Read 64-bit floating point type from a `AsyncRead`:
Expand Down

0 comments on commit 84e41d4

Please sign in to comment.