Struct clocked_dispatch::ClockedBroadcaster

pub struct ClockedBroadcaster<T: Clone> { /* private fields */ }

A sending half of a clocked synchronous channel that only allows broadcast. This half can only be owned by one thread, but it can be cloned to send to other threads. A ClockedBroadcaster can be constructed from a ClockedSender using ClockedSender::into_broadcaster.

Sending on a clocked channel will deliver the given message to the appropriate receiver, but also notify all other receivers about the timestamp assigned to the message. The sending will never block on a receiver that is not the destination of the message.

Beware that dropping a clocked sender incurs control messages to the dispatcher, and that those control messages may result in messages being sent to receivers. If the dispatch channel is not sufficiently buffered, this means that dropping a ClockedSender before the corresponding ClockedReceiver is receiving on its end of the channel may deadlock.

Note that the existence of a ClockedBroadcater prevents the closing of any clocked channels managed by this dispatcher.

Examples

Regular broadcast:

use clocked_dispatch;
use std::sync::mpsc;

let m = clocked_dispatch::new(10);
let (tx_a, rx_a) = m.new("atx", "arx");
let tx = tx_a.into_broadcaster();
// note that the A channel is still open since there now exists a broadcaster,
// even though all A senders have been dropped.

let (tx_b, rx_b) = m.new("btx", "brx");

tx.broadcast("1");

let x = rx_a.recv().unwrap();
assert_eq!(x.0, Some("1"));
assert_eq!(rx_b.recv(), Ok(x));

// non-broadcasts still work
tx_b.send("2");
let x = rx_b.recv().unwrap();
assert_eq!(x.0, Some("2"));
assert_eq!(rx_a.recv(), Ok((None, x.1)));

// drop broadcaster
drop(tx);

// A is now closed because there are no more senders
assert_eq!(rx_a.recv(), Err(mpsc::RecvError));

// rx_b is *not* closed because tx_b still exists
assert_eq!(rx_b.try_recv(), Err(mpsc::TryRecvError::Empty));

drop(tx_b);
// rx_b is now closed because its senders have all gone away
assert_eq!(rx_b.recv(), Err(mpsc::RecvError));

Forwarding broadcast:

use clocked_dispatch;
use std::sync::mpsc;

let m = clocked_dispatch::new(10);
let (tx_a, rx_a) = m.new("atx", "arx");
let (tx_b, rx_b) = m.new("btx", "brx");
let (tx_c, rx_c) = m.new("ctx", "crx");

let tx = tx_a.into_broadcaster();
tx.broadcast_forward(Some("1"), 1);

assert_eq!(rx_a.recv().unwrap(), (Some("1"), 1));
assert_eq!(rx_b.recv().unwrap(), (Some("1"), 1));
assert_eq!(rx_c.recv().unwrap(), (Some("1"), 1));

// non-broadcasts still work
tx_c.forward(Some("c"), 2);
assert_eq!(rx_a.recv().unwrap(), (None, 2));
assert_eq!(rx_b.recv().unwrap(), (None, 2));
assert_eq!(rx_c.recv().unwrap(), (Some("c"), 2));

Implementations

impl<T: Clone> ClockedBroadcaster<T>

pub fn broadcast(&self, data: T)

Sends a value to all receivers known to this dispatcher. The value will be assigned a sequence number by the dispatcher.

This function will block until space in the internal buffer becomes available, or a receiver is available to hand off the message to.

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. If the buffer size is 0, however, it can be guaranteed that the receiver has indeed received the data if this function returns success.

pub fn broadcast_forward(&self, data: Option<T>, ts: usize)

Sends an already-sequenced value to all receivers known to this dispatcher. The message may be buffered by the dispatcher until it can guarantee that no other sender will later try to send messages with a lower sequence number.

This function will block until space in the internal buffer becomes available, or a receiver is available to hand off the message to.

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. If the buffer size is 0, however, it can be guaranteed that the receiver has indeed received the data if this function returns success.

It is optional to include data when forwarding. If no data is included, this message conveys to the dispatcher that this sender promises not to send later messages with a higher sequence number than the one given.

pub fn clone<V: Into<String>>(&self, source: V) -> ClockedBroadcaster<T>

Creates a new clocked broadcast sender.

Clocked dispatch requires that all senders have a unique name so that the “up-to-date-ness” of the senders can be tracked reliably.

Trait Implementations

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

fn drop(&mut self)

Executes the destructor for this type.