Struct Vector 

pub struct Vector<V> { /* private fields */ }

A Vec-like container with per-slot dirty and validity tracking.

Two independent bits per slot

• Dirty (dirty): per-cycle bit, set when a slot is written via Vector::commit / Vector::invalidate / Vector::push / Vector::push_committed / Vector::update, cleared by Vector::reset. Drives Vector::iter_updated_valid.
• Validity (valid): multi-cycle bit, set by Vector::commit / Vector::push_committed / Vector::update, cleared by Vector::invalidate. Not touched by Vector::reset — a slot that was valid at end of cycle stays valid at start of the next cycle. Drives Vector::get_valid and Vector::iter_updated_valid.

The validity bit gives pipeline stages an Option-like read API: a downstream stage that reads via Vector::get_valid cannot reach the inner value without first matching on Some / None, so the consistency / freshness check is enforced at the type system level. See SlotWriter for the symmetric write side.

Breaking change in 0.2.1

The legacy bypass methods get, get_updated, get_mut, iter_updated were removed in 0.2.1. All access paths now engage with the validity bit. Callers that genuinely need indexed accumulation rather than single-value-per-slot should use crate::value::buckets::Buckets instead.

Implementations

impl<V> Vector<V>

pub fn new() -> Vector<V>

Creates a new, empty Vector.

pub fn with_capacity(capacity: usize) -> Vector<V>

Creates a Vector with the specified capacity.

pub fn from_vec(data: Vec<V>) -> Vector<V>

Bulk constructor from an existing Vec<V>. Every slot starts valid and clean (no dirty bits set), matching the “loaded from saved state” pattern: downstream consumers can read via Vector::get_valid but won’t see a fresh round of iter_updated_* events until something is committed or invalidated.

pub fn from_fill(value: V, len: usize) -> Vector<V>

where V: Clone,

Bulk constructor filled with len clones of value. Same dirty / valid semantics as Vector::from_vec: every slot starts valid + clean.

pub fn with_invalid_slots(len: usize) -> Vector<V>

where V: Default,

Bulk constructor with len slots that all start invalid and clean. The backing storage is allocated — so commit(i, ..) for any i < len will not panic — but every slot reads as None via Vector::get_valid until the caller commits a value into it. Slots hold V::default() placeholders that are never exposed while invalid.

Useful for an externally-fed buffer of known size whose slots are populated incrementally: allocate once with with_invalid_slots(n), then commit real values as they arrive. Contrast with Vector::from_fill, whose slots start valid.

pub fn as_slice(&self) -> &[V]

Returns the full underlying slice of values, regardless of per-slot validity or dirty state. Useful for bulk read paths where the caller has already established validity through other means (e.g. tests, snapshot serialisation).

pub fn is_updated(&self) -> bool

Returns true if any element in the Vector is updated.

pub fn all_updated(&self) -> bool

Returns true if every element in the Vector is updated. Returns false for an empty Vector.

pub fn clear(&mut self)

Clears the Vector, removing all values.

pub fn len(&self) -> usize

Returns the number of elements in the Vector.

pub fn is_empty(&self) -> bool

Returns true if the Vector contains no elements.

pub fn iter(&self) -> Iter<'_, V>

Returns an iterator over the elements of the Vector.

pub fn iter_mut(&mut self) -> IterMut<'_, V>

Returns a mutable iterator over the elements of the Vector. Marks all elements as updated.

pub fn get_mut_untracked(&mut self, index: usize) -> Option<&mut V>

Returns a mutable reference to the element at the given index without updating dirty tracking.

This is useful when callers want to reuse or clear previously touched storage between compute cycles without reporting a fresh update to downstream stages.

pub fn push(&mut self, value: V)

Appends an element to the back of the Vector, marking it as updated.

The new slot is marked invalid: the pushed value is treated as a placeholder rather than a meaningful committed value. Use Vector::push_committed when the initial value is meaningful, or call Vector::commit on the new index afterwards.

pub fn push_committed(&mut self, value: V)

Like Vector::push, but the new slot is marked valid.

Use this when you genuinely have a meaningful starting value for the slot; otherwise prefer push and explicitly Vector::commit later, which makes the moment the slot becomes valid explicit.

pub fn pop(&mut self) -> Option<V>

Removes the last element from the Vector and returns it, or None if empty.

pub fn is_valid(&self, index: usize) -> bool

Returns true if slot index is valid (has a committed value that has not been invalidated). Returns false if the index is out of bounds.

pub fn is_updated_at(&self, index: usize) -> bool

Returns true if slot index was written this cycle (commit / update / invalidate / slot_writer.commit). Returns false if the index is out of bounds, or if the slot’s dirty bit was cleared by Reset::reset at end-of-cycle.

Equivalent to looking up index in the set produced by Vector::iter_updated_indices, but as an O(1) bit test rather than an iteration. Use this when you have a fixed slot index and want to decide whether to do dirty-driven work on it — avoids the per-cycle materialisation that iter_updated_indices().collect::<HashSet<_>>() would force.

pub fn get_valid(&self, index: usize) -> Option<&V>

Returns a reference to slot index if (and only if) it is valid. The Option-like read accessor: mirrors Option::as_ref and forces callers to match on Some / None before reaching the inner value.

pub fn commit(&mut self, index: usize, value: V)

Write value into slot index, mark the slot valid, and mark it dirty. Panics if index is out of bounds.

pub fn update<F>(&mut self, index: usize, f: F)

where F: FnOnce(&mut V),

Apply f to slot index in place, then mark the slot valid and dirty.

The point of this method is to mutate a large V without moving in a fresh value the way Vector::commit does. For a wide value type, commit(i, fresh) copies the whole struct in; update(i, |v| v.field = new_field) writes only the bytes that changed.

The closure sees whatever the slot currently stores — the prior committed value, the placeholder from a non- Vector::push_committed Vector::push, or stale bytes from a slot that was Vector::invalidated. Callers that care about the prior validity should check Vector::is_valid / Vector::get_valid first.

Panics if index is out of bounds.

pub fn invalidate(&mut self, index: usize)

Mark slot index invalid and dirty. The slot retains its prior data; it just becomes invisible to readers using Vector::get_valid. Panics if index is out of bounds.

pub fn slot_writer(&mut self, index: usize) -> SlotWriter<'_, V>

Acquire a one-shot writer for slot index. The returned SlotWriter is #[must_use] and must be consumed via SlotWriter::commit or SlotWriter::invalidate; dropping it without consumption triggers a debug_assert! in debug builds.

Panics if index is out of bounds.

impl<V> Vector<V>

pub fn iter_updated_valid(&self) -> IterUpdatedValidItems<'_, V>

Iterate dirty slots in ascending index order, yielding (index, Some(&V)) for slots that are also valid and (index, None) for dirty slots that are invalid.

pub fn iter_updated_indices(&self) -> IterUpdatedIndices<'_>

Iterate indices of dirty slots in ascending order. Skips the validity check and data lookup that Vector::iter_updated_valid performs — useful when you only need the slot indices, e.g. to drive a parallel walk over another Vector or external array keyed by the same slot.

Trait Implementations

impl<V> Default for Vector<V>

fn default() -> Vector<V>

Returns the “default value” for a type.

impl<V> Reset for Vector<V>

type Error = Error

Clears the dirty bits and indices. Does not touch validity bits: a slot that was valid before reset stays valid after reset. Dirty is per-cycle; validity is multi-cycle.

fn reset(&mut self) -> Result<(), Error>

Clear per-cycle dirty state.

impl<V> Updated for Vector<V>

fn is_updated(&self) -> bool

Whether the value changed this cycle.