diff --git a/tokio/src/sync/mpsc/bounded.rs b/tokio/src/sync/mpsc/bounded.rs index c7ecd9fc6a3..14e4731aaae 100644 --- a/tokio/src/sync/mpsc/bounded.rs +++ b/tokio/src/sync/mpsc/bounded.rs @@ -49,8 +49,12 @@ impl fmt::Debug for Receiver { } } -/// 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 fmt::Debug for Receiver { /// 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 b95991318ec..7e663da89f0 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 1b2288ab08c..6b2ca722729 100644 --- a/tokio/src/sync/mpsc/unbounded.rs +++ b/tokio/src/sync/mpsc/unbounded.rs @@ -47,7 +47,7 @@ impl fmt::Debug for UnboundedReceiver { } /// 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