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

# Module std::sync::mpsc 1.0.0 [−] [src]

Multi-producer, single-consumer FIFO queue communication primitives.

This module provides message-based communication over channels, concretely defined among three types:

- `Sender`
- `SyncSender`
- `Receiver`

A `Sender` or `SyncSender` is used to send data to a `Receiver`. Both senders are clone-able (multi-producer) such that many threads can send simultaneously to one receiver (single-consumer).

These channels come in two flavors:

1. An asynchronous, infinitely buffered channel. The `channel` function will return a `(Sender, Receiver)` tuple where all sends will be asynchronous (they never block). The channel conceptually has an infinite buffer.

2. A synchronous, bounded channel. The `sync_channel` function will return a `(SyncSender, Receiver)` tuple where the storage for pending messages is a pre-allocated buffer of a fixed size. All sends will be synchronous by blocking until there is buffer space available. Note that a bound of 0 is allowed, causing the channel to become a "rendezvous" channel where each sender atomically hands off a message to a receiver.

## Disconnection

The send and receive operations on channels will all return a `Result` indicating whether the operation succeeded or not. An unsuccessful operation is normally indicative of the other half of a channel having "hung up" by being dropped in its corresponding thread.

Once half of a channel has been deallocated, most operations can no longer continue to make progress, so `Err` will be returned. Many applications will continue to `unwrap` the results returned from this module, instigating a propagation of failure among threads if one unexpectedly dies.

# Examples

Simple usage:

    use std::thread;
    use std::sync::mpsc::channel;

    // Create a simple streaming channel
    let (tx, rx) = channel();
    thread::spawn(move|| {
        tx.send(10).unwrap();
    });
    assert_eq!(rx.recv().unwrap(), 10);Run

Shared usage:

    use std::thread;
    use std::sync::mpsc::channel;

    // Create a shared channel that can be sent along from many threads
    // where tx is the sending half (tx for transmission), and rx is the receiving
    // half (rx for receiving).
    let (tx, rx) = channel();
    for i in 0..10 {
        let tx = tx.clone();
        thread::spawn(move|| {
            tx.send(i).unwrap();
        });
    }

    for _ in 0..10 {
        let j = rx.recv().unwrap();
        assert!(0 <= j && j < 10);
    }Run

Propagating panics:

    use std::sync::mpsc::channel;

    // The call to recv() will return an error because the channel has already
    // hung up (or been deallocated)
    let (tx, rx) = channel::<i32>();
    drop(tx);
    assert!(rx.recv().is_err());Run

Synchronous channels:

    use std::thread;
    use std::sync::mpsc::sync_channel;

    let (tx, rx) = sync_channel::<i32>(0);
    thread::spawn(move|| {
        // This will wait for the parent thread to start receiving
        tx.send(53).unwrap();
    });
    rx.recv().unwrap();Run

## Structs

IntoIter | An owning iterator over messages on a `Receiver`, created by Receiver::into_iter.
Iter | An iterator over messages on a `Receiver`, created by `iter`.
Receiver | The receiving half of Rust's `channel` (or `sync_channel`) type. This half can only be owned by one thread.
RecvError | An error returned from the `recv` function on a `Receiver`.
SendError | An error returned from the `Sender::send` or `SyncSender::send` function on channels.
Sender | The sending-half of Rust's asynchronous `channel` type. This half can only be owned by one thread, but it can be cloned to send to other threads.
SyncSender | The sending-half of Rust's synchronous `sync_channel` type.
TryIter | An iterator that attempts to yield all pending values for a `Receiver`, created by `try_iter`.
Handle | [ Experimental ] A handle to a receiver which is currently a member of a `Select` set of receivers. This handle is used to keep the receiver in the set as well as interact with the underlying receiver.
Select | [ Experimental ] The "receiver set" of the select interface. This structure is used to manage a set of receivers which are being selected over.

## Enums

RecvTimeoutError | This enumeration is the list of possible errors that made `recv_timeout` unable to return data when called. This can occur with both a `channel` and a `sync_channel`.
TryRecvError | This enumeration is the list of the possible reasons that `try_recv` could not return data when called. This can occur with both a `channel` and a `sync_channel`.
TrySendError | This enumeration is the list of the possible error outcomes for the `try_send` method.

## Functions

channel | Creates a new asynchronous channel, returning the sender/receiver halves. All data sent on the `Sender` will become available on the `Receiver` in the same order as it was sent, and no `send` will block the calling thread (this channel has an "infinite buffer", unlike `sync_channel`, which will block after its buffer limit is reached). `recv` will block until a message is available.
sync_channel | Creates a new synchronous, bounded channel. All data sent on the `SyncSender` will become available on the `Receiver` in the same order as it was sent. Like asynchronous `channel`s, the `Receiver` will block until a message becomes available. `sync_channel` differs greatly in the semantics of the sender, however.

# 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
+ / -
  Collapse/expand 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`)