Expand description
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 or 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 or
crossbeam. Similarly, for sending a message from sync
to async, you should use an unbounded Tokio mpsc channel.
Modules
Channel error types
Structs
Receive values from the associated Sender.
Send values to the associated Receiver.
Receive values from the associated UnboundedSender.
Send values to the associated UnboundedReceiver.
Functions
Creates a bounded mpsc channel for communicating between asynchronous tasks, returning the sender/receiver halves.
Creates an unbounded mpsc channel for communicating between asynchronous tasks.