From 060f66c665f12b97d6d16f3ff832b941813800e7 Mon Sep 17 00:00:00 2001 From: Grayman <59284190+Lqz13Th@users.noreply.github.com> Date: Tue, 23 Jun 2026 17:13:01 +0800 Subject: [PATCH] docs: clarify cancel safety wording (#8181) Co-authored-by: Tim Vilgot Mikael Fredenberg <26655508+vilgotf@users.noreply.github.com> --- tokio/src/fs/read_dir.rs | 2 +- tokio/src/io/util/async_buf_read_ext.rs | 14 +-- tokio/src/io/util/async_read_ext.rs | 142 ++++++++++++------------ tokio/src/io/util/async_write_ext.rs | 34 +++--- tokio/src/io/util/lines.rs | 2 +- tokio/src/macros/select.rs | 5 + tokio/src/net/tcp/listener.rs | 4 +- tokio/src/net/tcp/stream.rs | 4 +- tokio/src/net/udp.rs | 16 +-- tokio/src/net/unix/datagram/socket.rs | 16 +-- tokio/src/net/unix/listener.rs | 4 +- tokio/src/net/windows/named_pipe.rs | 4 +- tokio/src/runtime/task/join.rs | 6 +- tokio/src/signal/unix.rs | 4 +- tokio/src/sync/broadcast.rs | 4 +- tokio/src/sync/mpsc/bounded.rs | 16 +-- tokio/src/sync/mpsc/unbounded.rs | 12 +- tokio/src/sync/oneshot.rs | 8 +- tokio/src/sync/watch.rs | 8 +- tokio/src/task/join_set.rs | 16 +-- tokio/src/time/interval.rs | 5 +- 21 files changed, 166 insertions(+), 160 deletions(-) diff --git a/tokio/src/fs/read_dir.rs b/tokio/src/fs/read_dir.rs index 2e7288adb..4f98c0c35 100644 --- a/tokio/src/fs/read_dir.rs +++ b/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> { use std::future::poll_fn; poll_fn(|cx| self.poll_next_entry(cx)).await diff --git a/tokio/src/io/util/async_buf_read_ext.rs b/tokio/src/io/util/async_buf_read_ext.rs index f6ef74195..b2b94f95f 100644 --- a/tokio/src/io/util/async_buf_read_ext.rs +++ b/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 diff --git a/tokio/src/io/util/async_read_ext.rs b/tokio/src/io/util/async_read_ext.rs index 59de6cdb1..871af7f7e 100644 --- a/tokio/src/io/util/async_read_ext.rs +++ b/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 /// diff --git a/tokio/src/io/util/async_write_ext.rs b/tokio/src/io/util/async_write_ext.rs index 9bdc49748..913b824cc 100644 --- a/tokio/src/io/util/async_write_ext.rs +++ b/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. /// diff --git a/tokio/src/io/util/lines.rs b/tokio/src/io/util/lines.rs index 9472557b4..8d723aaa7 100644 --- a/tokio/src/io/util/lines.rs +++ b/tokio/src/io/util/lines.rs @@ -49,7 +49,7 @@ where /// /// # Cancel safety /// - /// This method is cancellation safe. + /// This method is cancel safe. /// /// # Examples /// diff --git a/tokio/src/macros/select.rs b/tokio/src/macros/select.rs index a69a1574b..7341f96e4 100644 --- a/tokio/src/macros/select.rs +++ b/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) diff --git a/tokio/src/net/tcp/listener.rs b/tokio/src/net/tcp/listener.rs index 35344fd5d..142d7bb65 100644 --- a/tokio/src/net/tcp/listener.rs +++ b/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. /// diff --git a/tokio/src/net/tcp/stream.rs b/tokio/src/net/tcp/stream.rs index 67a0d06cd..cddc570df 100644 --- a/tokio/src/net/tcp/stream.rs +++ b/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. /// diff --git a/tokio/src/net/udp.rs b/tokio/src/net/udp.rs index 2d3c5b809..212f18b8b 100644 --- a/tokio/src/net/udp.rs +++ b/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. /// diff --git a/tokio/src/net/unix/datagram/socket.rs b/tokio/src/net/unix/datagram/socket.rs index 4005c80fc..1d6fbc3c8 100644 --- a/tokio/src/net/unix/datagram/socket.rs +++ b/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. /// diff --git a/tokio/src/net/unix/listener.rs b/tokio/src/net/unix/listener.rs index d4e362f07..b39eedde3 100644 --- a/tokio/src/net/unix/listener.rs +++ b/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)> { diff --git a/tokio/src/net/windows/named_pipe.rs b/tokio/src/net/windows/named_pipe.rs index 17e793b47..7e1f01eb8 100644 --- a/tokio/src/net/windows/named_pipe.rs +++ b/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 diff --git a/tokio/src/runtime/task/join.rs b/tokio/src/runtime/task/join.rs index a22c22d9f..dfe0fad70 100644 --- a/tokio/src/runtime/task/join.rs +++ b/tokio/src/runtime/task/join.rs @@ -28,9 +28,9 @@ cfg_rt! { /// /// # Cancel safety /// - /// The `&mut JoinHandle` 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` 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. diff --git a/tokio/src/signal/unix.rs b/tokio/src/signal/unix.rs index 85727ad30..41222fbab 100644 --- a/tokio/src/signal/unix.rs +++ b/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 diff --git a/tokio/src/sync/broadcast.rs b/tokio/src/sync/broadcast.rs index 4890b6ebe..1d8f3a9ab 100644 --- a/tokio/src/sync/broadcast.rs +++ b/tokio/src/sync/broadcast.rs @@ -1407,8 +1407,8 @@ impl Receiver { /// /// # 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. /// diff --git a/tokio/src/sync/mpsc/bounded.rs b/tokio/src/sync/mpsc/bounded.rs index db50535ff..c11d2696c 100644 --- a/tokio/src/sync/mpsc/bounded.rs +++ b/tokio/src/sync/mpsc/bounded.rs @@ -198,9 +198,9 @@ impl Receiver { /// /// # 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 Receiver { /// /// # 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 Sender { /// /// # 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.** /// diff --git a/tokio/src/sync/mpsc/unbounded.rs b/tokio/src/sync/mpsc/unbounded.rs index 5e842ea8f..dd64e498a 100644 --- a/tokio/src/sync/mpsc/unbounded.rs +++ b/tokio/src/sync/mpsc/unbounded.rs @@ -123,9 +123,9 @@ impl UnboundedReceiver { /// /// # 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 UnboundedReceiver { /// /// # 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 diff --git a/tokio/src/sync/oneshot.rs b/tokio/src/sync/oneshot.rs index ccc77a6e8..5d913e3d3 100644 --- a/tokio/src/sync/oneshot.rs +++ b/tokio/src/sync/oneshot.rs @@ -243,11 +243,11 @@ pub struct Sender { /// /// [`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` 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 diff --git a/tokio/src/sync/watch.rs b/tokio/src/sync/watch.rs index 502765ebc..96e1dad64 100644 --- a/tokio/src/sync/watch.rs +++ b/tokio/src/sync/watch.rs @@ -788,8 +788,8 @@ impl Receiver { /// /// # 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 Receiver { /// /// # 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`. /// diff --git a/tokio/src/task/join_set.rs b/tokio/src/task/join_set.rs index f280a7461..96d10a713 100644 --- a/tokio/src/task/join_set.rs +++ b/tokio/src/task/join_set.rs @@ -288,11 +288,11 @@ impl JoinSet { /// /// 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> { std::future::poll_fn(|cx| self.poll_join_next(cx)).await } @@ -305,11 +305,11 @@ impl JoinSet { /// 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 diff --git a/tokio/src/time/interval.rs b/tokio/src/time/interval.rs index fb8baa983..ff889a00f 100644 --- a/tokio/src/time/interval.rs +++ b/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 ///