From cfb4895c0be5024145f7d8a2043b8c2df6110488 Mon Sep 17 00:00:00 2001 From: Daksh Date: Fri, 12 Aug 2022 04:53:41 +0530 Subject: [PATCH 1/9] channel: add max_capacity method Fixes: #4792 --- tokio/src/sync/mpsc/bounded.rs | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/tokio/src/sync/mpsc/bounded.rs b/tokio/src/sync/mpsc/bounded.rs index 47d7938158a..ed0c72fdf57 100644 --- a/tokio/src/sync/mpsc/bounded.rs +++ b/tokio/src/sync/mpsc/bounded.rs @@ -1036,6 +1036,36 @@ impl Sender { chan: self.chan.downgrade(), } } + + /// Returns the max buffer capacity of the channel. + /// + /// The max capacity is the buffer capacity you initially specified with [`channel`] + /// + /// # Examples + /// + /// ``` + /// use tokio::sync::mpsc; + /// + /// #[tokio::main] + /// async fn main() { + /// let (tx, rx) = mpsc::channel::<()>(5); + /// + /// // both max capacity and capacity are the same at first + /// assert_eq!(tx.max_capacity(), 5); + /// assert_eq!(tx.capacity(), 5); + /// + /// // Making a reservation doesn't change the max capacity. + /// let permit = tx.reserve().await.unwrap(); + /// assert_eq!(tx.max_capacity(), 5); + /// // but drops the capacity by one + /// assert_eq!(tx.capacity(), 4); + /// } + /// ``` + /// + /// [`channel`]: channel + pub fn max_capacity(&self) -> usize { + self.chan.semaphore().1 + } } impl Clone for Sender { From ec9b28f5fdba789d5e59bbdd2a1ab3ecd6722778 Mon Sep 17 00:00:00 2001 From: Daksh Date: Fri, 12 Aug 2022 05:16:25 +0530 Subject: [PATCH 2/9] Run cargo test with TRYBUILD=overwrite --- tests-build/tests/fail/macros_dead_code.stderr | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tests-build/tests/fail/macros_dead_code.stderr b/tests-build/tests/fail/macros_dead_code.stderr index 816c294bd31..256ecb24be6 100644 --- a/tests-build/tests/fail/macros_dead_code.stderr +++ b/tests-build/tests/fail/macros_dead_code.stderr @@ -1,11 +1,11 @@ -error: function is never used: `f` - --> $DIR/macros_dead_code.rs:6:10 +error: function `f` is never used + --> tests/fail/macros_dead_code.rs:6:10 | 6 | async fn f() {} | ^ | note: the lint level is defined here - --> $DIR/macros_dead_code.rs:1:9 + --> tests/fail/macros_dead_code.rs:1:9 | 1 | #![deny(dead_code)] | ^^^^^^^^^ From c82e6fbe83515c93c5166f5f33bd56ca17ade8b6 Mon Sep 17 00:00:00 2001 From: Daksh Date: Fri, 12 Aug 2022 16:56:49 +0530 Subject: [PATCH 3/9] Reverse missfix --- tests-build/tests/fail/macros_dead_code.stderr | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tests-build/tests/fail/macros_dead_code.stderr b/tests-build/tests/fail/macros_dead_code.stderr index 256ecb24be6..816c294bd31 100644 --- a/tests-build/tests/fail/macros_dead_code.stderr +++ b/tests-build/tests/fail/macros_dead_code.stderr @@ -1,11 +1,11 @@ -error: function `f` is never used - --> tests/fail/macros_dead_code.rs:6:10 +error: function is never used: `f` + --> $DIR/macros_dead_code.rs:6:10 | 6 | async fn f() {} | ^ | note: the lint level is defined here - --> tests/fail/macros_dead_code.rs:1:9 + --> $DIR/macros_dead_code.rs:1:9 | 1 | #![deny(dead_code)] | ^^^^^^^^^ From 2454d9854d9277314d6de5f49869d49c90106722 Mon Sep 17 00:00:00 2001 From: Daksh Date: Fri, 12 Aug 2022 17:15:33 +0530 Subject: [PATCH 4/9] minor wording fix --- tokio/src/sync/mpsc/bounded.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/tokio/src/sync/mpsc/bounded.rs b/tokio/src/sync/mpsc/bounded.rs index ed0c72fdf57..f6e96d7ed45 100644 --- a/tokio/src/sync/mpsc/bounded.rs +++ b/tokio/src/sync/mpsc/bounded.rs @@ -1039,7 +1039,8 @@ impl Sender { /// Returns the max buffer capacity of the channel. /// - /// The max capacity is the buffer capacity you initially specified with [`channel`] + /// The max capacity is the buffer capacity initially specified when calling + /// [`channel`] /// /// # Examples /// From a4f8512914460e87fa40d21421218e2da5efbeb0 Mon Sep 17 00:00:00 2001 From: Daksh Date: Fri, 12 Aug 2022 19:32:46 +0530 Subject: [PATCH 5/9] tests: add bounded channel capacity and max_capacity tests --- tokio/tests/sync_mpsc.rs | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/tokio/tests/sync_mpsc.rs b/tokio/tests/sync_mpsc.rs index aebdf8548d8..ee4ff9324e4 100644 --- a/tokio/tests/sync_mpsc.rs +++ b/tokio/tests/sync_mpsc.rs @@ -921,3 +921,17 @@ async fn test_tx_count_weak_sender() { assert!(tx_weak.upgrade().is_none() && tx_weak2.upgrade().is_none()); } + +// Tests that channel `capacity` changes and `max_capacity` stays the same +#[tokio::test] +async fn test_tx_capacity() { + let (tx, _rx) = mpsc::channel::<()>(10); + // both capacities are same before + assert_eq!(tx.capacity(), 10); + assert_eq!(tx.max_capacity(), 10); + + let _permit = tx.reserve().await.unwrap(); + // after reserve, only capacity should drop by one + assert_eq!(tx.capacity(), 9); + assert_eq!(tx.max_capacity(), 10); +} From dc32a826cd5aa4530ce41c6a6f24925d59e17c5c Mon Sep 17 00:00:00 2001 From: Daksh Date: Fri, 12 Aug 2022 19:34:05 +0530 Subject: [PATCH 6/9] Add period in docs --- tokio/src/sync/mpsc/bounded.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tokio/src/sync/mpsc/bounded.rs b/tokio/src/sync/mpsc/bounded.rs index f6e96d7ed45..0008d166fe5 100644 --- a/tokio/src/sync/mpsc/bounded.rs +++ b/tokio/src/sync/mpsc/bounded.rs @@ -1040,7 +1040,7 @@ impl Sender { /// Returns the max buffer capacity of the channel. /// /// The max capacity is the buffer capacity initially specified when calling - /// [`channel`] + /// [`channel`]. /// /// # Examples /// From a88fb0f1f89ce75abc1b817d034b96546f2f8350 Mon Sep 17 00:00:00 2001 From: Daksh Date: Sat, 13 Aug 2022 00:35:06 +0530 Subject: [PATCH 7/9] docs: Refine max_capacity and capacity docs to be more informative tests: test max_capacity and capacity using Sender::send --- tokio/src/sync/mpsc/bounded.rs | 16 +++++++++++++--- tokio/tests/sync_mpsc.rs | 5 +++++ 2 files changed, 18 insertions(+), 3 deletions(-) diff --git a/tokio/src/sync/mpsc/bounded.rs b/tokio/src/sync/mpsc/bounded.rs index 0008d166fe5..fc2d1f50b6a 100644 --- a/tokio/src/sync/mpsc/bounded.rs +++ b/tokio/src/sync/mpsc/bounded.rs @@ -998,6 +998,8 @@ impl Sender { /// /// 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`]. + /// This is distinct from [`max_capacity`], which always returns buffer capacity initially + /// specified when calling [`channel`] /// /// # Examples /// @@ -1023,6 +1025,8 @@ impl Sender { /// /// [`send`]: Sender::send /// [`reserve`]: Sender::reserve + /// [`channel`]: channel + /// [`max_capacity`]: Sender::max_capacity pub fn capacity(&self) -> usize { self.chan.semaphore().0.available_permits() } @@ -1037,10 +1041,14 @@ impl Sender { } } - /// Returns the max buffer capacity of the channel. + /// Returns the maximum buffer capacity of the channel. /// - /// The max capacity is the buffer capacity initially specified when calling - /// [`channel`]. + /// The maximum capacity is the buffer capacity initially specified when calling + /// [`channel`]. This is distinct from [`capacity`], which returns the *current* + /// available buffer capacity: as messages are sent and received, the + /// value returned by [`capacity`] will go up or down, while `max_capacity` + /// will always return maximum capacity that was set when the channel was + /// created. /// /// # Examples /// @@ -1064,6 +1072,8 @@ impl Sender { /// ``` /// /// [`channel`]: channel + /// [`max_capacity`]: Sender::max_capacity + /// [`capacity`]: Sender::capacity pub fn max_capacity(&self) -> usize { self.chan.semaphore().1 } diff --git a/tokio/tests/sync_mpsc.rs b/tokio/tests/sync_mpsc.rs index ee4ff9324e4..24f078c62b1 100644 --- a/tokio/tests/sync_mpsc.rs +++ b/tokio/tests/sync_mpsc.rs @@ -934,4 +934,9 @@ async fn test_tx_capacity() { // after reserve, only capacity should drop by one assert_eq!(tx.capacity(), 9); assert_eq!(tx.max_capacity(), 10); + + let _sent = tx.send(()).await.unwrap(); + // after send, capacity should drop by one again + assert_eq!(tx.capacity(), 8); + assert_eq!(tx.max_capacity(), 10); } From 26f04b844ae0a7cb6b598c2fd8209ff24c6be95d Mon Sep 17 00:00:00 2001 From: Daksh Date: Sat, 13 Aug 2022 03:09:48 +0530 Subject: [PATCH 8/9] prefix rx with underscore --- tokio/src/sync/mpsc/bounded.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tokio/src/sync/mpsc/bounded.rs b/tokio/src/sync/mpsc/bounded.rs index fc2d1f50b6a..262441db3a7 100644 --- a/tokio/src/sync/mpsc/bounded.rs +++ b/tokio/src/sync/mpsc/bounded.rs @@ -1057,7 +1057,7 @@ impl Sender { /// /// #[tokio::main] /// async fn main() { - /// let (tx, rx) = mpsc::channel::<()>(5); + /// let (tx, _rx) = mpsc::channel::<()>(5); /// /// // both max capacity and capacity are the same at first /// assert_eq!(tx.max_capacity(), 5); From 95fe056aea50acbe4eb66ac1e1fcedbb756b9f19 Mon Sep 17 00:00:00 2001 From: Daksh Date: Sun, 14 Aug 2022 18:57:57 +0530 Subject: [PATCH 9/9] docs: minor suggestion --- tokio/src/sync/mpsc/bounded.rs | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/tokio/src/sync/mpsc/bounded.rs b/tokio/src/sync/mpsc/bounded.rs index 262441db3a7..e5514277f6c 100644 --- a/tokio/src/sync/mpsc/bounded.rs +++ b/tokio/src/sync/mpsc/bounded.rs @@ -1046,9 +1046,8 @@ impl Sender { /// The maximum capacity is the buffer capacity initially specified when calling /// [`channel`]. This is distinct from [`capacity`], which returns the *current* /// available buffer capacity: as messages are sent and received, the - /// value returned by [`capacity`] will go up or down, while `max_capacity` - /// will always return maximum capacity that was set when the channel was - /// created. + /// value returned by [`capacity`] will go up or down, whereas the value + /// returned by `max_capacity` will remain constant. /// /// # Examples ///