Module mpsc

A multi-producer, single-consumer queue for sending values across asynchronous tasks.

Similarly to the 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 from the channel, the current task will be awoken when a new value is sent. Sender implements the Sink trait and allows a task to send messages into the channel. If the channel is at capacity, the send will be rejected and the task will be awoken when additional capacity is available. This process of delaying sends beyond a certain capacity is often referred to as “backpressure”.

Unbounded channels (without backpressure) are also available using the unbounded function.

Disconnection

When all Senders 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_next will return 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

If the Receiver is simply dropped, then it is possible for there to be messages still in the channel that will not be processed. As such, it is usually desirable to perform a “clean” shutdown. To do this, the receiver will first call 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.

Structs

• Receiver
  The receiving end of a bounded mpsc channel.
• SendError
  The error type for Senders used as Sinks.
• Sender
  The transmission end of a bounded mpsc channel.
• TryRecvError
  The error type returned from try_next.
• TrySendError
  The error type returned from try_send.
• UnboundedReceiver
  The receiving end of an unbounded mpsc channel.
• UnboundedSender
  The transmission end of an unbounded mpsc channel.

Functions

• channel
  Creates a bounded mpsc channel for communicating between asynchronous tasks.
• unbounded
  Creates an unbounded mpsc channel for communicating between asynchronous tasks.