Struct ImmutableCsr 

pub struct ImmutableCsr { /* private fields */ }

Packed immutable adjacency of one group.

hot_entries/cold_entries hold every row back to back in row order, each row sorted by (endpoint, rank, edge_id); degrees[row] is the row length and offsets[row] its start inside the halves. Empty rows contribute no slots. offsets is memory-only state rebuilt by packing and by loading.

values/valid carry the bundled inline value column slot-parallel to the packed halves when the group was packed from a valued bundled group; otherwise both stay empty and every value reads as NULL.

Implementations

impl ImmutableCsr

pub fn iter(&self, ts: u64) -> ImmutableCsrIterator<'_>

Iterate timestamp-visible entries across all rows.

pub fn iter_edges_of(&self, src_vid: u32, ts: u64) -> FrozenRowIter<'_>

Iterate timestamp-visible entries of one row without allocating.

Zero-copy counterpart of edges_of: walks the packed hot slice and assembles each record with its cold half inline, so per-vertex scans over frozen groups never touch the allocator. Out-of-range rows yield an empty iterator.

pub fn iter_all(&self) -> ImmutableCsrIterator<'_>

Iterate every physically stored entry, including tombstoned ones.

impl ImmutableCsr

pub fn compact_with_cutoff( &mut self, cutoff: u64, on_edge_removed: &mut dyn FnMut(EdgeId, u64), ) -> usize

Drop GC-eligible tombstones in place without unfreezing.

Rows stay sorted because filtering preserves order; degrees, offsets and the packed halves are rebuilt tight with no reserved gaps. Live entries are untouched, so the live edge count does not change. Each dropped entry is reported through on_edge_removed for tombstone accounting above this layer.

pub fn compact_rows_batched( &mut self, vids: &[u32], cutoff: u64, on_edge_removed: &mut dyn FnMut(EdgeId, u64), ) -> usize

Reclaim a set of rows in one linear pass without unfreezing.

Production replacement for repeated compact_row calls: one filter over the packed halves plus one offset rebuild reclaims any number of rows for a single table-proportional cost instead of one trailing memmove per row. Rows outside vids are carried verbatim; listed rows drop only cutoff-eligible tombstones and keep sorted order. An empty or maximum-cutoff request compacts nothing. Reported removals arrive in row order.

impl ImmutableCsr

pub fn new() -> ImmutableCsr

Empty table with no rows.

pub fn clear(&mut self)

Drop every entry, keeping no rows.

pub fn vertex_capacity(&self) -> usize

Row count of the packed table.

pub fn edge_count(&self) -> u64

Live edge count of the packed table.

pub fn pack_from_mutable(csr: &MutableCsr) -> ImmutableCsr

Pack every physical entry of a mutable CSR, primary rows and overflow chains merged per row, then sorted into frozen row order.

Content-preserving up to logical equivalence: tombstones travel verbatim, reserved-slot gap sentinels are dropped, and rows are sorted by (endpoint, rank, edge_id). Timestamp-filtered reads observe the same logical entries as the source table.

pub fn pack_single_from(csr: &SingleMutableCsr) -> ImmutableCsr

Pack every physical entry of a single-edge CSR, sorted the same way.

Rows hold at most one entry; the packed form is uniform with the multi-edge pack so one frozen type serves both strategies.

pub fn pack_from_pure(csr: &PureTopologyCsr) -> ImmutableCsr

Pack a pure-topology group directly into the frozen layout.

Same sorted content as routing through a temporary mutable table, without the full copy and without fabricating timestamp replicas. Pure rows carry no timestamps and no tombstones: every physically stored entry is live, so the pack walks the topology only.

pub fn pack_from_bundled(csr: &BundledCsr) -> ImmutableCsr

Pack a bundled group together with its inline values.

Same sorted content as the topology-only pack, with the value column carried slot-parallel in row order: a NULL slot stores a zero word with a cleared validity bit, mirroring the bundled layout. Freezing a valued bundled group therefore preserves its properties; unfreezing replays them back through the regular valued insert entry.

impl ImmutableCsr

pub fn used_memory_size(&self) -> usize

Approximate memory usage in bytes.

