Module flat_combine 

Flat combining for batched operation dispatch under contention.

When multiple event sources (timers, background tasks, input) post operations concurrently, flat combining batches them into a single pass. One thread becomes the “combiner” and executes ALL pending operations while holding the state lock, keeping data hot in L1 cache and reducing lock acquisition overhead.

When to Use

Use flat combining instead of a bare Mutex when:

• Multiple threads/tasks post operations to shared state
• 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.