Struct OutputHandle

pub struct OutputHandle<T>(/* private fields */);

A handle used to read data from a stream from outside the circuit.

Internally, the handle manages an array of mailboxes, one for each worker thread. At the end of each clock cycle, the worker writes the current contents of the stream to the mailbox.

Once the clock cycle ends (i.e., the DBSPHandle::step method returns), each mailbox contains a single value – a copy of stream contents at the current clock cycle.

The client retrieves values produced by individual workers using the take_from_worker method. Alternatively they can retrieve values from all mailboxes at once using take_from_all. If the stream carries relational data, the consolidate method can be used to combine output batches produced by all workes into a single batch.

Reading from a mailbox using any of these methods removes the value leaving the mailbox empty. If the value is not read, it gets overwritten at the next clock cycle (i.e., during the next call to step).

Implementations

impl<T> OutputHandle<T>

where T: Send + Clone + 'static,

pub fn num_nonempty_mailboxes(&self) -> usize

The number of mailboxes that contain values that haven’t been retrieved yet.

pub fn peek_from_worker<F, O: 'static>(&self, worker: usize, func: F) -> O

where F: Fn(&Option<T>) -> O,

pub fn take_from_worker(&self, worker: usize) -> Option<T>

Read the value produced by worker worker thread during the last clock cycle.

This method is invoked between two consecutive DBSPHandle::step calls to retrieve the value written to the stream during the last clock cycle, if any. It removes the value from the mailbox, so subsequent calls will return None.

Invoking this method in the middle of a clock cycle, i.e., during the execution of DBSPHandle::step, may return either None or Some, depending of whether a value has already been pushed to the stream.

pub fn take_from_all(&self) -> Vec<T>

Read values produced by all worker threads during the last clock cycle.

This is equivalent to calling take_from_worker for each worker thread in order and storing all none-None results in a vector.

impl<T> OutputHandle<T>

where T: Batch<Time = ()>, T::InnerBatch: Send,

pub fn consolidate(&self) -> T

Read batches produced by all worker threads during the last clock cycle and consolidate them into a single batch.

This method is used in the common case when the OutputHandle is attached to a stream that carries Batches of updates to relational data. Semantically, each Batch consists of (key, value, weight) tuples. Depending on the structure of the circuit, the same key or (key, value) pair can occur in batches produced by multiple workers. This method retrieves batches produced by all workers and consolidates them into a single batch where each (key, value) pair occurs exactly once.

Internally, consolidate calls take_from_worker to retrieve batches from individual worker threads. See take_from_worker documentation for the exact semantics of this method. In particular, note that repeated calls to take_from_worker return None. consolidate skips None results when computing the consolidated batch.

impl<T> OutputHandle<T>

where T: Batch<Time = ()> + Send,

pub fn dyn_consolidate(&self, factories: &T::Factories) -> T

See OutputHandle::consolidate.

Trait Implementations

impl<T: Clone> Clone for OutputHandle<T>

fn clone(&self) -> OutputHandle<T>

Returns a duplicate of the value.

const fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.