Struct EventBuffer

Source

pub struct EventBuffer<S: EngineSpec> { /* private fields */ }

Expand description

A receiver for events that provides a pull-based model with periodic reports.

By default, the update engine provides a push-based model where you are notified of new events as soon as they come in. The event buffer converts events into a pull-based model, where periodic, serializable EventReports can be generated.

§Features

The buffer is responsible for tracking step and progress events as they come in. The buffer can:

Receive events and update its internal state based on them.
Discard progress events that are no longer useful.
Cap the number of low-priority events such that older events are dropped.

The buffer is currently resilient against:

duplicated and dropped progress events
duplicated step events
dropped low-priority step events

The buffer is currently not resilient against:

dropped high-priority step events
reordered progress or step events

These cases can be handled on a best-effort basis in the future at some cost to complexity, if required.

Implementations§

Source §

impl<S: EngineSpec> EventBuffer<S>

Source

pub const DEFAULT_MAX_LOW_PRIORITY: usize = 8

The default value for max_low_priority, as created by EventBuffer::default().

Source

pub fn new(max_low_priority: usize) -> Self

Creates a new event buffer.

max_low_priority determines the maximum number of low-priority events retained for a particular step at any given time.

Source

pub fn add_event_report(&mut self, report: EventReport<S>)

Adds an EventReport to the buffer.

Source

pub fn add_event(&mut self, event: Event<S>)

Adds an individual Event to the buffer.

Source

pub fn add_step_event(&mut self, event: StepEvent<S>)

Adds a StepEvent to the buffer.

This might cause older low-priority events to fall off the list.

Source

pub fn root_execution_id(&self) -> Option<ExecutionUuid>

Returns the root execution ID, if this event buffer is aware of any events.

Source

pub fn root_execution_summary(&self) -> Option<ExecutionSummary>

Returns an execution summary for the root execution ID, if this event buffer is aware of any events.

Source

pub fn steps(&self) -> EventBufferSteps<'_, S>

Returns information about each step, as currently tracked by the buffer, in order of when the events were first defined.

Source

pub fn iter_steps_recursive( &self, ) -> impl Iterator<Item = (StepKey, &EventBufferStepData<S>)>

Iterates over all known steps in the buffer in a recursive fashion.

The iterator is depth-first and pre-order (i.e. for nested steps, the parent step is visited before the child steps).

Source

pub fn get(&self, step_key: &StepKey) -> Option<&EventBufferStepData<S>>

Returns information about the given step, as currently tracked by the buffer.

Source

pub fn get_execution_data( &self, execution_id: &ExecutionUuid, ) -> Option<&EventBufferExecutionData>

Returns per-execution data for the given execution ID.

Source

pub fn generate_report(&self) -> EventReport<S>

Generates an EventReport for this buffer.

This report can be serialized and sent over the wire.

Source

pub fn generate_report_since( &self, last_seen: &mut Option<usize>, ) -> EventReport<S>

Generates an EventReport for this buffer, updating last_seen to a new value for incremental report generation.

This report can be serialized and sent over the wire.

Source

pub fn has_pending_events_since(&self, last_seen: Option<usize>) -> bool

Returns true if any further step events are pending since last_seen.

This does not currently care about pending progress events, just pending step events. A typical use for this is to check that all step events have been reported before a sender shuts down.

Source