Struct FlatCombiner 

pub struct FlatCombiner<S> { /* private fields */ }

Flat combining dispatcher for batched operation execution.

Wraps shared mutable state with a two-level locking strategy:

1. A publication queue (queue) where threads post operations
2. The shared state (state) where operations are executed

The combiner thread locks the state once, drains the queue, and executes all operations in sequence — keeping the hot data in cache and minimizing lock handoffs.

Implementations

impl<S> FlatCombiner<S>

pub fn new(state: S) -> Self

Create a new flat combiner wrapping the given shared state.

pub fn execute<R>(&self, op: impl FnOnce(&mut S) -> R) -> R

Execute a single operation directly on the shared state.

Bypasses the publication queue. Use this when you need a return value or when contention is not expected.

pub fn with_state<R>(&self, f: impl FnOnce(&S) -> R) -> R

Read from the shared state without mutation.

pub fn submit(&self, op: impl FnOnce(&mut S) + Send + 'static)

Submit an operation to the publication queue for batched execution.

The operation will be executed during the next combine call. Operations are executed in submission order within each batch.

pub fn submit_batch( &self, ops: impl IntoIterator<Item = Box<dyn FnOnce(&mut S) + Send>>, )

Submit multiple operations at once (avoids repeated lock acquisitions).

pub fn combine(&self) -> usize

Drain all pending operations and execute them as a single batch.

The combiner holds the state lock for the entire batch, keeping the data hot in L1 cache. Returns the number of operations executed.

Returns 0 if no operations are pending.

pub fn combine_with<R>( &self, around: impl FnOnce(&mut S, &dyn Fn(&mut S)) -> R, ) -> (usize, R)

Combine with a pre/post hook for additional work during the batch.

The around function receives a mutable reference to the state and a closure that executes all pending operations. This allows wrapping the batch with setup/teardown logic (e.g., marking a dirty flag, snapshotting state).

Reentrant calls back into execute, with_state, combine, or combine_with from inside around are rejected with a panic instead of deadlocking on the state mutex.

pub fn pending_count(&self) -> usize

Number of operations currently in the publication queue.

pub fn generation(&self) -> u64

Current generation counter. Incremented after each combine pass.

pub fn stats(&self) -> CombinerStats

Get a snapshot of current performance statistics.

pub fn reset_stats(&self)

Reset statistics counters.

Trait Implementations

impl<S: Debug> Debug for FlatCombiner<S>

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

Formats the value using the given formatter.