sync: document mpsc::bounded minimum buffer size (#2808)

3 files changed, 28 insertions, 12 deletions

diff --git a/tokio/src/sync/mpsc/bounded.rs b/tokio/src/sync/mpsc/bounded.rs
index c7ecd9fc..14e4731a 100644
--- a/tokio/src/sync/mpsc/bounded.rs
+++ b/tokio/src/sync/mpsc/bounded.rs
@@ -49,8 +49,12 @@ impl<T> fmt::Debug for Receiver<T> {
     }
 }
 
-/// Creates a bounded mpsc channel for communicating between asynchronous tasks,
-/// returning the sender/receiver halves.
+/// Creates a bounded mpsc channel for communicating between asynchronous tasks
+/// with backpressure.
+///
+/// The channel will buffer up to the provided number of messages.  Once the
+/// buffer is full, attempts to `send` new messages will wait until a message is
+/// received from the channel. The provided buffer capacity must be at least 1.
 ///
 /// All data sent on `Sender` will become available on `Receiver` in the same
 /// order as it was sent.
@@ -62,6 +66,10 @@ impl<T> fmt::Debug for Receiver<T> {
 /// will return a `SendError`. Similarly, if `Sender` is disconnected while
 /// trying to `recv`, the `recv` method will return a `RecvError`.
 ///
+/// # Panics
+///
+/// Panics if the buffer capacity is 0.
+///
 /// # Examples
 ///
 /// ```rust
diff --git a/tokio/src/sync/mpsc/mod.rs b/tokio/src/sync/mpsc/mod.rs
index b9599131..7e663da8 100644
--- a/tokio/src/sync/mpsc/mod.rs
+++ b/tokio/src/sync/mpsc/mod.rs
@@ -1,23 +1,29 @@
 #![cfg_attr(not(feature = "sync"), allow(dead_code, unreachable_pub))]
 
-//! A multi-producer, single-consumer queue for sending values across
+//! A multi-producer, single-consumer queue for sending values between
 //! asynchronous tasks.
 //!
-//! Similar to `std`, channel creation provides [`Receiver`] and [`Sender`]
-//! handles. [`Receiver`] implements `Stream` and allows a task to read values
-//! out of the channel. If there is no message to read, the current task will be
-//! notified when a new value is sent. If the channel is at capacity, the send
-//! is rejected and the task will be notified when additional capacity is
-//! available. In other words, the channel provides backpressure.
-//!
 //! This module provides two variants of the channel: bounded and unbounded. The
 //! bounded variant has a limit on the number of messages that the channel can
 //! store, and if this limit is reached, trying to send another message will
 //! wait until a message is received from the channel. An unbounded channel has
-//! an infinite capacity, so the `send` method never does any kind of sleeping.
+//! an infinite capacity, so the `send` method will always complete immediately.
 //! This makes the [`UnboundedSender`] usable from both synchronous and
 //! asynchronous code.
 //!
+//! Similar to the `mpsc` channels provided by `std`, the channel constructor
+//! functions provide separate send and receive handles, [`Sender`] and
+//! [`Receiver`] for the bounded channel, [`UnboundedSender`] and
+//! [`UnboundedReceiver`] for the unbounded channel. Both [`Receiver`] and
+//! [`UnboundedReceiver`] implement [`Stream`] and allow a task to read
+//! values out of the channel. If there is no message to read, the current task
+//! will be notified when a new value is sent. [`Sender`] and
+//! [`UnboundedSender`] allow sending values into the channel. If the bounded
+//! channel is at capacity, the send is rejected and the task will be notified
+//! when additional capacity is available. In other words, the channel provides
+//! backpressure.
+//!
+//!
 //! # Disconnection
 //!
 //! When all [`Sender`] handles have been dropped, it is no longer
@@ -56,11 +62,13 @@
 //!
 //! [`Sender`]: crate::sync::mpsc::Sender
 //! [`Receiver`]: crate::sync::mpsc::Receiver
+//! [`Stream`]: crate::stream::Stream
 //! [bounded-send]: crate::sync::mpsc::Sender::send()
 //! [bounded-recv]: crate::sync::mpsc::Receiver::recv()
 //! [blocking-send]: crate::sync::mpsc::Sender::blocking_send()
 //! [blocking-recv]: crate::sync::mpsc::Receiver::blocking_recv()
 //! [`UnboundedSender`]: crate::sync::mpsc::UnboundedSender
+//! [`UnboundedReceiver`]: crate::sync::mpsc::UnboundedReceiver
 //! [`Handle::block_on`]: crate::runtime::Handle::block_on()
 //! [std-unbounded]: std::sync::mpsc::channel
 //! [crossbeam-unbounded]: https://docs.rs/crossbeam/*/crossbeam/channel/fn.unbounded.html
diff --git a/tokio/src/sync/mpsc/unbounded.rs b/tokio/src/sync/mpsc/unbounded.rs
index 1b2288ab..6b2ca722 100644
--- a/tokio/src/sync/mpsc/unbounded.rs
+++ b/tokio/src/sync/mpsc/unbounded.rs
@@ -47,7 +47,7 @@ impl<T> fmt::Debug for UnboundedReceiver<T> {
 }
 
 /// Creates an unbounded mpsc channel for communicating between asynchronous
-/// tasks.
+/// tasks without backpressure.
 ///
 /// A `send` on this channel will always succeed as long as the receive half has
 /// not been closed. If the receiver falls behind, messages will be arbitrarily