Struct StateChangelogBuffer 

pub struct StateChangelogBuffer { /* private fields */ }

Ring 0 SPSC changelog buffer for state mutations.

This buffer is designed for the hot path and must never allocate after initial warmup. It provides backpressure signaling when full.

Thread Safety

The buffer is designed for single-producer single-consumer access:

• Ring 0 (producer): pushes entries via push()
• Ring 1 (consumer): drains entries via drain()

Use atomic indices for thread-safe access when needed.

Example

use laminar_storage::incremental::{StateChangelogBuffer, StateChangelogEntry};

// Pre-allocate buffer for 1024 entries
let mut buffer = StateChangelogBuffer::with_capacity(1024);

// Ring 0: Push state mutations (no allocation)
let entry = StateChangelogEntry::put(1, 12345, 0, 100);
if !buffer.push(entry) {
    // Buffer full - apply backpressure
}

// Ring 1: Drain for WAL writes
let entries: Vec<_> = buffer.drain_all().collect();

Implementations

impl StateChangelogBuffer

pub const DEFAULT_CAPACITY: usize

Default buffer capacity (16K entries = 512KB).

pub fn with_capacity(capacity: usize) -> Self

Creates a new changelog buffer with the given capacity.

The buffer is pre-allocated to avoid allocation on the hot path.

Panics

Panics if capacity is 0.

pub fn new() -> Self

Creates a buffer with the default capacity.

pub fn set_epoch(&mut self, epoch: u64)

Sets the current epoch for new entries.

pub fn epoch(&self) -> u64

Returns the current epoch.

pub fn advance_epoch(&mut self) -> u64

Advances to the next epoch.

pub fn push(&self, entry: StateChangelogEntry) -> bool

Pushes an entry to the buffer (zero allocation).

Returns true if successful, false if buffer is full (backpressure).

pub fn push_put(&self, key: &[u8], mmap_offset: u64, value_len: u32) -> bool

Pushes a Put operation for the given key.

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

Pushes a Delete operation for the given key.

pub fn pop(&self) -> Option<StateChangelogEntry>

Attempts to pop a single entry (for consumer).

pub fn drain( &self, max_count: usize, ) -> impl Iterator<Item = StateChangelogEntry> + '_

Drains up to max_count entries from the buffer.

Returns an iterator over the drained entries.

pub fn drain_all(&self) -> impl Iterator<Item = StateChangelogEntry> + '_

Drains all available entries from the buffer.

pub fn len(&self) -> usize

Returns the number of entries currently in the buffer.

pub fn is_empty(&self) -> bool

Returns true if the buffer is empty.

pub fn is_full(&self) -> bool

Returns true if the buffer is full.

pub fn capacity(&self) -> usize

Returns the buffer capacity.

pub fn available(&self) -> usize

Returns available space in the buffer.

pub fn total_pushed(&self) -> usize

Returns the total number of entries pushed (including overflows).

pub fn total_drained(&self) -> usize

Returns the total number of entries drained.

pub fn overflow_count(&self) -> usize

Returns the number of overflow events (backpressure signals).

pub fn clear(&self)

Clears the buffer (for testing/reset).

pub fn checkpoint_barrier(&self) -> (u64, usize)

Creates a checkpoint barrier at the current position.

Returns the current epoch and write position for recovery.

Trait Implementations

impl Default for StateChangelogBuffer

fn default() -> Self

Returns the “default value” for a type.

impl Send for StateChangelogBuffer

impl Sync for StateChangelogBuffer