1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92
#![cfg_attr(not(feature = "sync"), allow(dead_code, unreachable_pub))] //! A multi-producer, single-consumer queue for sending values across //! 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. //! This makes the [`UnboundedSender`] usable from both synchronous and //! asynchronous code. //! //! # Disconnection //! //! When all [`Sender`] handles have been dropped, it is no longer //! possible to send values into the channel. This is considered the termination //! event of the stream. As such, `Receiver::poll` returns `Ok(Ready(None))`. //! //! If the [`Receiver`] handle is dropped, then messages can no longer //! be read out of the channel. In this case, all further attempts to send will //! result in an error. //! //! # Clean Shutdown //! //! When the [`Receiver`] is dropped, it is possible for unprocessed messages to //! remain in the channel. Instead, it is usually desirable to perform a "clean" //! shutdown. To do this, the receiver first calls `close`, which will prevent //! any further messages to be sent into the channel. Then, the receiver //! consumes the channel to completion, at which point the receiver can be //! dropped. //! //! # Communicating between sync and async code //! //! When you want to communicate between synchronous and asynchronous code, there //! 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. //! //! **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 //! use [the standard library unbounded channel][std-unbounded] or //! [crossbeam][crossbeam-unbounded]. Similarly, for sending a message _from sync //! to async_, you should use an unbounded Tokio `mpsc` channel. //! //! [`Sender`]: crate::sync::mpsc::Sender //! [`Receiver`]: crate::sync::mpsc::Receiver //! [bounded-send]: crate::sync::mpsc::Sender::send() //! [bounded-recv]: crate::sync::mpsc::Receiver::recv() //! [`UnboundedSender`]: crate::sync::mpsc::UnboundedSender //! [`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 pub(super) mod block; mod bounded; pub use self::bounded::{channel, Receiver, Sender}; mod chan; pub(super) mod list; mod unbounded; pub use self::unbounded::{unbounded_channel, UnboundedReceiver, UnboundedSender}; pub mod error; /// The number of values a block can contain. /// /// This value must be a power of 2. It also must be smaller than the number of /// bits in `usize`. #[cfg(all(target_pointer_width = "64", not(loom)))] const BLOCK_CAP: usize = 32; #[cfg(all(not(target_pointer_width = "64"), not(loom)))] const BLOCK_CAP: usize = 16; #[cfg(loom)] const BLOCK_CAP: usize = 2;