Module std::sync::mpsc1.0.0 [] [src]

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

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

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, this iterator will block whenever next is called, waiting for a new message, and None will be returned when the corresponding channel has hung up.

Iter

An iterator over messages on a receiver, this iterator will block whenever next is called, waiting for a new message, and None will be returned when the corresponding channel has hung up.

Receiver

The receiving-half of Rust's 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 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 channel type. This half can only be owned by one thread, but it can be cloned to send to other threads.

Handle [Unstable]

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 [Unstable]

The "receiver set" of the select interface. This structure is used to manage a set of receivers which are being selected over.

TryIter [Unstable]

An iterator that attempts to yield all pending values for a receiver. None will be returned when there are no pending values remaining or if the corresponding channel has hung up.

Enums

RecvTimeoutError

This enumeration is the list of possible errors that recv_timeout could not return data when called.

TryRecvError

This enumeration is the list of the possible reasons that try_recv could not return data when called.

TrySendError

This enumeration is the list of the possible error outcomes for the SyncSender::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, and no send will block the calling thread (this channel has an "infinite buffer").

sync_channel

Creates a new synchronous, bounded channel.