util: document cancel safety of SinkExt::send and StreamExt::next (…

…#6417)
tokio-rs · Mar 24, 2024 · deff252 · deff252
1 parent 4565b81
commit deff252
Show file tree

Hide file tree

Showing 3 changed files with 24 additions and 0 deletions.
diff --git a/tokio-util/src/codec/framed.rs b/tokio-util/src/codec/framed.rs
@@ -20,10 +20,21 @@ pin_project! {
     /// You can create a `Framed` instance by using the [`Decoder::framed`] adapter, or
     /// by using the `new` function seen below.
     ///
+    /// # Cancellation safety
+    ///
+    /// * [`futures_util::sink::SinkExt::send`]: if send is used as the event in a
+    /// `tokio::select!` statement and some other branch completes first, then it is
+    /// guaranteed that the message was not sent, but the message itself is lost.
+    /// * [`tokio_stream::StreamExt::next`]: This method is cancel safe. The returned
+    /// future only holds onto a reference to the underlying stream, so dropping it will
+    /// never lose a value.
+    ///
     /// [`Stream`]: futures_core::Stream
     /// [`Sink`]: futures_sink::Sink
     /// [`AsyncRead`]: tokio::io::AsyncRead
     /// [`Decoder::framed`]: crate::codec::Decoder::framed()
+    /// [`futures_util::sink::SinkExt::send`]: futures_util::sink::SinkExt::send
+    /// [`tokio_stream::StreamExt::next`]: https://docs.rs/tokio-stream/latest/tokio_stream/trait.StreamExt.html#method.next
     pub struct Framed<T, U> {
         #[pin]
         inner: FramedImpl<T, U, RWFrames>

diff --git a/tokio-util/src/codec/framed_read.rs b/tokio-util/src/codec/framed_read.rs
@@ -17,9 +17,15 @@ pin_project! {
     /// For examples of how to use `FramedRead` with a codec, see the
     /// examples on the [`codec`] module.
     ///
+    /// # Cancellation safety
+    /// * [`tokio_stream::StreamExt::next`]: This method is cancel safe. The returned
+    /// future only holds onto a reference to the underlying stream, so dropping it will
+    /// never lose a value.
+    ///
     /// [`Stream`]: futures_core::Stream
     /// [`AsyncRead`]: tokio::io::AsyncRead
     /// [`codec`]: crate::codec
+    /// [`tokio_stream::StreamExt::next`]: https://docs.rs/tokio-stream/latest/tokio_stream/trait.StreamExt.html#method.next
     pub struct FramedRead<T, D> {
         #[pin]
         inner: FramedImpl<T, D, ReadFrame>,

diff --git a/tokio-util/src/codec/framed_write.rs b/tokio-util/src/codec/framed_write.rs
@@ -18,8 +18,15 @@ pin_project! {
     /// For examples of how to use `FramedWrite` with a codec, see the
     /// examples on the [`codec`] module.
     ///
+    /// # Cancellation safety
+    ///
+    /// * [`futures_util::sink::SinkExt::send`]: if send is used as the event in a
+    /// `tokio::select!` statement and some other branch completes first, then it is
+    /// guaranteed that the message was not sent, but the message itself is lost.
+    ///
     /// [`Sink`]: futures_sink::Sink
     /// [`codec`]: crate::codec
+    /// [`futures_util::sink::SinkExt::send`]: futures_util::sink::SinkExt::send
     pub struct FramedWrite<T, E> {
         #[pin]
         inner: FramedImpl<T, E, WriteFrame>,