Communication primitives for concurrent tasks

Rust makes it very difficult to share data among tasks to prevent race conditions and to improve parallelism, but there is often a need for communication between concurrent tasks. The primitives defined in this module are the building blocks for synchronization in rust.

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

• Sender
• Receiver

A Sender is used to send data to a Receiver. A Sender is clone-able such that many tasks can send simultaneously to one receiver. These channels are task blocking, not thread blocking. This means that if one task is blocked on a channel, other tasks can continue to make progress.

Rust channels can be used as if they have an infinite internal buffer. What this means is that the send operation will never block. Receivers, on the other hand, will block the task if there is no data to be received.

Failure Propagation

In addition to being a core primitive for communicating in rust, channels are the points at which failure is propagated among tasks. Whenever the one half of channel is closed, the other half will have its next operation fail!. The purpose of this is to allow propagation of failure among tasks that are linked to one another via channels.

There are methods on both of Sender and Receiver to perform their respective operations without failing, however.

Outside the Runtime

All channels and ports work seamlessly inside and outside of the rust runtime. This means that code may use channels to communicate information inside and outside of the runtime. For example, if rust were embedded as an FFI module in another application, the rust runtime would probably be running in its own external thread pool. Channels created can communicate from the native application threads to the rust threads through the use of native mutexes and condition variables.

What this means is that if a native thread is using a channel, execution will be blocked accordingly by blocking the OS thread.

Example

// Create a simple streaming channel
let (tx, rx) = channel();
spawn(proc() {
    tx.send(10);
});
assert_eq!(rx.recv(), 10);

// Create a shared channel which can be sent along from many tasks
let (tx, rx) = channel();
for i in range(0, 10) {
    let tx = tx.clone();
    spawn(proc() {
        tx.send(i);
    })
}

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

// The call to recv() will fail!() because the channel has already hung
// up (or been deallocated)
let (tx, rx) = channel::<int>();
drop(tx);
rx.recv();