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 //! 25 //! # Disconnection 26 //! 27 //! When all [`Sender`] handles have been dropped, it is no longer 28 //! possible to send values into the channel. This is considered the termination 29 //! event of the stream. As such, `Receiver::poll` returns `Ok(Ready(None))`. 30 //! 31 //! If the [`Receiver`] handle is dropped, then messages can no longer 32 //! be read out of the channel. In this case, all further attempts to send will 33 //! result in an error. 34 //! 35 //! # Clean Shutdown 36 //! 37 //! When the [`Receiver`] is dropped, it is possible for unprocessed messages to 38 //! remain in the channel. Instead, it is usually desirable to perform a "clean" 39 //! shutdown. To do this, the receiver first calls `close`, which will prevent 40 //! any further messages to be sent into the channel. Then, the receiver 41 //! consumes the channel to completion, at which point the receiver can be 42 //! dropped. 43 //! 44 //! # Communicating between sync and async code 45 //! 46 //! When you want to communicate between synchronous and asynchronous code, there 47 //! are two situations to consider: 48 //! 49 //! **Bounded channel**: If you need a bounded channel, you should use a bounded 50 //! Tokio `mpsc` channel for both directions of communication. Instead of calling 51 //! the async [`send`][bounded-send] or [`recv`][bounded-recv] methods, in 52 //! synchronous code you will need to use the [`blocking_send`][blocking-send] or 53 //! [`blocking_recv`][blocking-recv] methods. 54 //! 55 //! **Unbounded channel**: You should use the kind of channel that matches where 56 //! the receiver is. So for sending a message _from async to sync_, you should 57 //! use [the standard library unbounded channel][std-unbounded] or 58 //! [crossbeam][crossbeam-unbounded]. Similarly, for sending a message _from sync 59 //! to async_, you should use an unbounded Tokio `mpsc` channel. 60 //! 61 //! [`Sender`]: crate::sync::mpsc::Sender 62 //! [`Receiver`]: crate::sync::mpsc::Receiver 63 //! [bounded-send]: crate::sync::mpsc::Sender::send() 64 //! [bounded-recv]: crate::sync::mpsc::Receiver::recv() 65 //! [blocking-send]: crate::sync::mpsc::Sender::blocking_send() 66 //! [blocking-recv]: crate::sync::mpsc::Receiver::blocking_recv() 67 //! [`UnboundedSender`]: crate::sync::mpsc::UnboundedSender 68 //! [`UnboundedReceiver`]: crate::sync::mpsc::UnboundedReceiver 69 //! [`Handle::block_on`]: crate::runtime::Handle::block_on() 70 //! [std-unbounded]: std::sync::mpsc::channel 71 //! [crossbeam-unbounded]: https://docs.rs/crossbeam/*/crossbeam/channel/fn.unbounded.html 72 73 pub(super) mod block; 74 75 mod bounded; 76 pub use self::bounded::{channel, Permit, Receiver, Sender}; 77 78 mod chan; 79 80 pub(super) mod list; 81 82 mod unbounded; 83 pub use self::unbounded::{unbounded_channel, UnboundedReceiver, UnboundedSender}; 84 85 pub mod error; 86 87 /// The number of values a block can contain. 88 /// 89 /// This value must be a power of 2. It also must be smaller than the number of 90 /// bits in `usize`. 91 #[cfg(all(target_pointer_width = "64", not(loom)))] 92 const BLOCK_CAP: usize = 32; 93 94 #[cfg(all(not(target_pointer_width = "64"), not(loom)))] 95 const BLOCK_CAP: usize = 16; 96 97 #[cfg(loom)] 98 const BLOCK_CAP: usize = 2; 99