Struct SequentialReadBuffer 

pub struct SequentialReadBuffer { /* private fields */ }

Per-traversal buffer for sequential I/O optimization

Design

• Scoped to single traversal (evaporates when function returns)
• Prefetches 8 slots (32KB) after LinearDetector confirms linear pattern
• Stores decoded NodeRecordV2 for rapid access without re-decoding
• Caches edge cluster data to eliminate per-node cluster I/O

MVCC Safety

Buffer is stack-allocated per traversal. No cross-traversal data sharing means no stale data across transactions.

Implementations

impl SequentialReadBuffer

pub fn new() -> Self

Create a new empty buffer with default 8-slot prefetch window

pub fn with_prefetch_window(prefetch_window: usize) -> Self

Create buffer with custom prefetch window (for testing)

pub fn get(&self, node_id: NativeNodeId) -> Option<&NodeRecordV2>

Get node from buffer, returns None if not cached

pub fn contains(&self, node_id: NativeNodeId) -> bool

Check if node is in buffer

pub fn len(&self) -> usize

Get number of nodes currently cached

pub fn is_empty(&self) -> bool

Check if buffer is empty

pub fn insert_batch(&mut self, nodes: Vec<NodeRecordV2>)

Insert a batch of decoded nodes into buffer

pub fn insert(&mut self, node: NodeRecordV2)

Insert a single node into buffer

pub fn prefetch_from( &mut self, graph_file: &mut GraphFile, start_node_id: NativeNodeId, ) -> NativeResult<()>

Prefetch sequential slots starting from start_node_id

Reads prefetch_window slots (default 8) using NodeStore::read_slots_batch() and caches the decoded NodeRecordV2 instances.

Parameters

• graph_file: Mutable borrow for I/O operations
• start_node_id: First node ID to prefetch

Errors

Returns error if batch read fails (file I/O, decoding errors)

pub fn prefetch_clusters_from( &mut self, graph_file: &mut GraphFile, start_node_id: NativeNodeId, ) -> NativeResult<()>

Prefetch sequential slots AND their edge clusters starting from start_node_id

This extends prefetch_from() by also prefetching edge cluster data for all buffered nodes. For each node with a non-zero cluster offset, the cluster data is read and cached, eliminating per-node cluster I/O during traversal.

Parameters

• graph_file: Mutable borrow for I/O operations
• start_node_id: First node ID to prefetch

How it works

1. First calls prefetch_from() to get node slots with cluster metadata
2. For each buffered node with non-zero cluster offsets, prefetches cluster data
3. For non-sequential clusters (typical case), does individual prefetches but caches them
4. Stores raw bytes in cluster_cache indexed by cluster_offset

Benefits

• Chain traversals visit each node once, so prefetch happens once per node
• Buffer covers 8 nodes ahead, so cluster I/O is done in anticipation of need
• Eliminates per-node graph_file.read_bytes(cluster_offset, ...) calls during traversal

Errors

Returns error if batch read or cluster prefetch fails (file I/O, decoding errors)

pub fn get_cluster(&self, cluster_offset: u64) -> Option<&[u8]>

Get cached cluster data by cluster_offset

Returns a reference to the cached cluster bytes if available, None if the cluster is not in the cache.

Parameters

• cluster_offset: The file offset of the cluster (from NodeRecordV2)

Returns

• Some(&[u8]) if cluster is cached
• None if cluster not in cache (caller should fall back to file I/O)

pub fn has_cluster(&self, cluster_offset: u64) -> bool

Check if cluster data is cached

Parameters

• cluster_offset: The file offset of the cluster (from NodeRecordV2)

Returns

• true if cluster is cached, false otherwise

pub fn cluster_cache_len(&self) -> usize

Get the number of clusters currently cached (for testing)

pub fn next_prefetch_start(&self) -> Option<NativeNodeId>

Get the next prefetch start ID (for testing/monitoring)

pub fn prefetch_window(&self) -> usize

Get the current prefetch window size (for testing)

pub fn clear(&mut self)

Clear all cached nodes and clusters

Trait Implementations

impl Default for SequentialReadBuffer

fn default() -> Self

Returns the “default value” for a type.