Module std::sync::mpsc [] [src]

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

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

A Sender`Senderor` or SyncSender`SyncSenderis used to send data to a` is used to send data to a Receiver`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()`channel()function will return a` function will return a (Sender, Receiver)`(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()`sync_channel()function will return a` function will return a (SyncSender, Receiver)`(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`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`Errwill be returned. Many applications will continue to` will be returned. Many applications will continue to unwrap()`unwrap()` the results returned from this module, instigating a propagation of failure among threads if one unexpectedly dies.

Examples

Simple usage:

fn main() { 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); }
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);

Shared usage:

fn main() { 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); } }
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);
}

Propagating panics:

fn main() { 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()); }
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());

Synchronous channels:

fn main() { 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(); }
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();

Structs

IntoIter

An owning iterator over messages on a receiver, this iterator will block whenever next`nextis called, waiting for a new message, and` is called, waiting for a new message, and None`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`nextis called, waiting for a new message, and` is called, waiting for a new message, and None`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`recvfunction on a` function on a Receiver`Receiver`.

SendError

An error returned from the send`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`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.

Enums

TryRecvError

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

TrySendError

This enumeration is the list of the possible error outcomes for the SyncSender::try_send`SyncSender::try_send` method.

Functions

channel

Creates a new asynchronous channel, returning the sender/receiver halves.

sync_channel

Creates a new synchronous, bounded channel.