Trait DataSource 

pub trait DataSource: Send {
    // Required methods
    fn reserve(&mut self, stride: usize) -> Option<Range<u64>>;
    fn render_item(&self, ordinal: u64) -> SourceItem;
    fn extent(&self) -> Option<u64>;
    fn consumed(&self) -> u64;
    fn schema(&self) -> &SourceSchema;

    // Provided methods
    fn next(&mut self) -> Option<SourceItem> { ... }
    fn next_chunk(&mut self, limit: usize) -> Vec<SourceItem> { ... }
    fn replay_contract(&self) -> SourceReplayContract { ... }
}

Consumption API for data sources. One instance per fiber.

The interaction model has two phases:

1. Reserve — reserve(stride) atomically claims a range of ordinals via CAS on the shared cursor. This touches shared state but is instantaneous (one atomic op). Returns None when the source is globally exhausted.

2. Render — the fiber uses the reserved range with its own Polydat instance to produce field values. No shared state, no contention between fibers. For range sources, rendering is trivial (ordinal IS the data). For dataset sources, rendering reads vectors/metadata from mmap’d storage.

The next_chunk convenience method combines both phases. Use reserve directly when the rendering is handled by the executor’s Polydat fiber.

Required Methods

fn reserve(&mut self, stride: usize) -> Option<Range<u64>>

Atomically reserve up to stride ordinals from the source.

Returns the half-open range [start..end) of reserved ordinals, or None if the source is exhausted. The range may be shorter than stride at the tail of the source.

This is the only method that touches shared state (the global cursor). It must be lock-free — a single CAS or fetch_add.

fn render_item(&self, ordinal: u64) -> SourceItem

Produce a source item for a previously reserved ordinal.

This is the fiber-local rendering step — no shared state. For range sources: returns SourceItem::ordinal(ordinal). For dataset sources: reads vector/metadata from storage.

fn extent(&self) -> Option<u64>

Known extent, if finite.

fn consumed(&self) -> u64

Items consumed so far (for progress reporting).

fn schema(&self) -> &SourceSchema

The schema of items this source yields.

Provided Methods

fn next(&mut self) -> Option<SourceItem>

Pull the next item. None = source exhausted.

fn next_chunk(&mut self, limit: usize) -> Vec<SourceItem>

Pull up to limit items. Combines reserve + render. Returns fewer than limit only when the source is globally exhausted. Empty vec = exhausted.

fn replay_contract(&self) -> SourceReplayContract

Replay/addressability capability for offset-stamped batch execution. External source implementations inherit the safe consumptive default until they explicitly prove the stronger contract.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors