From 45311e1afac906651401dd2274b0a3df3d038e39 Mon Sep 17 00:00:00 2001 From: Quinn Okabayashi Date: Sat, 26 Feb 2022 22:46:41 -0500 Subject: [PATCH 1/3] Updated unbounded channel docs --- tokio/src/sync/mpsc/unbounded.rs | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/tokio/src/sync/mpsc/unbounded.rs b/tokio/src/sync/mpsc/unbounded.rs index b133f9f35e3..356d36be287 100644 --- a/tokio/src/sync/mpsc/unbounded.rs +++ b/tokio/src/sync/mpsc/unbounded.rs @@ -79,8 +79,14 @@ impl UnboundedReceiver { /// Receives the next value for this receiver. /// - /// `None` is returned when all `Sender` halves have dropped, indicating - /// that no further values can be sent on the channel. + /// This method returns `None` if the channel has been closed and there are + /// no remaining messages in the channel's buffer. This indicates that no + /// further values can ever be received from this `Receiver`. The channel is + /// closed when all senders have been dropped, or when [`close`] is called. + /// + /// If there are no messages in the channel's buffer, but the channel has + /// not yet been closed, this method will sleep until a message is sent or + /// the channel is closed. /// /// # Cancel safety /// @@ -207,6 +213,10 @@ impl UnboundedReceiver { /// /// This prevents any further messages from being sent on the channel while /// still enabling the receiver to drain messages that are buffered. + /// + /// Since no more messages can be sent, the receiver will return `None` when + /// polled after the remaining messages have been drained, regardless of + /// whether or not all the senders have been dropped. pub fn close(&mut self) { self.chan.close(); } From ed5c3d9b25bedc524e927a278e1031864d4a18e0 Mon Sep 17 00:00:00 2001 From: Quinn Okabayashi Date: Sat, 26 Feb 2022 22:55:10 -0500 Subject: [PATCH 2/3] Made `close` docs consistent with bounded --- tokio/src/sync/mpsc/unbounded.rs | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/tokio/src/sync/mpsc/unbounded.rs b/tokio/src/sync/mpsc/unbounded.rs index 356d36be287..d31e373c3d8 100644 --- a/tokio/src/sync/mpsc/unbounded.rs +++ b/tokio/src/sync/mpsc/unbounded.rs @@ -214,9 +214,8 @@ impl UnboundedReceiver { /// This prevents any further messages from being sent on the channel while /// still enabling the receiver to drain messages that are buffered. /// - /// Since no more messages can be sent, the receiver will return `None` when - /// polled after the remaining messages have been drained, regardless of - /// whether or not all the senders have been dropped. + /// To guarantee that no messages are dropped, after calling `close()`, + /// `recv()` must be called until `None` is returned. pub fn close(&mut self) { self.chan.close(); } From 872dd50c6b2f25184042306ff9d9ef19054d0bc6 Mon Sep 17 00:00:00 2001 From: Quinn Okabayashi Date: Sun, 27 Feb 2022 09:38:43 -0500 Subject: [PATCH 3/3] Added `close` link + rustfmt fix --- tokio/src/sync/mpsc/unbounded.rs | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/tokio/src/sync/mpsc/unbounded.rs b/tokio/src/sync/mpsc/unbounded.rs index d31e373c3d8..f8338fb0885 100644 --- a/tokio/src/sync/mpsc/unbounded.rs +++ b/tokio/src/sync/mpsc/unbounded.rs @@ -83,7 +83,7 @@ impl UnboundedReceiver { /// no remaining messages in the channel's buffer. This indicates that no /// further values can ever be received from this `Receiver`. The channel is /// closed when all senders have been dropped, or when [`close`] is called. - /// + /// /// If there are no messages in the channel's buffer, but the channel has /// not yet been closed, this method will sleep until a message is sent or /// the channel is closed. @@ -95,6 +95,8 @@ impl UnboundedReceiver { /// completes first, it is guaranteed that no messages were received on this /// channel. /// + /// [`close`]: Self::close + /// /// # Examples /// /// ``` @@ -213,7 +215,7 @@ impl UnboundedReceiver { /// /// This prevents any further messages from being sent on the channel while /// still enabling the receiver to drain messages that are buffered. - /// + /// /// To guarantee that no messages are dropped, after calling `close()`, /// `recv()` must be called until `None` is returned. pub fn close(&mut self) {