Struct MmapStateStore 

pub struct MmapStateStore { /* private fields */ }

Memory-mapped state store implementation.

This store provides high-performance key-value storage with optional persistence via memory-mapped files. It achieves sub-500ns lookup latency by using BTreeMap for the index (enabling O(log n + k) prefix/range scans) and direct memory access for values.

Modes

• In-memory: Uses an arena allocator, fastest but not persistent
• Persistent: Uses memory-mapped file, survives restarts

Thread Safety

This store is Send but not Sync. It’s designed for single-threaded access within a reactor.

Implementations

impl MmapStateStore

pub fn in_memory(capacity: usize) -> Self

Creates a new in-memory state store with the given initial capacity.

This mode is the fastest but data is lost when the process exits.

Arguments

• capacity - Initial capacity in bytes for the data buffer

pub fn persistent( path: &Path, initial_capacity: usize, ) -> Result<Self, StateError>

Creates a new persistent state store backed by a memory-mapped file.

If the file exists, it will be opened and validated. If it doesn’t exist, a new file will be created with the given initial capacity.

Arguments

• path - Path to the state file
• initial_capacity - Initial file size if creating new

Errors

Returns StateError::Io if file operations fail, or StateError::Corruption if the file exists but has an invalid format.

pub fn is_persistent(&self) -> bool

Check if this store is persistent.

pub fn path(&self) -> Option<&Path>

Get the path to the backing file (if persistent).

pub fn compact(&mut self) -> Result<(), StateError>

Compact the store by rewriting live data.

This removes holes left by deleted entries and reduces file/memory usage.

Errors

Returns StateError if the compaction fails.

pub fn fragmentation(&self) -> f64

Get the fragmentation ratio (wasted space / total space).

pub fn save_index(&self) -> Result<(), StateError>

Save the index to disk.

This writes the BTreeMap index to a separate .idx file. Format: [magic: 8B][version: 4B][last_write_pos: 8B][next_version: 8B][rkyv data]

Errors

Returns StateError::Io if the file cannot be created or written. Returns StateError::Serialization if the index cannot be serialized.

Trait Implementations

impl StateStore for MmapStateStore

fn get(&self, key: &[u8]) -> Option<Bytes>

Get a value by key.

fn get_ref(&self, key: &[u8]) -> Option<&[u8]>

Get a zero-copy reference to a value by key.

fn put(&mut self, key: &[u8], value: Bytes) -> Result<(), StateError>

Store a key-value pair.

fn delete(&mut self, key: &[u8]) -> Result<(), StateError>

Delete a key.

fn prefix_scan<'a>( &'a self, prefix: &'a [u8], ) -> Box<dyn Iterator<Item = (Bytes, Bytes)> + 'a>

Scan all keys with a given prefix.

fn range_scan<'a>( &'a self, range: Range<&'a [u8]>, ) -> Box<dyn Iterator<Item = (Bytes, Bytes)> + 'a>

Range scan between two keys (exclusive end).

fn contains(&self, key: &[u8]) -> bool

Check if a key exists.

fn size_bytes(&self) -> usize

Get approximate size in bytes.

fn len(&self) -> usize

Get the number of entries in the store.

fn snapshot(&self) -> StateSnapshot

Create a snapshot for checkpointing.

fn restore(&mut self, snapshot: StateSnapshot)

Restore from a snapshot.

fn clear(&mut self)

Clear all entries.

fn flush(&mut self) -> Result<(), StateError>

Flush any pending writes to durable storage.

fn is_empty(&self) -> bool

Check if the store is empty.

fn get_or_insert( &mut self, key: &[u8], default: &[u8], ) -> Result<Bytes, StateError>

Get a value or insert a default.