Module mpmc

🔬This is a nightly-only experimental API. (mpmc_channel)

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

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

• Sender
• Receiver

Senders are used to send data to a set of Receivers. 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 (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:

#![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());

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 Sender by cloning it.
• RecvErrorExperimental
  An error returned from the recv function on a Receiver.
• SendErrorExperimental
  An error returned from the Sender::send or SyncSender::send function on channels.
• 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

• RecvTimeoutErrorExperimental
  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.
• SendTimeoutErrorExperimental
  An error returned from the send_timeout method.
• TryRecvErrorExperimental
  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.
• TrySendErrorExperimental
  This enumeration is the list of the possible error outcomes for the try_send method.

Functions

• channelExperimental
  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 while there is at least one Sender alive (including clones).
• sync_channelExperimental
  Creates a new synchronous, bounded channel. All data sent on the Sender will become available on the Receiver in the same order as it was sent. Like asynchronous channels, the Receiver will block until a message becomes available. sync_channel differs greatly in the semantics of the sender, however.