Struct bus::BusReader

pub struct BusReader<T: Clone> {
    // some fields omitted
}

A BusReader is a single consumer of Bus broadcasts. It will see every new value that is passed to .broadcast() (or successful calls to .try_broadcast()) on the Bus that it was created from.

Dropping a BusReader is perfectly safe, and will unblock the writer if it was waiting for that read to see a particular update.

use bus::Bus;
let mut tx = Bus::new(1);
let mut r1 = tx.add_rx();
let r2 = tx.add_rx();
assert_eq!(tx.try_broadcast(true), Ok(()));
assert_eq!(r1.recv(), Ok(true));

// the bus does not have room for another broadcast
// since it knows r2 has not yet read the first broadcast
assert_eq!(tx.try_broadcast(true), Err(true));

// dropping r2 tells the producer that there is a free slot
// (i.e., it has been read by everyone)
drop(r2);
assert_eq!(tx.try_broadcast(true), Ok(()));

Methods

impl<T: Clone> BusReader<T>

fn try_recv(&mut self) -> Result<T, TryRecvError>

Attempts to return a pending broadcast on this receiver without blocking.

This method will never block the caller in order to wait for data to become available. Instead, this will always return immediately with a possible option of pending data on the channel.

If the corresponding bus has been dropped, and all broadcasts have been received, this method will return with a disconnected error.

This mehtod is useful for a flavor of "optimistic check" before deciding to block on a receiver.

use bus::Bus;
use std::thread;

let mut tx = Bus::new(10);
let mut rx = tx.add_rx();

// spawn a thread that will broadcast at some point
let j = thread::spawn(move || {
    tx.broadcast(true);
});

loop {
    match rx.try_recv() {
        Ok(val) => {
            assert_eq!(val, true);
            break;
        }
        Err(..) => {
            // maybe we can do other useful work here
            // or we can just busy-loop
            thread::yield_now()
        },
    }
}

j.join().unwrap();

fn recv(&mut self) -> Result<T, RecvError>

Read another broadcast message from the bus, and block if none are available.

This function will always block the current thread if there is no data available and it's possible for more broadcasts to be sent. Once a broadcast is sent on the corresponding Bus, then this receiver will wake up and return that message.

If the corresponding Bus has been dropped, or it is dropped while this call is blocking, this call will wake up and return Err to indicate that no more messages can ever be received on this channel. However, since channels are buffered, messages sent before the disconnect will still be properly received.

fn iter<'a>(&'a mut self) -> BusIter<'a, T>

Returns an iterator that will block waiting for broadcasts. It will return None when the bus has been closed (i.e., the Bus has been dropped).

Trait Implementations

impl<T: Clone> Drop for BusReader<T>

fn drop(&mut self)

A method called when the value goes out of scope.

impl<'a, T: Clone> IntoIterator for &'a mut BusReader<T>

type Item = T

The type of the elements being iterated over.

type IntoIter = BusIter<'a, T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> BusIter<'a, T>

Creates an iterator from a value.

impl<T: Clone> IntoIterator for BusReader<T>

type Item = T

The type of the elements being iterated over.

type IntoIter = BusIntoIter<T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> BusIntoIter<T>

Creates an iterator from a value.