Trait StateStore 

pub trait StateStore: Send {
    // Required methods
    fn get(&self, key: &[u8]) -> Option<Bytes>;
    fn put(&mut self, key: &[u8], value: &[u8]) -> Result<(), StateError>;
    fn delete(&mut self, key: &[u8]) -> Result<(), StateError>;
    fn prefix_scan<'a>(
        &'a self,
        prefix: &'a [u8],
    ) -> Box<dyn Iterator<Item = (Bytes, Bytes)> + 'a>;
    fn range_scan<'a>(
        &'a self,
        range: Range<&'a [u8]>,
    ) -> Box<dyn Iterator<Item = (Bytes, Bytes)> + 'a>;
    fn size_bytes(&self) -> usize;
    fn len(&self) -> usize;
    fn snapshot(&self) -> StateSnapshot;
    fn restore(&mut self, snapshot: StateSnapshot);
    fn clear(&mut self);

    // Provided methods
    fn contains(&self, key: &[u8]) -> bool { ... }
    fn is_empty(&self) -> bool { ... }
    fn flush(&mut self) -> Result<(), StateError> { ... }
    fn get_or_insert(
        &mut self,
        key: &[u8],
        default: &[u8],
    ) -> Result<Bytes, StateError> { ... }
}

Trait for state store implementations.

This is the core abstraction for operator state in Ring 0 (hot path). All implementations must achieve < 500ns lookup latency for point queries.

Thread Safety

State stores are Send but not Sync. They are designed for single-threaded access within a reactor. Cross-thread communication uses SPSC queues.

Memory Model

• get() returns Bytes which is a cheap reference-counted handle
• put() copies the input to internal storage
• Snapshots are copy-on-write where possible

Dyn Compatibility

This trait is dyn-compatible for use with Box<dyn StateStore>. For generic convenience methods like get_typed and put_typed, use the StateStoreExt extension trait.

Required Methods

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

Get a value by key.

Returns None if the key does not exist.

Performance

Target: < 500ns for in-memory stores.

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

Store a key-value pair.

If the key already exists, the value is overwritten.

Errors

Returns StateError if the operation fails (e.g., disk full for memory-mapped stores).

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

Delete a key.

No error is returned if the key does not exist.

Errors

Returns StateError if the operation fails.

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

Scan all keys with a given prefix.

Returns an iterator over matching (key, value) pairs in lexicographic order.

Performance

O(log n + k) where n is the total number of keys and k is the number of matching entries.

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

Range scan between two keys (exclusive end).

Returns an iterator over keys where start <= key < end in lexicographic order.

Performance

O(log n + k) where n is the total number of keys and k is the number of matching entries.

fn size_bytes(&self) -> usize

Get approximate size in bytes.

This includes both keys and values. The exact accounting may vary by implementation.

fn len(&self) -> usize

Get the number of entries in the store.

fn snapshot(&self) -> StateSnapshot

Create a snapshot for checkpointing.

The snapshot captures the current state and can be used to restore the store to this point in time. Snapshots are serializable for persistence.

Implementation Notes

For in-memory stores, this clones the data. For memory-mapped stores, this may use copy-on-write semantics.

fn restore(&mut self, snapshot: StateSnapshot)

Restore from a snapshot.

This replaces the current state with the snapshot’s state. Any changes since the snapshot was taken are lost.

fn clear(&mut self)

Clear all entries.

Provided Methods

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

Check if a key exists.

More efficient than get() when you don’t need the value.

fn is_empty(&self) -> bool

Check if the store is empty.

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

Flush any pending writes to durable storage.

For in-memory stores, this is a no-op. For memory-mapped or disk-backed stores, this ensures data is persisted.

Errors

Returns StateError if the flush operation fails.

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

Get a value or insert a default.

If the key doesn’t exist, the default is inserted and returned.

Errors

Returns StateError if inserting the default value fails.

Implementors

impl StateStore for InMemoryStore

impl StateStore for MmapStateStore