Struct bus::Bus

pub struct Bus<T> { /* private fields */ }

Bus is the main interconnect for broadcast messages. It can be used to send broadcast messages, or to connect additional consumers. When the Bus is dropped, receivers will continue receiving any outstanding broadcast messages they would have received if the bus were not dropped. After all those messages have been received, any subsequent receive call on a receiver will return a disconnected error.

Implementations

impl<T> Bus<T>

pub fn new(len: usize) -> Bus<T>

Allocates a new Bus.

The provided length should be sufficient to absorb temporary peaks in the data flow, and is thus workflow-dependent. Bus performance degrades somewhat when the queue is full, so it is generally better to set this high than low unless you are pressed for memory.

pub fn try_broadcast(&mut self, val: T) -> Result<(), T>

Attempt to broadcast the given value to all consumers, but does not block if full.

Note that, in contrast to regular channels, a bus is not considered closed if there are no consumers, and thus broadcasts will continue to succeed. Thus, a successful broadcast occurs as long as there is room on the internal bus to store the value, or some older value has been received by all consumers. Note that a return value of Err means that the data will never be received (by any consumer), but a return value of Ok does not mean that the data will be received by a given consumer. It is possible for a receiver to hang up immediately after this function returns Ok.

This method will never block the current thread.

use bus::Bus;
let mut tx = Bus::new(1);
let mut rx = tx.add_rx();
assert_eq!(tx.try_broadcast("Hello"), Ok(()));
assert_eq!(tx.try_broadcast("world"), Err("world"));

pub fn broadcast(&mut self, val: T)

Broadcasts a value on the bus to all consumers.

This function will block until space in the internal buffer becomes available.

Note that a successful send does not guarantee that the receiver will ever see the data if there is a buffer on this channel. Items may be enqueued in the internal buffer for the receiver to receive at a later time. Furthermore, in contrast to regular channels, a bus is not considered closed if there are no consumers, and thus broadcasts will continue to succeed.

pub fn add_rx(&mut self) -> BusReader<T>

Add a new consumer to this bus.

The new consumer will receive all future broadcasts on this bus.

Examples

use bus::Bus;
use std::sync::mpsc::TryRecvError;

let mut bus = Bus::new(10);
let mut rx1 = bus.add_rx();

bus.broadcast("Hello");

// consumer present during broadcast sees update
assert_eq!(rx1.recv(), Ok("Hello"));

// new consumer does *not* see broadcast
let mut rx2 = bus.add_rx();
assert_eq!(rx2.try_recv(), Err(TryRecvError::Empty));

// both consumers see new broadcast
bus.broadcast("world");
assert_eq!(rx1.recv(), Ok("world"));
assert_eq!(rx2.recv(), Ok("world"));

pub fn rx_count(&self) -> usize

Returns the number of active consumers currently attached to this bus.

It is not guaranteed that a sent message will reach this number of consumers, as active consumers may never call recv or try_recv again before dropping.

Examples

use bus::Bus;

let mut bus = Bus::<u8>::new(10);
assert_eq!(bus.rx_count(), 0);

let rx1 = bus.add_rx();
assert_eq!(bus.rx_count(), 1);

drop(rx1);
assert_eq!(bus.rx_count(), 0);

Trait Implementations

impl<T> Debug for Bus<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> Drop for Bus<T>

fn drop(&mut self)

Executes the destructor for this type.