diff options
Diffstat (limited to 'src/sync/mpsc/mod.rs')
| -rw-r--r-- | src/sync/mpsc/mod.rs | 39 |
1 files changed, 24 insertions, 15 deletions
diff --git a/src/sync/mpsc/mod.rs b/src/sync/mpsc/mod.rs index c489c9f..a2bcf83 100644 --- a/src/sync/mpsc/mod.rs +++ b/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 @@ -43,11 +49,10 @@ //! are two situations to consider: //! //! **Bounded channel**: If you need a bounded channel, you should use a bounded -//! Tokio `mpsc` channel for both directions of communication. To call the async -//! [`send`][bounded-send] or [`recv`][bounded-recv] methods in sync code, you -//! will need to use [`Handle::block_on`], which allow you to execute an async -//! method in synchronous code. This is necessary because a bounded channel may -//! need to wait for additional capacity to become available. +//! Tokio `mpsc` channel for both directions of communication. Instead of calling +//! the async [`send`][bounded-send] or [`recv`][bounded-recv] methods, in +//! synchronous code you will need to use the [`blocking_send`][blocking-send] or +//! [`blocking_recv`][blocking-recv] methods. //! //! **Unbounded channel**: You should use the kind of channel that matches where //! the receiver is. So for sending a message _from async to sync_, you should @@ -57,9 +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 @@ -67,7 +76,7 @@ pub(super) mod block; mod bounded; -pub use self::bounded::{channel, Receiver, Sender}; +pub use self::bounded::{channel, Permit, Receiver, Sender}; mod chan; |