pub fn topology_encoding_report( &self, ) -> Vec<(String, TopologyColumnEncoding, usize, usize)>

Encoding report for the persisted neighbor columns.

pub fn dump(&self) -> Vec<u8>

Dump to bytes.

Format:

• rows (u64)
• edge_count (u64)
• entries_len (u64)
• encoded degrees column
• encoded endpoints column
• encoded ranks column
• encoded edge ids column
• encoded delete stamps column
• has_values flag (u64, 0 or 1)
• encoded value words column (present only when the flag is set)
• validity byte count (u64) plus raw validity bytes (flag set only)

Groups packed from non-bundled sources carry no value columns and store a zero flag. Row offsets are memory-only and never persisted; load rebuilds them.

pub fn dump_into(&self, out: &mut Vec<u8>)

Borrow-based dump into out without an intermediate owned buffer.

pub fn dump_into_with_scratch( &self, out: &mut Vec<u8>, scratch: &mut CsrDumpScratch, )

Dump reusing caller-owned column buffers.

Same bytes as Self::dump_into; a checkpoint over many groups pays one allocation per column instead of one per group. The scratch holds no state between calls.

pub fn load(&mut self, data: &[u8]) -> Result<(), StorageError>

Load from bytes.

Rejects short headers, CRC mismatches, column length mismatches, out-of-range row windows, edge count mismatches and trailing bytes.

impl ImmutableCsr

pub fn row_degree(&self, src_vid: u32) -> usize

Row length of one vertex. Out-of-range rows report zero.

pub fn edges_of(&self, src_vid: u32, ts: u64) -> Vec<Nbr>

Timestamp-filtered read of one row.

UNFILTERED single-predicate read for tests and offline tools only: filters by row delete stamp without consulting the version authority. Production traversals must use the row iterator or caller-buffer fill paths with the authority gate.

pub fn get_edge(&self, src_vid: u32, dst: VertexId, ts: u64) -> Option<Nbr>

First timestamp-visible entry matching an endpoint key.

Bisects the sorted row to the (endpoint, rank) key range, then filters inside the range by timestamp. The row sort makes edge-id order the total version order within each key.

pub fn get_edge_physical(&self, src_vid: u32, dst: VertexId) -> Option<Nbr>

First live entry matching an endpoint key without consulting snapshots.

Same key-range bisection as Self::get_edge; liveness is the raw open-deletion-stamp check instead of a timestamp filter.

pub fn physical_edges_of(&self, src_vid: u32) -> Vec<Nbr>

Every physically stored entry of one row without timestamp filtering.

Test and offline use; production scans use fill_physical_into or the row iterator instead of this allocating accessor.

pub fn fill_physical_into(&self, src_vid: u32, out: &mut Vec<Nbr>)

Fill a caller buffer with every physically stored entry of one row.

pub fn visit_physical<F>(&self, src_vid: u32, f: F)

where F: FnMut(Nbr) -> bool,

Visit every physically stored entry of one row without allocating.

pub fn visit_hot<F>(&self, src_vid: u32, f: F)

where F: FnMut(HotNbr) -> bool,

Visit every physically stored hot half of one row without allocating and without touching the stamp lines.

Hot-only counterpart of Self::visit_physical for traversals that resolve visibility through the version authority by edge_id.

pub fn is_row_sorted(&self, _src_vid: u32) -> bool

Packed rows are always sorted by (endpoint, rank, edge_id).

pub fn visit_threshold<F>( &self, src_vid: u32, lower: Option<(u32, i64)>, upper: Option<(u32, i64)>, f: F, )

where F: FnMut(Nbr) -> bool,

Visit live entries whose (endpoint, rank) key falls in the inclusive [lower, upper] range. The packed row is sorted, so the window is bisected and only the window is scanned for liveness.

pub fn fill_threshold_into( &self, src_vid: u32, lower: Option<(u32, i64)>, upper: Option<(u32, i64)>, out: &mut Vec<Nbr>, )

Fill a caller buffer with the same range content as visit_threshold.

pub fn nbr_at_offset(&self, src_vid: u32, offset: i32) -> Option<Nbr>

