Module spmc 

Available on crate feature spmc only.

Single-producer, multi-consumer queues for distributing work between asynchronous tasks.

Enable the spmc Cargo feature to use this module. bounded applies backpressure at its exact capacity; unbounded sends synchronously and can grow until memory is exhausted. Receivers are cloneable and compete for messages: each accepted message is delivered to one receiver while receivers remain. Values leave the queue in FIFO order, but consumer completion order and an equal distribution of work are not guaranteed.

The sender cannot be cloned, and every send operation requires &mut self, including for the lifetime of a bounded send future. It can move between tasks, but shared references cannot send. Dropping the sender lets receivers drain buffered messages before observing disconnection. Dropping the last receiver releases buffered messages and makes sending return the unsent value.

Example

use asyncband::spmc;

let (mut sender, receiver) = spmc::bounded(2);
let competing = receiver.clone();
sender.send("first").await.unwrap();
sender.send("second").await.unwrap();
drop(sender);

assert_eq!(receiver.recv().await, Ok("first"));
assert_eq!(competing.recv().await, Ok("second"));
assert_eq!(receiver.recv().await, Err(spmc::RecvError::Disconnected));

Single-producer capability

Neither sender supports cloning:

let (sender, _receiver) = asyncband::spmc::bounded::<u8>(1);
let second_producer = sender.clone();

let (sender, _receiver) = asyncband::spmc::unbounded::<u8>();
let second_producer = sender.clone();

Sending through a shared reference is rejected:

fn send(sender: &asyncband::spmc::BoundedSender<u8>) {
    let _ = sender.try_send(1);
}

fn send(sender: &asyncband::spmc::UnboundedSender<u8>) {
    let _ = sender.send(1);
}

A bounded send future retains the exclusive borrow until completion or cancellation:

let (mut sender, _receiver) = asyncband::spmc::bounded(1);
let pending = sender.send(1);
let _ = sender.try_send(2);
drop(pending);

Structs

BoundedReceiver

Receives values from the associated BoundedSender handles.

BoundedSender

Sends values to the associated BoundedReceiver handles.

SendError

An error returned when trying to send on a disconnected queue.

UnboundedReceiver

Receives values from the associated UnboundedSender handles.

UnboundedSender

Sends values to the associated UnboundedReceiver handles.

Enums

RecvError

Error returned by a receive operation.

TryRecvError

Error returned by a non-blocking receive operation.

TrySendError

Error returned by BoundedSender::try_send.

Functions

bounded

Creates a bounded single-producer, multi-consumer queue.

unbounded

Creates an unbounded single-producer, multi-consumer queue.