Module comm::broadcast[][src]

Multiple-producer, multiple-consumer channels.

Unlike MPSC channels, broadcast channels must be statically allocated. Every broadcast channel must have a unique type that implements [Token][broadcast::Token]. Access to a particular broadcast channel is controlled by the visibility of this Token, as the token must be presented to the Switchboard to construct broadcast transmitters or receivers.

Broadcast channels always broadcast messages to all nodes in the cluster, with the exception that the broadcasting node can choose whether it would like to receive its own messages, via [Token::loopback][broadcast::Token::loopback]. It is therefore very important that all nodes in the cluster allocate their broadcast receiver and periodically drain it of messages; otherwise, the network buffer will fill up, and the transmitter will be unable to broadcast new messages.

A relatively contrived example of broadcasting in a one-node cluster follows:

use comm::{broadcast, Switchboard};
use futures::sink::SinkExt;
use futures::stream::StreamExt;

struct UniversalAnswersToken;

impl broadcast::Token for UniversalAnswersToken {
    type Item = usize;

    fn loopback(&self) -> bool {
        // Enable loopback so that we receive our own transmissions.
        true
    }
}

let switchboard = Switchboard::local()?;
let mut tx = switchboard.broadcast_tx(UniversalAnswersToken);
let mut rx = switchboard.broadcast_rx(UniversalAnswersToken);
tx.send(42).await?;
assert_eq!(rx.next().await.transpose()?, Some(42));

Structs

FanoutReceiverBuilder

The builder returned by Receiver::fanout. New receivers can be allocated with FanoutReceiverBuilder::attach. Once all new receivers are allocated, FanoutReceiverBuilder::shuttle must be called, and the returned future spawned onto a [tokio::executor::Executor], in order for the transmissions to be routed appropriately.

Receiver

The receiving end of a broadcast channel.

Sender

The transmission end of a broadcast channel.

Enums

FanoutError

The error returned while shuttling messages to fanned-out broadcast receivers.

Traits

Token

The capability to construct a particular broadcast sender or receiver.