From 0fe24fcffaa98cea639f9e3b38c9c4e93305fa0d Mon Sep 17 00:00:00 2001 From: Rain Date: Fri, 25 Aug 2023 15:03:23 -0700 Subject: [PATCH] sync: improve cancel-safety documentation for mpsc::Sender::send (#5947) This specific issue (data loss because a send got cancelled) has bitten our team a couple of times over the last few months. We've switched to recommending this kind of reserve pattern instead. --- tokio/src/sync/mpsc/bounded.rs | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/tokio/src/sync/mpsc/bounded.rs b/tokio/src/sync/mpsc/bounded.rs index e870ae5f42e..8924dc22292 100644 --- a/tokio/src/sync/mpsc/bounded.rs +++ b/tokio/src/sync/mpsc/bounded.rs @@ -439,7 +439,11 @@ impl Sender { /// /// If `send` is used as the event in a [`tokio::select!`](crate::select) /// statement and some other branch completes first, then it is guaranteed - /// that the message was not sent. + /// that the message was not sent. **However, in that case, the message + /// is dropped and will be lost.** + /// + /// To avoid losing messages, use [`reserve`](Self::reserve) to reserve + /// capacity, then use the returned [`Permit`] to send the message. /// /// This channel uses a queue to ensure that calls to `send` and `reserve` /// complete in the order they were requested. Cancelling a call to