Struct Cursors 

pub struct Cursors { /* private fields */ }

Provenance-driven advancer that targets only the cursor nodes relevant to a specific set of output fields.

Built at phase setup by tracing Polydat provenance from the op template’s referenced fields back to root cursor nodes. Only those cursors advance — unused cursors are left untouched.

Implementations

impl Cursors

pub fn for_fields( program: &PolydatProgram, field_names: &[&str], source_factories: &HashMap<String, Arc<dyn DataSourceFactory>>, ) -> Self

Build an advancer from a Polydat program, a set of output field names, and a map of source name → DataSourceFactory.

Traces provenance: for each field, finds the output node, gets its input provenance bitmask, and identifies which inputs are cursor ordinals (matching {source}__ordinal pattern). Creates a reader for each targeted source.

pub fn reserve_ordinal_batch( &mut self, demand: usize, ) -> Result<Option<OrdinalBatchLease>, CursorBatchError>

Reserve one owned batch from a single perfect ordinal cursor.

This is the source-side entry point for Tier-1 SIMD execution. It is intentionally unavailable for multiple cursor targets or sources that merely happen to be monotonic: only the explicit perfect-ordinal contract permits payload-free replay from the returned range.

pub fn advance(&mut self) -> bool

Advance all targeted cursors. Returns false if any targeted cursor is exhausted (no more data).

After advancing, the new ordinals and field projections are available via inject_into_state().

pub fn inject_into_state(&self, state: &mut PolydatState)

Inject the current cursor values into a Polydat state.

Sets each cursor’s ordinal at its input index, plus any field projections from the source item.

pub fn last_items(&self) -> &[Option<SourceItem>]

Get the last items read from all targets (for FiberBuilder injection).

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

Known extent of the driving cursor (smallest among targeted cursors with known extent). Used for progress reporting.

pub fn consumed(&self) -> u64

Total advances performed so far.

pub fn target_count(&self) -> usize

Number of targeted cursors.

pub fn is_empty(&self) -> bool

Whether this advancer has any targets.