docs: clarify cancel safety wording (#8181)

Co-authored-by: Tim Vilgot Mikael Fredenberg <[email protected]>

tokio/src/fs/read_dir.rs

@@ -74,7 +74,7 @@ impl ReadDir {
     ///
     /// # Cancel safety
     ///
-    /// This method is cancellation safe.
+    /// This method is cancel safe.
     pub async fn next_entry(&mut self) -> io::Result<Option<DirEntry>> {
         use std::future::poll_fn;
         poll_fn(|cx| self.poll_next_entry(cx)).await

tokio/src/io/util/async_buf_read_ext.rs

@@ -39,8 +39,8 @@ cfg_io_util! {
         ///
         /// # Cancel safety
         ///
-        /// If the method is used as the event in a
-        /// [`tokio::select!`](crate::select) statement and some other branch
+        /// If used as a branch in
+        /// [`tokio::select!`](crate::select) and another branch
         /// completes first, then some data may have been partially read. Any
         /// partially read bytes are appended to `buf`, and the method can be
         /// called again to continue reading until `byte`.
@@ -129,9 +129,9 @@ cfg_io_util! {
         ///
         /// # 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 have been partially
+        /// This method is not cancel safe. If the method is used as a
+        /// branch in [`tokio::select!`](crate::select) and another
+        /// branch completes first, then some data may have been partially
         /// read, and this data is lost. There are no guarantees regarding the
         /// contents of `buf` when the call is cancelled. The current
         /// implementation replaces `buf` with the empty string, but this may
@@ -269,8 +269,8 @@ cfg_io_util! {
         ///
         /// # 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
+        /// This method is cancel safe. If used as a branch in
+        /// [`tokio::select!`](crate::select) and another branch
         /// completes first, then it is guaranteed that no data was read.
         ///
         /// [`consume`]: crate::io::AsyncBufReadExt::consume

tokio/src/io/util/async_read_ext.rs

@@ -147,8 +147,8 @@ cfg_io_util! {
         ///
         /// # 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
+        /// This method is cancel safe. If you use it as a branch in
+        /// [`tokio::select!`](crate::select) and another branch
         /// completes first, then it is guaranteed that no data was read.
         ///
         /// # Examples
@@ -215,8 +215,8 @@ cfg_io_util! {
         ///
         /// # 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
+        /// This method is cancel safe. If you use it as a branch in
+        /// [`tokio::select!`](crate::select) and another branch
         /// completes first, then it is guaranteed that no data was read.
         ///
         /// # Examples
@@ -291,9 +291,9 @@ cfg_io_util! {
         ///
         /// # 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
+        /// This method is not cancel safe. If the method is used as a
+        /// branch in [`tokio::select!`](crate::select) and another
+        /// branch completes first, then some data may already have been
         /// read into `buf`.
         ///
         /// # Examples
@@ -347,8 +347,8 @@ cfg_io_util! {
             ///
             /// # 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
+            /// This method is cancel safe. If this method is used as a branch in
+            /// [`tokio::select!`](crate::select) and another branch
             /// completes first, it is guaranteed that no data were read.
             ///
             /// # Examples
@@ -391,8 +391,8 @@ cfg_io_util! {
             ///
             /// # 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
+            /// This method is cancel safe. If this method is used as a branch in
+            /// [`tokio::select!`](crate::select) and another branch
             /// completes first, it is guaranteed that no data were read.
             ///
             /// # Examples
@@ -436,9 +436,9 @@ cfg_io_util! {
             ///
             /// # 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.
+            /// This method is not cancel safe. If the method is used as a
+            /// branch in [`tokio::select!`](crate::select) and another
+            /// branch completes first, then some data may be lost.
             ///
             /// # Examples
             ///
@@ -480,9 +480,9 @@ cfg_io_util! {
             ///
             /// # 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.
+            /// This method is not cancel safe. If the method is used as a
+            /// branch in [`tokio::select!`](crate::select) and another
+            /// branch completes first, then some data may be lost.
             ///
             /// # Examples
             ///
@@ -524,9 +524,9 @@ cfg_io_util! {
             ///
             /// # 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.
+            /// This method is not cancel safe. If the method is used as a
+            /// branch in [`tokio::select!`](crate::select) and another
+            /// branch completes first, then some data may be lost.
             ///
             /// # Examples
             ///
@@ -568,9 +568,9 @@ cfg_io_util! {
             ///
             /// # 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.
+            /// This method is not cancel safe. If the method is used as a
+            /// branch in [`tokio::select!`](crate::select) and another
+            /// branch completes first, then some data may be lost.
             ///
             /// # Examples
             ///
@@ -611,9 +611,9 @@ cfg_io_util! {
             ///
             /// # 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.
+            /// This method is not cancel safe. If the method is used as a
+            /// branch in [`tokio::select!`](crate::select) and another
+            /// branch completes first, then some data may be lost.
             ///
             /// # Examples
             ///
@@ -656,9 +656,9 @@ cfg_io_util! {
             ///
             /// # 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.
+            /// This method is not cancel safe. If the method is used as a
+            /// branch in [`tokio::select!`](crate::select) and another
+            /// branch completes first, then some data may be lost.
             ///
             /// # Examples
             ///
@@ -699,9 +699,9 @@ cfg_io_util! {
             ///
             /// # 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.
+            /// This method is not cancel safe. If the method is used as a
+            /// branch in [`tokio::select!`](crate::select) and another
+            /// branch completes first, then some data may be lost.
             ///
             /// # Examples
             ///
@@ -745,9 +745,9 @@ cfg_io_util! {
             ///
             /// # 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.
+            /// This method is not cancel safe. If the method is used as a
+            /// branch in [`tokio::select!`](crate::select) and another
+            /// branch completes first, then some data may be lost.
             ///
             /// # Examples
             ///
@@ -791,9 +791,9 @@ cfg_io_util! {
             ///
             /// # 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.
+            /// This method is not cancel safe. If the method is used as a
+            /// branch in [`tokio::select!`](crate::select) and another
+            /// branch completes first, then some data may be lost.
             ///
             /// # Examples
             ///
@@ -834,9 +834,9 @@ cfg_io_util! {
             ///
             /// # 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.
+            /// This method is not cancel safe. If the method is used as a
+            /// branch in [`tokio::select!`](crate::select) and another
+            /// branch completes first, then some data may be lost.
             ///
             /// # Examples
             ///
@@ -879,9 +879,9 @@ cfg_io_util! {
             ///
             /// # 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.
+            /// This method is not cancel safe. If the method is used as a
+            /// branch in [`tokio::select!`](crate::select) and another
+            /// branch completes first, then some data may be lost.
             ///
             /// # Examples
             ///
@@ -923,9 +923,9 @@ cfg_io_util! {
             ///
             /// # 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.
+            /// This method is not cancel safe. If the method is used as a
+            /// branch in [`tokio::select!`](crate::select) and another
+            /// branch completes first, then some data may be lost.
             ///
             /// # Examples
             ///
@@ -967,9 +967,9 @@ cfg_io_util! {
             ///
             /// # 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.
+            /// This method is not cancel safe. If the method is used as a
+            /// branch in [`tokio::select!`](crate::select) and another
+            /// branch completes first, then some data may be lost.
             ///
             /// # Examples
             ///
@@ -1011,9 +1011,9 @@ cfg_io_util! {
             ///
             /// # 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.
+            /// This method is not cancel safe. If the method is used as a
+            /// branch in [`tokio::select!`](crate::select) and another
+            /// branch completes first, then some data may be lost.
             ///
             /// # Examples
             ///
@@ -1054,9 +1054,9 @@ cfg_io_util! {
             ///
             /// # 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.
+            /// This method is not cancel safe. If the method is used as a
+            /// branch in [`tokio::select!`](crate::select) and another
+            /// branch completes first, then some data may be lost.
             ///
             /// # Examples
             ///
@@ -1099,9 +1099,9 @@ cfg_io_util! {
             ///
             /// # 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.
+            /// This method is not cancel safe. If the method is used as a
+            /// branch in [`tokio::select!`](crate::select) and another
+            /// branch completes first, then some data may be lost.
             ///
             /// # Examples
             ///
@@ -1142,9 +1142,9 @@ cfg_io_util! {
             ///
             /// # 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.
+            /// This method is not cancel safe. If the method is used as a
+            /// branch in [`tokio::select!`](crate::select) and another
+            /// branch completes first, then some data may be lost.
             ///
             /// # Examples
             ///
@@ -1188,9 +1188,9 @@ cfg_io_util! {
             ///
             /// # 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.
+            /// This method is not cancel safe. If the method is used as a
+            /// branch in [`tokio::select!`](crate::select) and another
+            /// branch completes first, then some data may be lost.
             ///
             /// # Examples
             ///
@@ -1234,9 +1234,9 @@ cfg_io_util! {
             ///
             /// # 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.
+            /// This method is not cancel safe. If the method is used as a
+            /// branch in [`tokio::select!`](crate::select) and another
+            /// branch completes first, then some data may be lost.
             ///
             /// # Examples
             ///
@@ -1277,9 +1277,9 @@ cfg_io_util! {
             ///
             /// # 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.
+            /// This method is not cancel safe. If the method is used as a
+            /// branch in [`tokio::select!`](crate::select) and another
+            /// branch completes first, then some data may be lost.
             ///
             /// # Examples
             ///

tokio/src/io/util/async_write_ext.rs

@@ -103,9 +103,9 @@ cfg_io_util! {
         ///
         /// # 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
+        /// This method is cancel safe. If it is used as a branch in
+        /// [`tokio::select!`](crate::select) and another branch completes
+        /// first, then it is guaranteed that no data was
         /// written to this `AsyncWrite`.
         ///
         /// # Examples
@@ -146,9 +146,9 @@ cfg_io_util! {
         ///
         /// # 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
+        /// This method is cancel safe. If it is used as a branch in
+        /// [`tokio::select!`](crate::select) and another branch completes
+        /// first, then it is guaranteed that no data was
         /// written to this `AsyncWrite`.
         ///
         /// # Examples
@@ -223,9 +223,9 @@ cfg_io_util! {
         ///
         /// # 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
+        /// This method is cancel safe. If it is used as a branch in
+        /// [`tokio::select!`](crate::select) and another branch completes
+        /// first, then it is guaranteed that no data was
         /// written to this `AsyncWrite`.
         ///
         /// # Examples
@@ -294,8 +294,8 @@ cfg_io_util! {
         ///
         /// # Cancel safety
         ///
-        /// If `write_all_buf` is used as the event in a
-        /// [`tokio::select!`](crate::select) statement and some other branch
+        /// If `write_all_buf` is used as a branch in
+        /// [`tokio::select!`](crate::select) and another 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
@@ -354,9 +354,9 @@ cfg_io_util! {
         ///
         /// # 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
+        /// This method is not cancel safe. If it is used as a branch in
+        /// [`tokio::select!`](crate::select) and another 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.
         ///
@@ -1253,9 +1253,9 @@ cfg_io_util! {
         ///
         /// This method is cancel safe.
         ///
-        /// If `flush` is used as the event in a [`tokio::select!`](crate::select)
-        /// statement and some other branch completes first, then the data in the
-        /// buffered data in this `AsyncWrite` may have been partially flushed.
+        /// If `flush` is used as a branch in [`tokio::select!`](crate::select)
+        /// and another branch completes first, then the buffered data in this
+        /// `AsyncWrite` may have been partially flushed.
         /// However, it is guaranteed that the buffer is advanced by the amount of
         /// bytes that have been partially flushed.
         ///

tokio/src/io/util/lines.rs

@@ -49,7 +49,7 @@ where
     ///
     /// # Cancel safety
     ///
-    /// This method is cancellation safe.
+    /// This method is cancel safe.
     ///
     /// # Examples
     ///

tokio/src/macros/select.rs

@@ -95,6 +95,11 @@ macro_rules! doc {
         /// describes whether they are cancel safe.  The lists in this section are not
         /// exhaustive.
         ///
+        /// Cancellation safety describes what happens when a future is dropped
+        /// before it completes. Whether something is cancellation safe depends on
+        /// the behavior of the future passed to `select!`, which may come from an
+        /// async method, an async expression, or another future-producing operation.
+        ///
         /// The following methods are cancellation safe:
         ///
         ///  * [`tokio::sync::mpsc::Receiver::recv`](crate::sync::mpsc::Receiver::recv)

tokio/src/net/tcp/listener.rs

@@ -133,8 +133,8 @@ impl TcpListener {
     ///
     /// # Cancel safety
     ///
-    /// This method is cancel safe. If the method is used as the event in a
-    /// [`tokio::select!`](crate::select) statement and some other branch
+    /// This method is cancel safe. If the method is used as a branch in
+    /// [`tokio::select!`](crate::select) and another branch
     /// completes first, then it is guaranteed that no new connections were
     /// accepted by this method.
     ///

tokio/src/net/tcp/stream.rs

@@ -1074,8 +1074,8 @@ impl TcpStream {
     ///
     /// # Cancel safety
     ///
-    /// This method is cancel safe. If the method is used as the event in a
-    /// [`tokio::select!`](crate::select) statement and some other branch
+    /// This method is cancel safe. If the method is used as a branch in
+    /// [`tokio::select!`](crate::select) and another branch
     /// completes first, then it is guaranteed that no peek was performed, and
     /// that `buf` has not been modified.
     ///

tokio/src/net/udp.rs

@@ -545,8 +545,8 @@ impl UdpSocket {
     ///
     /// # Cancel safety
     ///
-    /// This method is cancel safe. If `send` is used as the event in a
-    /// [`tokio::select!`](crate::select) statement and some other branch
+    /// This method is cancel safe. If `send` is used as a branch in
+    /// [`tokio::select!`](crate::select) and another branch
     /// completes first, then it is guaranteed that the message was not sent.
     ///
     /// # Examples
@@ -762,8 +762,8 @@ impl UdpSocket {
     ///
     /// # Cancel safety
     ///
-    /// This method is cancel safe. If `recv` is used as the event in a
-    /// [`tokio::select!`](crate::select) statement and some other branch
+    /// This method is cancel safe. If `recv` is used as a branch in
+    /// [`tokio::select!`](crate::select) and another branch
     /// completes first, it is guaranteed that no messages were received on this
     /// socket.
     ///
@@ -1162,8 +1162,8 @@ impl UdpSocket {
     ///
     /// # Cancel safety
     ///
-    /// This method is cancel safe. If `send_to` is used as the event in a
-    /// [`tokio::select!`](crate::select) statement and some other branch
+    /// This method is cancel safe. If `send_to` is used as a branch in
+    /// [`tokio::select!`](crate::select) and another branch
     /// completes first, then it is guaranteed that the message was not sent.
     ///
     /// # Example
@@ -1291,8 +1291,8 @@ impl UdpSocket {
     ///
     /// # Cancel safety
     ///
-    /// This method is cancel safe. If `recv_from` is used as the event in a
-    /// [`tokio::select!`](crate::select) statement and some other branch
+    /// This method is cancel safe. If `recv_from` is used as a branch in
+    /// [`tokio::select!`](crate::select) and another branch
     /// completes first, it is guaranteed that no messages were received on this
     /// socket.
     ///

tokio/src/net/unix/datagram/socket.rs

@@ -612,8 +612,8 @@ impl UnixDatagram {
     ///
     /// # Cancel safety
     ///
-    /// This method is cancel safe. If `send` is used as the event in a
-    /// [`tokio::select!`](crate::select) statement and some other branch
+    /// This method is cancel safe. If `send` is used as a branch in
+    /// [`tokio::select!`](crate::select) and another branch
     /// completes first, then it is guaranteed that the message was not sent.
     ///
     /// # Examples
@@ -742,8 +742,8 @@ impl UnixDatagram {
     ///
     /// # Cancel safety
     ///
-    /// This method is cancel safe. If `recv` is used as the event in a
-    /// [`tokio::select!`](crate::select) statement and some other branch
+    /// This method is cancel safe. If `recv` is used as a branch in
+    /// [`tokio::select!`](crate::select) and another branch
     /// completes first, it is guaranteed that no messages were received on this
     /// socket.
     ///
@@ -1062,8 +1062,8 @@ impl UnixDatagram {
     ///
     /// # Cancel safety
     ///
-    /// This method is cancel safe. If `send_to` is used as the event in a
-    /// [`tokio::select!`](crate::select) statement and some other branch
+    /// This method is cancel safe. If `send_to` is used as a branch in
+    /// [`tokio::select!`](crate::select) and another branch
     /// completes first, then it is guaranteed that the message was not sent.
     ///
     /// # Examples
@@ -1112,8 +1112,8 @@ impl UnixDatagram {
     ///
     /// # Cancel safety
     ///
-    /// This method is cancel safe. If `recv_from` is used as the event in a
-    /// [`tokio::select!`](crate::select) statement and some other branch
+    /// This method is cancel safe. If `recv_from` is used as a branch in
+    /// [`tokio::select!`](crate::select) and another branch
     /// completes first, it is guaranteed that no messages were received on this
     /// socket.
     ///

tokio/src/net/unix/listener.rs

@@ -202,8 +202,8 @@ impl UnixListener {
     ///
     /// # Cancel safety
     ///
-    /// This method is cancel safe. If the method is used as the event in a
-    /// [`tokio::select!`](crate::select) statement and some other branch
+    /// This method is cancel safe. If the method is used as a branch in
+    /// [`tokio::select!`](crate::select) and another branch
     /// completes first, then it is guaranteed that no new connections were
     /// accepted by this method.
     pub async fn accept(&self) -> io::Result<(UnixStream, SocketAddr)> {

tokio/src/net/windows/named_pipe.rs

@@ -167,8 +167,8 @@ impl NamedPipeServer {
     ///
     /// # Cancel safety
     ///
-    /// This method is cancellation safe in the sense that if it is used as the
-    /// event in a [`select!`](crate::select) statement and some other branch
+    /// This method is cancel safe. If it is used as a branch in
+    /// [`select!`](crate::select) and another branch
     /// completes first, then no connection events have been lost.
     ///
     /// [`ConnectNamedPipe`]: https://docs.microsoft.com/en-us/windows/win32/api/namedpipeapi/nf-namedpipeapi-connectnamedpipe

tokio/src/runtime/task/join.rs

@@ -28,9 +28,9 @@ cfg_rt! {
     ///
     /// # Cancel safety
     ///
-    /// The `&mut JoinHandle<T>` type is cancel safe. If it is used as the event
-    /// in a `tokio::select!` statement and some other branch completes first,
-    /// then it is guaranteed that the output of the task is not lost.
+    /// Awaiting a `&mut JoinHandle<T>` is cancel safe. If it is used as a
+    /// branch in `tokio::select!` and another branch completes first, then it
+    /// is guaranteed that the output of the task is not lost.
     ///
     /// If a `JoinHandle` is dropped, then the task continues running in the
     /// background and its return value is lost.

tokio/src/signal/unix.rs

@@ -426,8 +426,8 @@ impl Signal {
     ///
     /// # 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
+    /// This method is cancel safe. If you use it as a branch in
+    /// [`tokio::select!`](crate::select) and another branch
     /// completes first, then it is guaranteed that no signal is lost.
     ///
     /// # Examples

tokio/src/sync/broadcast.rs

@@ -1407,8 +1407,8 @@ impl<T: Clone> Receiver<T> {
     ///
     /// # Cancel safety
     ///
-    /// This method is cancel safe. If `recv` is used as the event in a
-    /// [`tokio::select!`](crate::select) statement and some other branch
+    /// This method is cancel safe. If `recv` is used as a branch in
+    /// [`tokio::select!`](crate::select) and another branch
     /// completes first, it is guaranteed that no messages were received on this
     /// channel.
     ///

tokio/src/sync/mpsc/bounded.rs

@@ -198,9 +198,9 @@ impl<T> Receiver<T> {
     ///
     /// # Cancel safety
     ///
-    /// This method is cancel safe. If `recv` is used as the event in a
-    /// [`tokio::select!`](crate::select) statement and some other branch
-    /// completes first, it is guaranteed that no messages were received on this
+    /// This method is cancel safe. If `recv` is used as a branch in
+    /// [`tokio::select!`](crate::select) and another branch completes first,
+    /// it is guaranteed that no messages were received on this
     /// channel.
     ///
     /// [`close`]: Self::close
@@ -268,9 +268,9 @@ impl<T> Receiver<T> {
     ///
     /// # Cancel safety
     ///
-    /// This method is cancel safe. If `recv_many` is used as the event in a
-    /// [`tokio::select!`](crate::select) statement and some other branch
-    /// completes first, it is guaranteed that no messages were received on this
+    /// This method is cancel safe. If `recv_many` is used as a branch in
+    /// [`tokio::select!`](crate::select) and another branch completes first,
+    /// it is guaranteed that no messages were received on this
     /// channel.
     ///
     /// [`close`]: Self::close
@@ -775,8 +775,8 @@ impl<T> Sender<T> {
     ///
     /// # Cancel safety
     ///
-    /// If `send` is used as the event in a [`tokio::select!`](crate::select)
-    /// statement and some other branch completes first, then it is guaranteed
+    /// If `send` is used as a branch in [`tokio::select!`](crate::select) and
+    /// another branch completes first, then it is guaranteed
     /// that the message was not sent. **However, in that case, the message
     /// is dropped and will be lost.**
     ///

tokio/src/sync/mpsc/unbounded.rs

@@ -123,9 +123,9 @@ impl<T> UnboundedReceiver<T> {
     ///
     /// # Cancel safety
     ///
-    /// This method is cancel safe. If `recv` is used as the event in a
-    /// [`tokio::select!`](crate::select) statement and some other branch
-    /// completes first, it is guaranteed that no messages were received on this
+    /// This method is cancel safe. If `recv` is used as a branch in
+    /// [`tokio::select!`](crate::select) and another branch completes first,
+    /// it is guaranteed that no messages were received on this
     /// channel.
     ///
     /// [`close`]: Self::close
@@ -191,9 +191,9 @@ impl<T> UnboundedReceiver<T> {
     ///
     /// # Cancel safety
     ///
-    /// This method is cancel safe. If `recv_many` is used as the event in a
-    /// [`tokio::select!`](crate::select) statement and some other branch
-    /// completes first, it is guaranteed that no messages were received on this
+    /// This method is cancel safe. If `recv_many` is used as a branch in
+    /// [`tokio::select!`](crate::select) and another branch completes first,
+    /// it is guaranteed that no messages were received on this
     /// channel.
     ///
     /// [`close`]: Self::close

tokio/src/sync/oneshot.rs

@@ -243,11 +243,11 @@ pub struct Sender<T> {
 ///
 /// [`Future`]: trait@std::future::Future
 ///
-/// # Cancellation safety
+/// # Cancel safety
 ///
-/// The `Receiver` is cancel safe. If it is used as the event in a
-/// [`tokio::select!`](crate::select) statement and some other branch
-/// completes first, it is guaranteed that no message was received on this
+/// Awaiting a `&mut Receiver<T>` is cancel safe. If it is used as a branch in
+/// [`tokio::select!`](crate::select) and another branch completes first, it is
+/// guaranteed that no message was received on this
 /// channel.
 ///
 /// # Examples

tokio/src/sync/watch.rs

@@ -788,8 +788,8 @@ impl<T> Receiver<T> {
     ///
     /// # 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
+    /// This method is cancel safe. If you use it as a branch in
+    /// [`tokio::select!`](crate::select) and another branch
     /// completes first, then it is guaranteed that no values have been marked
     /// seen by this call to `changed`.
     ///
@@ -857,8 +857,8 @@ impl<T> Receiver<T> {
     ///
     /// # 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
+    /// This method is cancel safe. If you use it as a branch in
+    /// [`tokio::select!`](crate::select) and another branch
     /// completes first, then it is guaranteed that the last seen value `val`
     /// (if any) satisfies `f(val) == false`.
     ///

tokio/src/task/join_set.rs

@@ -288,11 +288,11 @@ impl<T: 'static> JoinSet<T> {
     ///
     /// Returns `None` if the set is empty.
     ///
-    /// # Cancel Safety
+    /// # Cancel safety
     ///
-    /// This method is cancel safe. If `join_next` is used as the event in a `tokio::select!`
-    /// statement and some other branch completes first, it is guaranteed that no tasks were
-    /// removed from this `JoinSet`.
+    /// This method is cancel safe. If `join_next` is used as a branch in
+    /// `tokio::select!` and another branch completes first, it is guaranteed
+    /// that no tasks were removed from this `JoinSet`.
     pub async fn join_next(&mut self) -> Option<Result<T, JoinError>> {
         std::future::poll_fn(|cx| self.poll_join_next(cx)).await
     }
@@ -305,11 +305,11 @@ impl<T: 'static> JoinSet<T> {
     /// When this method returns an error, then the id of the task that failed can be accessed
     /// using the [`JoinError::id`] method.
     ///
-    /// # Cancel Safety
+    /// # Cancel safety
     ///
-    /// This method is cancel safe. If `join_next_with_id` is used as the event in a `tokio::select!`
-    /// statement and some other branch completes first, it is guaranteed that no tasks were
-    /// removed from this `JoinSet`.
+    /// This method is cancel safe. If `join_next_with_id` is used as a branch
+    /// in `tokio::select!` and another branch completes first, it is
+    /// guaranteed that no tasks were removed from this `JoinSet`.
     ///
     /// [task ID]: crate::task::Id
     /// [`JoinError::id`]: fn@crate::task::JoinError::id

tokio/src/time/interval.rs

@@ -402,8 +402,9 @@ impl Interval {
     ///
     /// # Cancel safety
     ///
-    /// This method is cancellation safe. If `tick` is used as the branch in a `tokio::select!` and
-    /// another branch completes first, then no tick has been consumed.
+    /// This method is cancel safe. If `tick` is used as a branch in
+    /// [`tokio::select!`](crate::select) and another branch completes first,
+    /// then no tick has been consumed.
     ///
     /// # Examples
     ///