# tokio::sync::mpsc - Rust
API documentation for the Rust `mpsc` mod in crate `tokio`.
Keywords: rust, rustlang, rust-lang, mpsc

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

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

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 will always complete immediately. This makes the `UnboundedSender` usable from both synchronous and asynchronous code.

Similar to the `mpsc` channels provided by `std`, the channel constructor functions provide separate send and receive handles, `Sender` and `Receiver` for the bounded channel, `UnboundedSender` and `UnboundedReceiver` for the unbounded channel. If there is no message to read, the current task will be notified when a new value is sent. `Sender` and `UnboundedSender` allow sending values into the channel. If the bounded 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.

# 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. Instead of calling the async `send` or `recv` methods, in synchronous code you will need to use the `blocking_send` or `blocking_recv` methods.

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

error | Channel error types

## Structs

Permit | Permit to send one value into the channel.
Receiver | Receive values from the associated `Sender`.
Sender | Send values to the associated `Receiver`.
UnboundedReceiver | Receive values from the associated `UnboundedSender`.
UnboundedSender | Send values to the associated `UnboundedReceiver`.

## Functions

channel | Creates a bounded mpsc channel for communicating between asynchronous tasks with backpressure.
unbounded_channel | Creates an unbounded mpsc channel for communicating between asynchronous tasks without backpressure.