From 883d8bd091c7da153858ef0028fba373c3dd1708 Mon Sep 17 00:00:00 2001 From: Sean Klein Date: Wed, 22 Oct 2025 14:52:45 -0700 Subject: [PATCH 1/4] update capacity docs --- tokio/src/sync/mpsc/bounded.rs | 24 ++++++++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) diff --git a/tokio/src/sync/mpsc/bounded.rs b/tokio/src/sync/mpsc/bounded.rs index 4fc300ca4e3..b197c3f8d80 100644 --- a/tokio/src/sync/mpsc/bounded.rs +++ b/tokio/src/sync/mpsc/bounded.rs @@ -546,10 +546,18 @@ impl Receiver { self.chan.len() } - /// Returns the current capacity of the channel. + /// Returns the current number of reservations which can immediately be + /// returned from the channel. /// /// The capacity goes down when the sender sends a value by calling [`Sender::send`] or by reserving - /// capacity with [`Sender::reserve`]. The capacity goes up when values are received. + /// capacity with [`Sender::reserve`]. + /// + /// The capacity goes up when values are received, unless there are + /// existing, uncancelled calls to [`Sender::send`] or [`Sender::reserve`] + /// which have returned [`Poll::Pending`]. While those calls exist, reading + /// values from the [`Receiver`] gives access to a channel slot directly to + /// those callers, in FIFO order, without modifying the capacity. + /// /// This is distinct from [`max_capacity`], which always returns buffer capacity initially /// specified when calling [`channel`]. /// @@ -1502,10 +1510,18 @@ impl Sender { self.chan.same_channel(&other.chan) } - /// Returns the current capacity of the channel. + /// Returns the current number of reservations which can immediately be + /// returned from the channel. /// /// The capacity goes down when sending a value by calling [`send`] or by reserving capacity - /// with [`reserve`]. The capacity goes up when values are received by the [`Receiver`]. + /// with [`reserve`]. + /// + /// The capacity goes up when values are received, unless there are + /// existing, uncancelled calls to [`Sender::send`] or [`Sender::reserve`] + /// which have returned [`Poll::Pending`]. While those calls exist, reading + /// values from the [`Receiver`] gives access to a channel slot directly to + /// those callers, in FIFO order, without modifying the capacity. + /// /// This is distinct from [`max_capacity`], which always returns buffer capacity initially /// specified when calling [`channel`] /// From c00465d744f0e0eba0e0f7eeca4395c45a4935cd Mon Sep 17 00:00:00 2001 From: Sean Klein Date: Wed, 22 Oct 2025 15:05:23 -0700 Subject: [PATCH 2/4] non-cancelled --- tokio/src/sync/mpsc/bounded.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tokio/src/sync/mpsc/bounded.rs b/tokio/src/sync/mpsc/bounded.rs index b197c3f8d80..a5fa64f3ce4 100644 --- a/tokio/src/sync/mpsc/bounded.rs +++ b/tokio/src/sync/mpsc/bounded.rs @@ -553,7 +553,7 @@ impl Receiver { /// capacity with [`Sender::reserve`]. /// /// The capacity goes up when values are received, unless there are - /// existing, uncancelled calls to [`Sender::send`] or [`Sender::reserve`] + /// existing, non-cancelled calls to [`Sender::send`] or [`Sender::reserve`] /// which have returned [`Poll::Pending`]. While those calls exist, reading /// values from the [`Receiver`] gives access to a channel slot directly to /// those callers, in FIFO order, without modifying the capacity. @@ -1517,7 +1517,7 @@ impl Sender { /// with [`reserve`]. /// /// The capacity goes up when values are received, unless there are - /// existing, uncancelled calls to [`Sender::send`] or [`Sender::reserve`] + /// existing, non-cancelled calls to [`Sender::send`] or [`Sender::reserve`] /// which have returned [`Poll::Pending`]. While those calls exist, reading /// values from the [`Receiver`] gives access to a channel slot directly to /// those callers, in FIFO order, without modifying the capacity. From bf20392b595cd2316a8a7049763954ab66d7f705 Mon Sep 17 00:00:00 2001 From: Sean Klein Date: Thu, 23 Oct 2025 10:07:14 -0700 Subject: [PATCH 3/4] one more clarification - access to a slot is not granted, just the capacity. Tested this with a larger saturated mpsc --- tokio/src/sync/mpsc/bounded.rs | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/tokio/src/sync/mpsc/bounded.rs b/tokio/src/sync/mpsc/bounded.rs index a5fa64f3ce4..705a96c5d69 100644 --- a/tokio/src/sync/mpsc/bounded.rs +++ b/tokio/src/sync/mpsc/bounded.rs @@ -555,8 +555,8 @@ impl Receiver { /// The capacity goes up when values are received, unless there are /// existing, non-cancelled calls to [`Sender::send`] or [`Sender::reserve`] /// which have returned [`Poll::Pending`]. While those calls exist, reading - /// values from the [`Receiver`] gives access to a channel slot directly to - /// those callers, in FIFO order, without modifying the capacity. + /// values from the [`Receiver`] transfers access to that capacity directly to + /// those callers, in FIFO order. /// /// This is distinct from [`max_capacity`], which always returns buffer capacity initially /// specified when calling [`channel`]. @@ -1519,11 +1519,11 @@ impl Sender { /// The capacity goes up when values are received, unless there are /// existing, non-cancelled calls to [`Sender::send`] or [`Sender::reserve`] /// which have returned [`Poll::Pending`]. While those calls exist, reading - /// values from the [`Receiver`] gives access to a channel slot directly to - /// those callers, in FIFO order, without modifying the capacity. + /// values from the [`Receiver`] transfers access to that capacity directly to + /// those callers, in FIFO order. /// /// This is distinct from [`max_capacity`], which always returns buffer capacity initially - /// specified when calling [`channel`] + /// specified when calling [`channel`]. /// /// # Examples /// From 27a0887577b7427544ed69c295fa6c4b7479cafc Mon Sep 17 00:00:00 2001 From: Sean Klein Date: Thu, 23 Oct 2025 10:16:51 -0700 Subject: [PATCH 4/4] complete -> granted capacity --- tokio/src/sync/mpsc/bounded.rs | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/tokio/src/sync/mpsc/bounded.rs b/tokio/src/sync/mpsc/bounded.rs index 705a96c5d69..a796c67e968 100644 --- a/tokio/src/sync/mpsc/bounded.rs +++ b/tokio/src/sync/mpsc/bounded.rs @@ -792,8 +792,8 @@ impl Sender { /// 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 - /// `send` makes you lose your place in the queue. + /// are granted capacity in the order they were requested. Cancelling a + /// call to `send` makes you lose your place in the queue. /// /// # Examples /// @@ -1095,8 +1095,8 @@ impl Sender { /// # Cancel safety /// /// This channel uses a queue to ensure that calls to `send` and `reserve` - /// complete in the order they were requested. Cancelling a call to - /// `reserve` makes you lose your place in the queue. + /// are granted capacity in the order they were requested. Cancelling a + /// call to `reserve` makes you lose your place in the queue. /// /// # Examples /// @@ -1151,7 +1151,7 @@ impl Sender { /// # Cancel safety /// /// This channel uses a queue to ensure that calls to `send` and `reserve_many` - /// complete in the order they were requested. Cancelling a call to + /// are granted capacity in the order they were requested. Cancelling a call to /// `reserve_many` makes you lose your place in the queue. /// /// # Examples @@ -1214,8 +1214,8 @@ impl Sender { /// # Cancel safety /// /// This channel uses a queue to ensure that calls to `send` and `reserve` - /// complete in the order they were requested. Cancelling a call to - /// `reserve_owned` makes you lose your place in the queue. + /// are granted capacity in the order they were requested. Cancelling a + /// call to `reserve_owned` makes you lose your place in the queue. /// /// # Examples /// Sending a message using an [`OwnedPermit`]: