Crate uchan 

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

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

• Sender
• Receiver

A Sender is used to send data to a Receiver. Senders are clone-able (multi-producer) such that many threads can send simultaneously to one receiver (single-consumer).

There is currently one flavour available: 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.

no_std Usage

Channels can be used in no_std settings due to the thread blocking facilities being made generic. Use the Event trait to implement thread parking and create custom RawSenders and Receivers using raw_channel. The default Sender and Receiver use StdEvent which implements thread parking using std::thread::park.

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 uchan::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:

use std::thread;
use uchan::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:

use uchan::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

RawReceiver

The receiving half of Rust’s raw_channel type. This half can only be owned by one thread.

RawSender

The sending-half of Rust’s asynchronous raw_channel type. This half can only be owned by one thread, but it can be cloned to send to other threads.

RecvError

An error returned from the recv function on a RawReceiver.

SendError

An error returned from the RawSender::send function on channels.

StdEvent

An implementation of Event and TimedEvent using std::thread.

Enums

RecvTimeoutError

This enumeration is the list of possible errors that made recv_timeout unable to return data when called. This can occur with a raw_channel.

TryRecvError

This enumeration is the list of the possible reasons that try_recv could not return data when called. This can occur with a raw_channel.

Traits

Event

An Event represents a single-producer, single-consumer notification synchronization primitive. A thread creates an Event using Event::with, makes it available to the producer, and uses Event::wait to block the caller thread until Event::set is called from another thread or from the same consumer thread prior to Event::wait.

TimedEvent

A TimedEvent is an Event which supports waiting for Event::set but with a timeout. Most conditions of Event::wait still apply, but the timeout allows the caller to stop blocking before Event::set is called from another producer thread.

Functions

channel

Creates an unbounded channel Sender and Receiver using the StdEvent implementation. See raw_channel for more details.

raw_channel

Creates a new asynchronous channel, returning the sender/receiver halves. All data sent on the RawSender will become available on the RawReceiver in the same order as it was sent, and no send will block the calling thread (this channel has an “infinite buffer”). recv will block until a message is available while there is at least one Sender alive (including clones).

Type Aliases

Receiver

An unbounded channel receiver implemented with StdEvent. See RawReceiver for more details.

Sender

An unbounded channel sender implemented with StdEvent. See RawSender for more details.