Trait UnloadChunk

Source

pub trait UnloadChunk: Chunk {
    type Staging: Default;
    type Probes<'a>: Copy;

    // Required methods
    fn probe_count(probes: Self::Probes<'_>) -> usize;
    fn locate(&self, probes: Self::Probes<'_>, probe_index: usize) -> Ordering;
    fn extract_into(
        &self,
        probes: Self::Probes<'_>,
        probe_index: &mut usize,
        staging: &mut Self::Staging,
    );
    fn fetch_into(&self, staging: &mut Self::Staging);
}

Expand description

Look up a sorted set of keys in a chunk, copying the matching updates out into caller-owned staging.

This is the bulk, copy-out way to read a chunk: extraction is finished with a chunk’s body when the call returns, so a spilled body is read for the scope of one call and no reference into pool memory ever exists outside it. That contract is what lets a buffer pool evict with no reader accounting, where navigation-style access would need the body kept readable for as long as the reader holds it.

Callers usually read whole batches, not single chunks: the UnloadBatch extension on ChunkBatch looks up a probe set across the batch’s chunk sequence, and its fetch_into stages the full contents (the scan path). Results land in a Staging the caller owns and consumes at leisure. Staged times are copied verbatim — advancement by a compaction frontier stays with the consumer.

Like Chunk itself, the trait has no key, val, time, or diff opinions: Staging and Probes are opaque types the implementing family chooses, and the one key comparison the batch driver needs is delegated to the chunk via locate — which, like len, must be answerable from resident metadata even when the body is spilled.

§The consume-index protocol (implementors)

A batch’s chunks are one globally-sorted sequence cut at arbitrary points, so a key’s updates may straddle consecutive chunks. extract_into carries that invariant as a protocol: a chunk consumes (advances *probe_index past) every probe strictly below its last key — extracting hits, silently passing over misses — and extracts but does not consume a probe equal to its last key, so the driver re-offers that probe to the next chunk, whose continuation lands in staging as a legal straddle. Consumers detect misses as keys absent from staging.

Required Associated Types§

Source

type Staging: Default

Where extracted updates land: an owned accumulation of resident data, chosen by the implementing family.

Appends arrive in global (key, val, time) order; a group continuing across appends may remain split, exactly as chunk sequences elsewhere carry the straddle invariant.

Source

type Probes<'a>: Copy

A sorted, deduplicated key column, borrowed from the same family — another chunk’s key column, or a synthesized probe set.

Required Methods§

Source

fn probe_count(probes: Self::Probes<'_>) -> usize

The number of probe keys.

Source

fn locate(&self, probes: Self::Probes<'_>, probe_index: usize) -> Ordering

Where probes[probe_index] falls relative to this chunk’s key span: Less before the first key, Equal within [first, last], Greater past the last key.

Resident metadata only — must never fetch a spilled body.

Source

fn extract_into( &self, probes: Self::Probes<'_>, probe_index: &mut usize, staging: &mut Self::Staging, )

Append this chunk’s updates for probes at and after *probe_index into staging, advancing *probe_index past every probe strictly below this chunk’s last key.

A probe equal to the last key is extracted but not consumed: its group may continue in the next chunk (see the protocol above). Any read of a spilled body is scoped to this call.

Source