# Module futures::sync::mpsc [−] [src]

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.

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)