Module read_optimized 

Read-optimized concurrent stores for read-heavy, write-rare data.

Terminal UIs are read-dominated: theme colors, terminal capabilities, and animation clocks are read every frame but changed only on user action or mode switch. A traditional RwLock or Mutex adds unnecessary contention on the hot read path.

This module provides ReadOptimized<T>, a trait abstracting over wait-free read stores, plus three concrete implementations:

Store	Read	Write	Use case
ArcSwapStore	wait-free	atomic swap	Production default
RwLockStore	shared lock	exclusive lock	Baseline comparison
MutexStore	exclusive lock	exclusive lock	Baseline comparison

Constraints

• #![forbid(unsafe_code)] — all safety delegated to arc-swap.
• T: Clone + Send + Sync — required for cross-thread sharing.
• Read path allocates nothing (arc-swap load returns a guard, no clone).
• Write path allocates one Arc per store.

Example

use ftui_core::read_optimized::{ReadOptimized, ArcSwapStore};

let store = ArcSwapStore::new(42u64);
assert_eq!(store.load(), 42);

store.store(99);
assert_eq!(store.load(), 99);

Design decision: arc-swap over left-right

Both crates provide safe, lock-free reads. arc-swap was chosen because:

1. Simpler API — single ArcSwap<T> vs read/write handle pairs.
2. Lower memory — one Arc vs two full copies of T.
3. Sufficient for our types — ResolvedTheme (Copy, 76 bytes) and TerminalCapabilities (Copy, 20 bytes) are tiny; double-buffering gains nothing.
4. Zero-dependency unsafe — our crate stays #![forbid(unsafe_code)]; the unsafe is encapsulated inside arc-swap.

The seqlock crate was rejected because its API requires unsafe at the call site.

Structs

ArcSwapStore

Wait-free reads via arc_swap::ArcSwap.

MutexStore

Exclusive-lock reads via std::sync::Mutex.

RwLockStore

Shared-lock reads via std::sync::RwLock.

Traits

ReadOptimized

A concurrent store optimized for read-heavy access patterns.