1#![cfg_attr(not(feature = "sync"), allow(dead_code, unreachable_pub))]
2
3//! A multi-producer, single-consumer queue for sending values between
4//! asynchronous tasks.
5//!
6//! This module provides two variants of the channel: bounded and unbounded. The
7//! bounded variant has a limit on the number of messages that the channel can
8//! store, and if this limit is reached, trying to send another message will
9//! wait until a message is received from the channel. An unbounded channel has
10//! an infinite capacity, so the `send` method will always complete immediately.
11//! This makes the [`UnboundedSender`] usable from both synchronous and
12//! asynchronous code.
13//!
14//! Similar to the `mpsc` channels provided by `std`, the channel constructor
15//! functions provide separate send and receive handles, [`Sender`] and
16//! [`Receiver`] for the bounded channel, [`UnboundedSender`] and
17//! [`UnboundedReceiver`] for the unbounded channel. If there is no message to read,
18//! the current task will be notified when a new value is sent. [`Sender`] and
19//! [`UnboundedSender`] allow sending values into the channel. If the bounded
20//! channel is at capacity, the send is rejected and the task will be notified
21//! when additional capacity is available. In other words, the channel provides
22//! backpressure.
23//!
24//! This channel is also suitable for the single-producer single-consumer
25//! use-case. (Unless you only need to send one message, in which case you
26//! should use the [oneshot] channel.)
27//!
28//! # Disconnection
29//!
30//! When all [`Sender`] handles have been dropped, it is no longer
31//! possible to send values into the channel. This is considered the termination
32//! event of the stream. As such, `Receiver::poll` returns `Ok(Ready(None))`.
33//!
34//! If the [`Receiver`] handle is dropped, then messages can no longer
35//! be read out of the channel. In this case, all further attempts to send will
36//! result in an error. Additionally, all unread messages will be drained from the
37//! channel and dropped.
38//!
39//! # Clean Shutdown
40//!
41//! When the [`Receiver`] is dropped, it is possible for unprocessed messages to
42//! remain in the channel. Instead, it is usually desirable to perform a "clean"
43//! shutdown. To do this, the receiver first calls `close`, which will prevent
44//! any further messages to be sent into the channel. Then, the receiver
45//! consumes the channel to completion, at which point the receiver can be
46//! dropped.
47//!
48//! # Communicating between sync and async code
49//!
50//! When you want to communicate between synchronous and asynchronous code, there
51//! are two situations to consider:
52//!
53//! **Bounded channel**: If you need a bounded channel, you should use a bounded
54//! Tokio `mpsc` channel for both directions of communication. Instead of calling
55//! the async [`send`][bounded-send] or [`recv`][bounded-recv] methods, in
56//! synchronous code you will need to use the [`blocking_send`][blocking-send] or
57//! [`blocking_recv`][blocking-recv] methods.
58//!
59//! **Unbounded channel**: You should use the kind of channel that matches where
60//! the receiver is. So for sending a message _from async to sync_, you should
61//! use [the standard library unbounded channel][std-unbounded] or
62//! [crossbeam][crossbeam-unbounded]. Similarly, for sending a message _from sync
63//! to async_, you should use an unbounded Tokio `mpsc` channel.
64//!
65//! Please be aware that the above remarks were written with the `mpsc` channel
66//! in mind, but they can also be generalized to other kinds of channels. In
67//! general, any channel method that isn't marked async can be called anywhere,
68//! including outside of the runtime. For example, sending a message on a
69//! [oneshot] channel from outside the runtime is perfectly fine.
70//!
71//! # Multiple runtimes
72//!
73//! The mpsc channel does not care about which runtime you use it in, and can be
74//! used to send messages from one runtime to another. It can also be used in
75//! non-Tokio runtimes.
76//!
77//! There is one exception to the above: the [`send_timeout`] must be used from
78//! within a Tokio runtime, however it is still not tied to one specific Tokio
79//! runtime, and the sender may be moved from one Tokio runtime to another.
80//!
81//! [`Sender`]: crate::sync::mpsc::Sender
82//! [`Receiver`]: crate::sync::mpsc::Receiver
83//! [bounded-send]: crate::sync::mpsc::Sender::send()
84//! [bounded-recv]: crate::sync::mpsc::Receiver::recv()
85//! [blocking-send]: crate::sync::mpsc::Sender::blocking_send()
86//! [blocking-recv]: crate::sync::mpsc::Receiver::blocking_recv()
87//! [`UnboundedSender`]: crate::sync::mpsc::UnboundedSender
88//! [`UnboundedReceiver`]: crate::sync::mpsc::UnboundedReceiver
89//! [oneshot]: crate::sync::oneshot
90//! [`Handle::block_on`]: crate::runtime::Handle::block_on()
91//! [std-unbounded]: std::sync::mpsc::channel
92//! [crossbeam-unbounded]: https://docs.rs/crossbeam/*/crossbeam/channel/fn.unbounded.html
93//! [`send_timeout`]: crate::sync::mpsc::Sender::send_timeout
94
95pub(super) mod block;
96
97mod bounded;
98pub use self::bounded::{channel, OwnedPermit, Permit, Receiver, Sender, WeakSender};
99
100mod chan;
101
102pub(super) mod list;
103
104mod unbounded;
105pub use self::unbounded::{
106 unbounded_channel, UnboundedReceiver, UnboundedSender, WeakUnboundedSender,
107};
108
109pub mod error;
110
111/// The number of values a block can contain.
112///
113/// This value must be a power of 2. It also must be smaller than the number of
114/// bits in `usize`.
115#[cfg(all(target_pointer_width = "64", not(loom)))]
116const BLOCK_CAP: usize = 32;
117
118#[cfg(all(not(target_pointer_width = "64"), not(loom)))]
119const BLOCK_CAP: usize = 16;
120
121#[cfg(loom)]
122const BLOCK_CAP: usize = 2;
123