Module flat_combine 

Caller-driven flat combining for batched operation dispatch.

When multiple event sources (timers, background tasks, input) post operations concurrently, submitters enqueue them under a short queue lock and whichever thread calls FlatCombiner::combine acts as the combiner: it drains the queue and executes ALL pending operations in one pass while holding the state lock, keeping data hot in L1 cache.

Unlike classic flat combining, there is no combiner election and submitters do not wait for results: operations are fire-and-forget, and nothing runs until some thread explicitly polls combine() (or combine_with). Operations still queued when the FlatCombiner is dropped are discarded, and the publication queue is unbounded — the polling cadence is the backpressure.

When to Use

Use this instead of a bare Mutex when:

• Multiple threads/tasks post operations to shared state
• A natural polling point exists (e.g., once per frame/tick)
• Operations are short (the combiner shouldn’t hold the lock too long)
• Batching is beneficial (e.g., coalescing events, reducing redraws)

Example

use ftui_runtime::flat_combine::FlatCombiner;

let combiner = FlatCombiner::new(Vec::<String>::new());

// Submit operations (from any thread)
combiner.submit(|state| state.push("event-a".into()));
combiner.submit(|state| state.push("event-b".into()));

// Combiner drains and applies all pending ops in one pass
let count = combiner.combine();
assert_eq!(count, 2);

// Direct execution when no contention
let len = combiner.execute(|state| state.len());
assert_eq!(len, 2);

Structs

CombinerStats

Statistics for monitoring flat combining performance.

FlatCombiner

Flat combining dispatcher for batched operation execution.