From 0e9c1d60d1d2bbf145ffa5d424f9c214879bc720 Mon Sep 17 00:00:00 2001 From: "M.Amin Rayej" Date: Sun, 11 Feb 2024 03:39:04 +0330 Subject: [PATCH] document cancel safety --- tokio/src/io/util/async_read_ext.rs | 132 ++++++++++++++++++++++++++++ 1 file changed, 132 insertions(+) diff --git a/tokio/src/io/util/async_read_ext.rs b/tokio/src/io/util/async_read_ext.rs index 11bd42448ab..4007e4993ee 100644 --- a/tokio/src/io/util/async_read_ext.rs +++ b/tokio/src/io/util/async_read_ext.rs @@ -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`: @@ -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`: @@ -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`: @@ -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`: @@ -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`: @@ -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`: @@ -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`: @@ -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`: @@ -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`: @@ -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`: @@ -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`: @@ -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`: @@ -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`: @@ -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`: @@ -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`: @@ -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`: @@ -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`: @@ -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`: @@ -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`: @@ -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`: @@ -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`: @@ -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`: