Module futures::sync::mpsc

A multi-producer, single-consumer, futures-aware, FIFO queue with back pressure.

A channel can be used as a communication primitive between tasks running on futures-rs executors. 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 notified 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, then send will be rejected and the task will be notified when additional capacity is available.

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, Sender::poll 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, a 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

Execute

Type of future which Executor instances must be able to execute for spawn.

Receiver

The receiving end of a channel which implements the Stream trait.

SendError

Error type for sending, used when the receiving end of a channel is dropped

Sender

The transmission end of a channel which is used to send values.

SpawnHandle

Handle returned from the spawn function.

TrySendError

Error type returned from try_send

UnboundedReceiver

The receiving end of a channel which implements the Stream trait.

UnboundedSender

The transmission end of a channel which is used to send values.

Functions

channel

Creates an in-memory channel implementation of the Stream trait with bounded capacity.

spawn

Spawns a stream onto the instance of Executor provided, executor, returning a handle representing the remote stream.

spawn_unbounded

Spawns a stream onto the instance of Executor provided, executor, returning a handle representing the remote stream, with unbounded buffering.

unbounded

Creates an in-memory channel implementation of the Stream trait with unbounded capacity.