Trait TraceReader

Source

pub trait TraceReader {
    type Time: Timestamp + Lattice;
    type Batch: 'static + Clone;

    // Required methods
    fn spans_through(
        &mut self,
        upper: AntichainRef<'_, Self::Time>,
    ) -> Option<Vec<Span<Self::Time, Self::Batch>>>;
    fn set_logical_compaction(&mut self, frontier: AntichainRef<'_, Self::Time>);
    fn get_logical_compaction(&mut self) -> AntichainRef<'_, Self::Time>;
    fn set_physical_compaction(
        &mut self,
        frontier: AntichainRef<'_, Self::Time>,
    );
    fn get_physical_compaction(&mut self) -> AntichainRef<'_, Self::Time>;
    fn map_spans<F: FnMut(&Span<Self::Time, Self::Batch>)>(&self, f: F);

    // Provided methods
    fn batches_through(
        &mut self,
        upper: AntichainRef<'_, Self::Time>,
    ) -> Option<Vec<Self::Batch>> { ... }
    fn read_upper(&mut self, target: &mut Antichain<Self::Time>) { ... }
    fn advance_upper(&mut self, upper: &mut Antichain<Self::Time>) { ... }
}

Expand description

A trace whose contents may be read.

This is a restricted interface to the more general Trace trait, which extends this trait with further methods to update the contents of the trace. These methods are used to examine the contents, and to update the reader’s capabilities (which may release restrictions on the mutations to the underlying trace and cause work to happen).

Required Associated Types§

Source

type Time: Timestamp + Lattice

The timestamp type of the trace’s updates.

Key/val/diff opinions live on the batches’ cursors; the trace itself only needs time, to bound its contents and to drive compaction.

Source

type Batch: 'static + Clone

The batches of updates the trace’s spans carry.

A span is Span<Self::Time, Self::Batch>, pairing a description with a batch when its interval brought any updates. The trace has no opinion on how a batch is read: operators that want cursors add a Navigable bound of their own, and operators that read batches some other way add none.

Required Methods§

Source

fn spans_through( &mut self, upper: AntichainRef<'_, Self::Time>, ) -> Option<Vec<Span<Self::Time, Self::Batch>>>

Acquires the non-empty sequence of spans covering updates at times not greater or equal to an element of upper.

This method is expected to work if called with an upper that (i) was an observed bound in spans from the trace, and (ii) the trace has not been advanced beyond upper. Practically, the implementation should be expected to look for a “clean cut” using upper, and if it finds such a cut can return the spans. This should allow upper such as &[], used to acquire all spans, though it is difficult to imagine other uses.

Source

fn set_logical_compaction(&mut self, frontier: AntichainRef<'_, Self::Time>)

Advances the frontier that constrains logical compaction.

Logical compaction is the ability of the trace to change the times of the updates it contains. Update times may be changed as long as their comparison to all query times beyond the logical compaction frontier remains unchanged. Practically, this means that groups of timestamps not beyond the frontier can be coalesced into fewer representative times.

Logical compaction is important, as it allows the trace to forget historical distinctions between update times, and maintain a compact memory footprint over an unbounded update history.

By advancing the logical compaction frontier, the caller unblocks merging of otherwise equivalent updates, but loses the ability to observe historical detail that is not beyond frontier.

It is an error to call this method with a frontier not equal to or beyond the most recent arguments to this method, or the initial value of get_logical_compaction() if this method has not yet been called.

Source

fn get_logical_compaction(&mut self) -> AntichainRef<'_, Self::Time>

Reports the logical compaction frontier.

All update times beyond this frontier will be presented with their original times, and all update times not beyond this frontier will present as a time that compares identically with all query times beyond this frontier. Practically, update times not beyond this frontier should not be taken to be accurate as presented, and should be used carefully, only in accumulation to times that are beyond the frontier.

Source

fn set_physical_compaction(&mut self, frontier: AntichainRef<'_, Self::Time>)

Advances the frontier that constrains physical compaction.

Physical compaction is the ability of the trace to merge the batches of updates it maintains. Physical compaction does not change the updates or their timestamps, although it is also the moment at which logical compaction is most likely to happen.

Physical compaction allows the trace to maintain a logarithmic number of batches of updates, which is what allows the trace to provide efficient random access by keys and values.

By advancing the physical compaction frontier, the caller unblocks the merging of batches of updates, but loses the ability to create a cursor through any frontier not beyond frontier.

It is an error to call this method with a frontier not equal to or beyond the most recent arguments to this method, or the initial value of get_physical_compaction() if this method has not yet been called.

Source

fn get_physical_compaction(&mut self) -> AntichainRef<'_, Self::Time>

Reports the physical compaction frontier.

All spans containing updates beyond this frontier will not be merged with other spans. This allows the caller to acquire the spans through any frontier beyond the physical compaction frontier, with the spans_through() method. This functionality is primarily of interest to the join operator, and any other operators who need to take notice of the physical structure of update batches.

Source

fn map_spans<F: FnMut(&Span<Self::Time, Self::Batch>)>(&self, f: F)

Maps logic across the non-empty sequence of spans in the trace.

This is currently used only to extract historical data to prime late-starting operators who want to reproduce the stream of spans moving past the trace.

Provided Methods§

Source

fn batches_through( &mut self, upper: AntichainRef<'_, Self::Time>, ) -> Option<Vec<Self::Batch>>

Acquires the batches of the spans covering times not greater or equal to an element of upper.

Spans with no updates contribute nothing, so this is what callers taking cursors want; spans_through is for the drivers that also need the spans’ descriptions.

Source

fn read_upper(&mut self, target: &mut Antichain<Self::Time>)

Reads the upper frontier of committed times.

Source

fn advance_upper(&mut self, upper: &mut Antichain<Self::Time>)

Advances upper across any spans with no updates.

A span carrying no updates whose lower bound equals the current contents of upper will advance upper to its upper. Taken across all spans, this should advance upper across update-free regions.