SyncBox<T> class

A synchronized variant of Box providing Thread-Safe Access and facilitating Atomic State Transitions across concurrent execution boundaries.

SyncBox implements the Synchronized State Anchor pattern. While a standard Box is optimized for zero-latency, single-threaded propagation within a reactive wave, SyncBox is designed for Conactive Integrity—ensuring that state remains consistent even when accessed or mutated by multiple asynchronous actors (such as isolates, event loop tasks, or network callbacks).

When to use

• Shared Resources: Protecting state that is updated from external asynchronous drivers like hardware sensors, sockets, or Bluetooth streams.
• Cross-Context Signals: Acting as a stable memory bridge when Pulse signals originate from background workers or different execution tiers.
• Concurrent Orchestration: Managing shared configuration in complex system hierarchies where multiple independent agents may read or write simultaneously.
• State Tearing Prevention: Ensuring that complex payloads are not read while a mutation is partially complete.

How it works

1. Serialization: Access to the underlying Box is gated by a non-recursive Lock. This ensures that only one actor can perform a read or write operation at any given moment.
2. Visibility Guarantees: It ensures that once a value is committed, it is immediately visible to all subsequent readers across different execution contexts, maintaining a Linearizable state history.
3. Asynchronous Interface: All operations return Future handles, aligning with the framework's non-blocking concurrency model and signaling a synchronization barrier.
4. Conactive Bridge: It serves as the primary gateway for Async proxies to interact with a cell's internal cytoplasm safely.

Non‑obvious

• Locking Latency: While providing safety, the synchronization barrier introduces a minor scheduling delay compared to direct Box access. Use the standard Box for pure intra-wave reactive transformations.
• Point-in-Time Consistency: The state getter returns the state at the exact moment the lock was acquired, preventing the "Lost Update" problem during high-contention cycles.
• Zero-Blocking: Because it uses the framework's internal Lock, the calling thread remains free to handle other event loop tasks while waiting for access, preventing UI jank.
• Principal Coupling: A SyncBox is strictly a proxy; it does not own the state itself but merely coordinates access to its principal Box.

Example

final sharedBox = Box<int>(0).async; // Returns a SyncBox

void updateFromNetwork(int newValue) async {
  // Thread-safe update
  await sharedBox.set(newValue);

  // Thread-safe read
  final current = await sharedBox.state;
  print('Atomic state: $current');
}

Parameters:

• T: The type of data stored in the box.

See Also:

• Box: The high-performance, non-synchronized somatic variant.
• FinalBox: For write-once, late-bound immutable anchors.
• Lock: The underlying primitive used to serialize access.