Read-only view of one packed slot without mutating state.

pub fn has_physical_entries(&self, vid: u32) -> bool

Whether one row holds any physically stored entry.

pub fn primary_contains(&self, src_vid: u32, edge_id: EdgeId) -> bool

Whether one row holds edge_id.

pub fn locate_edge( &self, src_vid: u32, edge_id: EdgeId, ) -> Option<(EdgePosition, Nbr)>

Locate the first entry with edge_id, returning its packed slot.

pub fn has_valued_entries(&self) -> bool

Whether this frozen group carries a bundled inline value column.

Only groups packed from a valued bundled group do; every other pack leaves the value columns empty and reads every value as NULL.

pub fn value_by_edge_id( &self, src_vid: u32, edge_id: EdgeId, ) -> Option<(u64, bool)>

Read the inline value of one edge by id within its source row.

Paired value half of a frozen topology walk: resolve the edge from the topology walk first, then read its value here.

pub fn value_by_endpoint( &self, src_vid: u32, endpoint: u32, ) -> Option<(u64, bool)>

Read the inline value of the first physical entry for one endpoint.

First-match walk like the bundled accessor: tombstones are physical entries and may match, mirroring the bundled layout where deletion clears validity but keeps the slot position.

pub fn visit_physical_with_values<F>(&self, src_vid: u32, f: F)

where F: FnMut(Nbr, Option<u64>) -> bool,

Visit every physically stored entry of one row with its inline value (None for NULL slots).

Frozen counterpart of the bundled paired traversal: topology and value stay slot-parallel after the pack reorder, so one index serves both halves.

pub fn any_valid_values(&self) -> bool

Whether any slot holds a valid inline value.

pub fn vertex_census(&self, vid: u32) -> (usize, usize, usize)

Physical entry census of one row: (live, dead, capacity).

Same live/dead predicates as the mutable census; capacity equals the row length because frozen rows carry no reserved gaps.

pub fn reclaimable_count(&self, vid: u32, cutoff: u64) -> usize

Count entries of one row reclaimable at cutoff.

Trait Implementations

impl Clone for ImmutableCsr

fn clone(&self) -> ImmutableCsr

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl CsrBase for ImmutableCsr

fn vertex_capacity(&self) -> usize

Concurrency contract: row stores carry no internal locks. Concurrent reads are safe while no writer holds exclusive access, but any concurrent mutation requires caller-side mutual exclusion. The Send + Sync bounds express single-writer transfer across threads, not lock-free concurrent writes. Multi-core scaling comes from shard-level parallelism over NodeGroup shards above this trait; the CSR lock model itself stays single-writer with no row locks.

fn edge_count(&self) -> u64

fn dump(&self) -> Vec<u8>

fn dump_into(&self, out: &mut Vec<u8>)

Append the same bytes as dump into out without an intermediate owned buffer, so checkpoint writes borrow the live topology instead of cloning it for serialization.

fn load(&mut self, data: &[u8]) -> Result<(), StorageError>

impl Debug for ImmutableCsr

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for ImmutableCsr

fn default() -> ImmutableCsr

Returns the “default value” for a type.

impl MutableCsrTrait for ImmutableCsr

fn insert_edge( &mut self, _src_vid: u32, _dst: VertexId, _edge_id: EdgeId, _ts: u64, ) -> Result<(), StorageError>

Insert an edge.

fn delete_edge( &mut self, _src_vid: u32, _edge_id: EdgeId, _ts: u64, ) -> Result<bool, StorageError>

Delete an edge by edge_id.

fn delete_edge_by_dst( &mut self, _src_vid: u32, _dst: VertexId, _ts: u64, ) -> usize

Delete all edges matching (src, dst) with full-match semantics.

fn locate_edge( &self, src_vid: u32, edge_id: EdgeId, ) -> Option<(EdgePosition, Nbr)>

Locate one stored edge, returning its row position and copy.

fn delete_edge_at_position( &mut self, _src_vid: u32, _position: EdgePosition, _expected: EdgeId, _ts: u64, ) -> Result<bool, StorageError>

Delete the edge at position when it still holds expected id.

