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. 37 //! 38 //! # Clean Shutdown 39 //! 40 //! When the [`Receiver`] is dropped, it is possible for unprocessed messages to 41 //! remain in the channel. Instead, it is usually desirable to perform a "clean" 42 //! shutdown. To do this, the receiver first calls `close`, which will prevent 43 //! any further messages to be sent into the channel. Then, the receiver 44 //! consumes the channel to completion, at which point the receiver can be 45 //! dropped. 46 //! 47 //! # Communicating between sync and async code 48 //! 49 //! When you want to communicate between synchronous and asynchronous code, there 50 //! are two situations to consider: 51 //! 52 //! **Bounded channel**: If you need a bounded channel, you should use a bounded 53 //! Tokio `mpsc` channel for both directions of communication. Instead of calling 54 //! the async [`send`][bounded-send] or [`recv`][bounded-recv] methods, in 55 //! synchronous code you will need to use the [`blocking_send`][blocking-send] or 56 //! [`blocking_recv`][blocking-recv] methods. 57 //! 58 //! **Unbounded channel**: You should use the kind of channel that matches where 59 //! the receiver is. So for sending a message _from async to sync_, you should 60 //! use [the standard library unbounded channel][std-unbounded] or 61 //! [crossbeam][crossbeam-unbounded]. Similarly, for sending a message _from sync 62 //! to async_, you should use an unbounded Tokio `mpsc` channel. 63 //! 64 //! Please be aware that the above remarks were written with the `mpsc` channel 65 //! in mind, but they can also be generalized to other kinds of channels. In 66 //! general, any channel method that isn't marked async can be called anywhere, 67 //! including outside of the runtime. For example, sending a message on a 68 //! [oneshot] channel from outside the runtime is perfectly fine. 69 //! 70 //! # Multiple runtimes 71 //! 72 //! The mpsc channel does not care about which runtime you use it in, and can be 73 //! used to send messages from one runtime to another. It can also be used in 74 //! non-Tokio runtimes. 75 //! 76 //! There is one exception to the above: the [`send_timeout`] must be used from 77 //! within a Tokio runtime, however it is still not tied to one specific Tokio 78 //! runtime, and the sender may be moved from one Tokio runtime to another. 79 //! 80 //! [`Sender`]: crate::sync::mpsc::Sender 81 //! [`Receiver`]: crate::sync::mpsc::Receiver 82 //! [bounded-send]: crate::sync::mpsc::Sender::send() 83 //! [bounded-recv]: crate::sync::mpsc::Receiver::recv() 84 //! [blocking-send]: crate::sync::mpsc::Sender::blocking_send() 85 //! [blocking-recv]: crate::sync::mpsc::Receiver::blocking_recv() 86 //! [`UnboundedSender`]: crate::sync::mpsc::UnboundedSender 87 //! [`UnboundedReceiver`]: crate::sync::mpsc::UnboundedReceiver 88 //! [oneshot]: crate::sync::oneshot 89 //! [`Handle::block_on`]: crate::runtime::Handle::block_on() 90 //! [std-unbounded]: std::sync::mpsc::channel 91 //! [crossbeam-unbounded]: https://docs.rs/crossbeam/*/crossbeam/channel/fn.unbounded.html 92 //! [`send_timeout`]: crate::sync::mpsc::Sender::send_timeout 93 94 pub(super) mod block; 95 96 mod bounded; 97 pub use self::bounded::{channel, OwnedPermit, Permit, Receiver, Sender, WeakSender}; 98 99 mod chan; 100 101 pub(super) mod list; 102 103 mod unbounded; 104 pub use self::unbounded::{ 105 unbounded_channel, UnboundedReceiver, UnboundedSender, WeakUnboundedSender, 106 }; 107 108 pub mod error; 109 110 /// The number of values a block can contain. 111 /// 112 /// This value must be a power of 2. It also must be smaller than the number of 113 /// bits in `usize`. 114 #[cfg(all(target_pointer_width = "64", not(loom)))] 115 const BLOCK_CAP: usize = 32; 116 117 #[cfg(all(not(target_pointer_width = "64"), not(loom)))] 118 const BLOCK_CAP: usize = 16; 119 120 #[cfg(loom)] 121 const BLOCK_CAP: usize = 2; 122