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 95 pub(super) mod block; 96 97 mod bounded; 98 pub use self::bounded::{channel, OwnedPermit, Permit, Receiver, Sender, WeakSender}; 99 100 mod chan; 101 102 pub(super) mod list; 103 104 mod unbounded; 105 pub use self::unbounded::{ 106 unbounded_channel, UnboundedReceiver, UnboundedSender, WeakUnboundedSender, 107 }; 108 109 pub 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)))] 116 const BLOCK_CAP: usize = 32; 117 118 #[cfg(all(not(target_pointer_width = "64"), not(loom)))] 119 const BLOCK_CAP: usize = 16; 120 121 #[cfg(loom)] 122 const BLOCK_CAP: usize = 2; 123