fn revert_delete_at_position( &mut self, _src_vid: u32, _position: EdgePosition, _expected: EdgeId, _ts: u64, ) -> bool

Revert the deletion at position when it still holds expected id.

fn delete_edge_by_offset( &mut self, _src_vid: u32, _offset: i32, _ts: u64, ) -> Result<bool, StorageError>

Delete an edge by its offset position in the primary block.

fn revert_delete_by_offset( &mut self, _src_vid: u32, _offset: i32, _ts: u64, ) -> bool

Revert a deleted edge by its offset position.

fn nbr_at_offset(&self, src_vid: u32, offset: i32) -> Option<Nbr>

Read-only view of one primary slot for offset identity checks.

fn get_edge_physical(&self, src_vid: u32, dst: VertexId) -> Option<Nbr>

Locate the first live edge by endpoint without consulting snapshots.

fn physical_edges_of(&self, src_vid: u32) -> Vec<Nbr>

Every physically stored entry of one vertex without timestamp filtering.

fn fill_physical_into(&self, src_vid: u32, out: &mut Vec<Nbr>)

Fill a caller buffer with every physically stored entry of one vertex.

fn has_physical_entries(&self, vid: u32) -> bool

Whether one vertex holds any physically stored entry.

fn primary_contains(&self, src_vid: u32, edge_id: EdgeId) -> bool

Whether the primary row of one vertex holds edge_id.

fn rollback_insert(&mut self, _src_vid: u32, _edge_id: EdgeId) -> bool

Erase one just-inserted edge for insert rollback (no tombstone trace).

fn revert_delete_by_edge_id( &mut self, _src_vid: u32, _edge_id: EdgeId, _ts: u64, ) -> bool

Revert a deletion by edge id if it happened at or before ts.

fn get_edge(&self, src_vid: u32, dst: VertexId, ts: u64) -> Option<Nbr>

Get a specific edge by source and destination. Test-only row-stamp filter; production reads go through the version authority.

fn edges_of(&self, src_vid: u32, ts: u64) -> Vec<Nbr>

Get all valid edges of a vertex at the given timestamp. Test-only row-stamp filter; production reads go through the version authority. Test and offline use; production traversals use the visitor or caller-buffer fill paths instead of this allocating accessor.

fn compact_vertex_with_reporting( &mut self, _vid: u32, _cutoff: u64, _on_edge_removed: &mut dyn FnMut(EdgeId, u64), ) -> usize

Reclaim one vertex in place, dropping entries eligible for collection at cutoff and tightening live entries without touching other rows.

fn reclaimable_count(&self, vid: u32, cutoff: u64) -> usize

Count entries of one vertex that are reclaimable at cutoff.

fn vertex_needs_compact(&self, vid: u32, cutoff: u64) -> bool

Whether one vertex holds anything reclaimable at cutoff.

fn vertex_census(&self, vid: u32) -> (usize, usize, usize)

Physical entry census of one vertex: (live, dead, capacity).

fn vertex_reclaim_probe(&self, vid: u32, cutoff: u64) -> (usize, usize)

Single-walk reclaim probe of one vertex: (dead, reclaimable).

fn row_gap(&self, _vid: u32) -> usize

Reserved primary slots minus live primary entries of one row.

fn row_density(&self, _vid: u32) -> f32

Live primary entries per unit of reserved primary capacity.

fn rebalance_row(&mut self, _vid: u32) -> bool

Rebalance one row in place, pulling overflow entries into primary gaps and repacking leftover overflow. Returns true when the row no longer holds overflow. Strategies without rows report true.

fn used_memory_size(&self) -> usize

Return the approximate memory usage in bytes.

fn delete_edge_by_dst_reporting( &mut self, src_vid: u32, dst: VertexId, ts: u64, _on_deleted: &mut dyn FnMut(EdgeId), ) -> usize

Delete all edges matching (src, dst), reporting every stamped id.

fn delete_edge_by_dst_reporting_positioned( &mut self, src_vid: u32, dst: VertexId, ts: u64, on_deleted: &mut dyn FnMut(EdgeId, Option<EdgePosition>), ) -> usize

Delete all edges matching (src, dst), reporting each stamped id with its row position.