pub struct BusReader<T> { /* private fields */ }
Expand description
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(()));
Implementations§
source§impl<T: Clone + Sync> BusReader<T>
impl<T: Clone + Sync> BusReader<T>
sourcepub fn try_recv(&mut self) -> Result<T, TryRecvError>
pub 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 method 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();
sourcepub fn recv(&mut self) -> Result<T, RecvError>
pub 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.
sourcepub fn recv_timeout(&mut self, timeout: Duration) -> Result<T, RecvTimeoutError>
pub fn recv_timeout(&mut self, timeout: Duration) -> Result<T, RecvTimeoutError>
Attempts to wait for a value from the bus, returning an error if the corresponding channel
has hung up, or if it waits more than timeout
.
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 message 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.
Examples
use bus::Bus;
use std::sync::mpsc::RecvTimeoutError;
use std::time::Duration;
let mut tx = Bus::<bool>::new(10);
let mut rx = tx.add_rx();
let timeout = Duration::from_millis(100);
assert_eq!(Err(RecvTimeoutError::Timeout), rx.recv_timeout(timeout));