Document cancellation safety

tokio/src/io/util/async_read_ext.rs

@@ -105,8 +105,8 @@ cfg_io_util! {
         /// async fn read(&mut self, buf: &mut [u8]) -> io::Result<usize>;
         /// ```
         ///
-        /// This function does not provide any guarantees about whether it
-        /// completes immediately or asynchronously
+        /// This method does not provide any guarantees about whether it
+        /// completes immediately or asynchronously.
         ///
         /// # Return
         ///
@@ -138,6 +138,12 @@ cfg_io_util! {
         /// variant will be returned. If an error is returned then it must be
         /// guaranteed that no bytes were read.
         ///
+        /// # Cancel safety
+        ///
+        /// This method is cancel safe. If you use it as the event in a
+        /// [`tokio::select!`](crate::select) statement and some other branch
+        /// completes first, then it is guaranteed that no data was read.
+        ///
         /// # Examples
         ///
         /// [`File`][crate::fs::File]s implement `Read`:
@@ -177,8 +183,8 @@ cfg_io_util! {
         /// Usually, only a single `read` syscall is issued, even if there is
         /// more space in the supplied buffer.
         ///
-        /// This function does not provide any guarantees about whether it
-        /// completes immediately or asynchronously
+        /// This method does not provide any guarantees about whether it
+        /// completes immediately or asynchronously.
         ///
         /// # Return
         ///
@@ -197,6 +203,12 @@ cfg_io_util! {
         /// variant will be returned. If an error is returned then it must be
         /// guaranteed that no bytes were read.
         ///
+        /// # Cancel safety
+        ///
+        /// This method is cancel safe. If you use it as the event in a
+        /// [`tokio::select!`](crate::select) statement and some other branch
+        /// completes first, then it is guaranteed that no data was read.
+        ///
         /// # Examples
         ///
         /// [`File`] implements `Read` and [`BytesMut`] implements [`BufMut`]:
@@ -261,6 +273,13 @@ cfg_io_util! {
         /// it has read, but it will never read more than would be necessary to
         /// completely fill the buffer.
         ///
+        /// # 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 already have been
+        /// read into `buf`.
+        ///
         /// # Examples
         ///
         /// [`File`][crate::fs::File]s implement `Read`:

tokio/src/io/util/async_write_ext.rs

@@ -97,6 +97,13 @@ cfg_io_util! {
         /// It is **not** considered an error if the entire buffer could not be
         /// written to this writer.
         ///
+        /// # Cancel safety
+        ///
+        /// This method is cancellation safe in the sense that if it is used as
+        /// the event in a [`tokio::select!`](crate::select) statement and some
+        /// other branch completes first, then it is guaranteed that no data was
+        /// written to this `AsyncWrite`.
+        ///
         /// # Examples
         ///
         /// ```no_run
@@ -129,6 +136,13 @@ cfg_io_util! {
         ///
         /// See [`AsyncWrite::poll_write_vectored`] for more details.
         ///
+        /// # Cancel safety
+        ///
+        /// This method is cancellation safe in the sense that if it is used as
+        /// the event in a [`tokio::select!`](crate::select) statement and some
+        /// other branch completes first, then it is guaranteed that no data was
+        /// written to this `AsyncWrite`.
+        ///
         /// # Examples
         ///
         /// ```no_run
@@ -195,6 +209,13 @@ cfg_io_util! {
         /// It is **not** considered an error if the entire buffer could not be
         /// written to this writer.
         ///
+        /// # Cancel safety
+        ///
+        /// This method is cancellation safe in the sense that if it is used as
+        /// the event in a [`tokio::select!`](crate::select) statement and some
+        /// other branch completes first, then it is guaranteed that no data was
+        /// written to this `AsyncWrite`.
+        ///
         /// # Examples
         ///
         /// [`File`] implements [`AsyncWrite`] and [`Cursor`]`<&[u8]>` implements [`Buf`]:
@@ -243,6 +264,7 @@ cfg_io_util! {
         ///     while buf.has_remaining() {
         ///         self.write_buf(&mut buf).await?;
         ///     }
+        ///     Ok(())
         /// }
         /// ```
         ///
@@ -254,13 +276,23 @@ cfg_io_util! {
         /// The buffer is advanced after each chunk is successfully written. After failure,
         /// `src.chunk()` will return the chunk that failed to write.
         ///
+        /// # Cancel safety
+        ///
+        /// If `write_all_buf` is used as the event in a
+        /// [`tokio::select!`](crate::select) statement and some other branch
+        /// completes first, then the data in the provided buffer may have been
+        /// partially written. However, it is guaranteed that the provided
+        /// buffer has been [advanced] by the amount of bytes that have been
+        /// partially written.
+        ///
         /// # Examples
         ///
         /// [`File`] implements [`AsyncWrite`] and [`Cursor`]`<&[u8]>` implements [`Buf`]:
         ///
         /// [`File`]: crate::fs::File
         /// [`Buf`]: bytes::Buf
         /// [`Cursor`]: std::io::Cursor
+        /// [advanced]: bytes::Buf::advance
         ///
         /// ```no_run
         /// use tokio::io::{self, AsyncWriteExt};
@@ -300,6 +332,14 @@ cfg_io_util! {
         /// has been successfully written or such an error occurs. The first
         /// error generated from this method will be returned.
         ///
+        /// # Cancel safety
+        ///
+        /// This method is not cancellation safe. If it is used as the event
+        /// in a [`tokio::select!`](crate::select) statement and some other
+        /// branch completes first, then the provided buffer may have been
+        /// partially written, but future calls to `write_all` will start over
+        /// from the beginning of the buffer.
+        ///
         /// # Errors
         ///
         /// This function will return the first error that [`write`] returns.