tokio_sync/mpsc/mod.rs
1//! A multi-producer, single-consumer queue for sending values across
2//! asynchronous tasks.
3//!
4//! Similar to `std`, channel creation provides [`Receiver`] and [`Sender`]
5//! handles. [`Receiver`] implements `Stream` and allows a task to read values
6//! out of the channel. If there is no message to read, the current task will be
7//! notified when a new value is sent. [`Sender`] implements the `Sink` trait
8//! and allows sending messages into the channel. If the channel is at capacity,
9//! the send is rejected and the task will be notified when additional capacity
10//! is available. In other words, the channel provides backpressure.
11//!
12//! Unbounded channels are also available using the `unbounded_channel`
13//! constructor.
14//!
15//! # Disconnection
16//!
17//! When all [`Sender`] handles have been dropped, it is no longer
18//! possible to send values into the channel. This is considered the termination
19//! event of the stream. As such, `Receiver::poll` returns `Ok(Ready(None))`.
20//!
21//! If the [`Receiver`] handle is dropped, then messages can no longer
22//! be read out of the channel. In this case, all further attempts to send will
23//! result in an error.
24//!
25//! # Clean Shutdown
26//!
27//! When the [`Receiver`] is dropped, it is possible for unprocessed messages to
28//! remain in the channel. Instead, it is usually desirable to perform a "clean"
29//! shutdown. To do this, the receiver first calls `close`, which will prevent
30//! any further messages to be sent into the channel. Then, the receiver
31//! consumes the channel to completion, at which point the receiver can be
32//! dropped.
33//!
34//! [`Sender`]: struct.Sender.html
35//! [`Receiver`]: struct.Receiver.html
36
37mod block;
38mod bounded;
39mod chan;
40mod list;
41mod unbounded;
42
43pub use self::bounded::{channel, Receiver, Sender};
44
45pub use self::unbounded::{unbounded_channel, UnboundedReceiver, UnboundedSender};
46
47pub mod error {
48 //! Channel error types
49
50 pub use super::bounded::{RecvError, SendError, TrySendError};
51
52 pub use super::unbounded::{UnboundedRecvError, UnboundedSendError, UnboundedTrySendError};
53}
54
55/// The number of values a block can contain.
56///
57/// This value must be a power of 2. It also must be smaller than the number of
58/// bits in `usize`.
59#[cfg(target_pointer_width = "64")]
60const BLOCK_CAP: usize = 32;
61
62#[cfg(not(target_pointer_width = "64"))]
63const BLOCK_CAP: usize = 16;