std::sync::mpmc - Rust
Description: Multi-producer, multi-consumer FIFO queue communication primitives.

## Module mpmc

Source
🔬This is a nightly-only experimental API. (`mpmc_channel` #126840)
Expand description

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

This module provides message-based communication over channels, concretely defined by two types:

- `Sender`
- `Receiver`

`Sender`s are used to send data to a set of `Receiver`s where each item sent is delivered to (at most) one receiver. Both sender and receiver are cloneable (multi-producer) such that many threads can send simultaneously to receivers (multi-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 `(Sender, 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:

    #![feature(mpmc_channel)]

    use std::thread;
    use std::sync::mpmc::channel;

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

Shared usage:

    #![feature(mpmc_channel)]

    use std::thread;
    use std::sync::mpmc::channel;

    thread::scope(|s| {
        // 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();
            s.spawn(move || {
                tx.send(i).unwrap();
            });
        }

        for _ in 0..5 {
            let rx1 = rx.clone();
            let rx2 = rx.clone();
            s.spawn(move || {
                let j = rx1.recv().unwrap();
                assert!(0 <= j && j < 10);
            });
            s.spawn(move || {
                let j = rx2.recv().unwrap();
                assert!(0 <= j && j < 10);
            });
        }
    })

Propagating panics:

    #![feature(mpmc_channel)]

    use std::sync::mpmc::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());

## Re-exports§

`pub use crate::sync::mpsc::RecvError;`
`pub use crate::sync::mpsc::RecvTimeoutError;`
`pub use crate::sync::mpsc::SendError;`
`pub use crate::sync::mpsc::TryRecvError;`
`pub use crate::sync::mpsc::TrySendError;`

## Structs§

IntoIterExperimental
  An owning iterator over messages on a `Receiver`, created by `into_iter`.
IterExperimental
  An iterator over messages on a `Receiver`, created by `iter`.
ReceiverExperimental
  The receiving half of Rust’s `channel` (or `sync_channel`) type. Different threads can share this `Receiver` by cloning it.
SenderExperimental
  The sending-half of Rust’s synchronous `channel` type.
TryIterExperimental
  An iterator that attempts to yield all pending values for a `Receiver`, created by `try_iter`.

## Enums§

SendTimeoutErrorExperimental
  An error returned from the `send_timeout` method.

## Functions§

channelExperimental
  Creates a new asynchronous channel, returning the sender/receiver halves.
sync_channelExperimental
  Creates a new synchronous, bounded channel.