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
- 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.
- 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.
- Asynchronous Interface: All operations return Future handles, aligning with the framework's non-blocking concurrency model and signaling a synchronization barrier.
- Conactive Bridge: It serves as the primary gateway for Async proxies to interact with a cell's internal cytoplasm safely.
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:
Constructors
Properties
Methods
-
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
set(
T? state) → Future< void> - Sets the current state asynchronously, ensuring the write is performed within a thread-safe State Commitment Phase.
-
toString(
) → String -
A string representation of this object.
inherited
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited