PropagationStrategy enum
Defines the tactical execution models for Pulse Propagation within the Cell framework's reactive graph.
The PropagationStrategy governs the temporal and behavioral characteristics of how a stimulus (a Pulse) travels from a source Cell through its Synapses to downstream observers. By selecting a strategy, developers can optimise for latency, throughput, or stability, essentially defining the "metabolic rate" of specific branches in the reactive graph.
When to use
- You typically set a strategy via a PropagationPolicy when creating synapses:
Choose the strategy that matches your use case – most common arefinal synapses = Synapses( policy: PropagationPolicy( strategy: PropagationStrategy.debounced, debounceTime: Duration(milliseconds: 300), ), );immediate(default),debounced(for user input), andthrottled(for rate‑limiting). - immediate: For critical state updates that must be synchronous.
- async: To break deep recursion or offload to the event loop.
- debounced: For search‑as‑you‑type, where only the final value matters.
- throttled: For rate‑limiting high‑frequency events (e.g., scroll).
- batched: For aggregating multiple updates into one (e.g., logging).
- audit: To get the latest value at a fixed interval.
- debounceLeading: To respond immediately to the first event, then wait.
- persistent: To replay the last state to new observers.
How it works
- The strategy is applied at the egress point – when a pulse is about to be broadcast to observers.
- The policy holds the strategy and any timing parameters.
- The synapses implementation switches on the strategy to determine how to buffer, delay, or batch outgoing pulses.
- Each strategy has a specific behaviour; see the individual enum values for details.
Example: Debounced Search
final searchSynapses = Synapses<String, Cell>(
policy: PropagationPolicy(
strategy: PropagationStrategy.debounced,
debounceTime: Duration(milliseconds: 300),
),
);
See also:
- PropagationPolicy – the configuration container.
- Synapses – the distribution network that uses the policy.
Values
- immediate → const PropagationStrategy
-
The Default Synchronous strategy. Pulses are delivered immediately and recursively within the current execution pulse.
- Behavior: When a cell is triggered, it immediately invokes the receptors of all linked cells on the same stack frame.
- Use Case: Ideal for critical state logic, validation rules, and scenarios where "Tearing" (inconsistent state between related nodes) must be strictly avoided.
- Trade-off: High-frequency updates can lead to UI jank or temporary blocking of the event loop if the downstream graph is deep.
- async → const PropagationStrategy
-
The Microtask Deferral strategy. Pulses are scheduled to be broadcast on the next turn of the event loop.
- Behavior: Uses
FutureorscheduleMicrotaskto decouple the source trigger from the observer execution. - Use Case: Beneficial for breaking up long execution chains and ensuring the current function returns before downstream side effects begin.
- Trade-off: Introduces a small amount of latency and breaks immediate synchronous execution flow.
- Behavior: Uses
- batched → const PropagationStrategy
-
The Accumulative Processing strategy. Multiple signals are collected into a buffer and delivered as a single unit.
- Behavior: Pulses are held in a
bufferuntil a specificbatchSizeis reached or a time window expires. They are then delivered as a single Pulse containing a collection of payloads. - Use Case: High-throughput scenarios like logging, bulk database writes, or multi-item UI updates where processing individuals would be inefficient.
- Trade-off: Increased memory overhead for the buffer and delayed delivery for the first items in the batch.
- Behavior: Pulses are held in a
- buffered → const PropagationStrategy
-
The Temporal Aggregation strategy for lossless signal delivery.
- Behavior: Pulses are accumulated in an internal queue during a
deterministic time window. Unlike throttled or debounced, no
intermediate signals are discarded. Once the
throttleTimeexpires, all captured pulses are broadcast as a single composite event. - Use Case: Ideal for high-density telemetry, audit trails, and I/O-heavy operations (like database persistence or network logging) where preserving every event is critical, but processing them individually is inefficient.
- Trade-off: Introduces a delivery delay for all signals in the buffer equal to the remaining duration of the current temporal cycle, and increases memory pressure proportional to the burst volume.
- Memory: Requires temporary heap storage for the accumulated pulses until the flush occurs.
- Behavior: Pulses are accumulated in an internal queue during a
deterministic time window. Unlike throttled or debounced, no
intermediate signals are discarded. Once the
- debounced → const PropagationStrategy
-
The Trailing Edge strategy. Delivery is delayed until a specified period of "silence" has passed.
- Behavior: Each new pulse resets a
debouncedtimer. The pulse is only broadcast if no new signals are received within that window. - Use Case: Search-as-you-type inputs, window resizing, or any scenario where only the final state after a burst of activity is relevant.
- Trade-off: Pulses that arrive during the burst are discarded; only the last one survives.
- Behavior: Each new pulse resets a
- throttled → const PropagationStrategy
-
The Fixed Frequency strategy. Ensures signals are delivered at a controlled, maximum rate.
- Behavior: The first pulse is delivered immediately, and a
throttledtimer starts. Subsequent signals during this window are ignored until the timer expires. - Use Case: Limiting expensive operations like scroll event listeners, API rate-limiting, or physical hardware sensors that emit more data than the consumer needs.
- Trade-off: Intermediate data points between throttle ticks are lost, providing a "sampled" view of the state.
- Behavior: The first pulse is delivered immediately, and a
- audit → const PropagationStrategy
-
The Trailing-Edge Sampling strategy. Ensures the latest state within a periodic window is delivered.
- Behavior: Similar to throttled, but instead of delivering the
first pulse of a window, it delivers the most recent pulse received
when the
throttleTimeexpires. - Use Case: Real-time dashboards or telemetry where you need the freshest data point at a fixed frequency, without the "silence" requirement of debounced.
- Trade-off: Introduces a constant latency equal to the
throttleTime.
- Behavior: Similar to throttled, but instead of delivering the
first pulse of a window, it delivers the most recent pulse received
when the
- debounceLeading → const PropagationStrategy
-
The Leading-Edge Debounce strategy. Delivers the first signal and silences subsequent signals during the window.
- Behavior: High-responsiveness. Delivers the first pulse
immediately, then ignores all others until the
throttleTimesilence window is met. - Use Case: Button debouncing where the user expects immediate UI feedback, but the backend must be protected from double-clicks.
- Behavior: High-responsiveness. Delivers the first pulse
immediately, then ignores all others until the
- persistent → const PropagationStrategy
-
The State-Preserving Relink strategy. Ensures newly linked observers receive the last known state.
Properties
- hashCode → int
-
The hash code for this object.
no setterinherited
- index → int
-
A numeric identifier for the enumerated value.
no setterinherited
- name → String
-
Available on Enum, provided by the EnumName extension
The name of the enum value.no setter - runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
Methods
-
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
toString(
) → String -
A string representation of this object.
inherited
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited
Constants
-
values
→ const List<
PropagationStrategy> - A constant List of the values in this enum, in order of their declaration.