EphemeralPolicy<C extends Cell> class
Advanced
Advanced · Ephemeral Policy
Defines the Lifecycle Governance for transient reactive nodes.
EphemeralPolicy gives a Cell — or any cell-backed node such as a
Tissue collection — a finite operational life. The framework reclaims
the node automatically when a time budget (duration) elapses or an
event budget (eventLimit) is exhausted. This prevents memory leaks and
guarantees that transient state never outlives its usefulness.
What constitutes a governed cell
A cell is governed when it has an EphemeralPolicy, either directly or inherited from upstream:
- Hosted (local) policy — the policy is stored in the cell's own
Nucleus, or in its
principalchain (which is how a deputy inherits the policy of the nucleus it extends). This is whatCell.governed(ephemeralPolicy: ...),Cell.deputy(ephemeralPolicy: ...), and theTissue*Nucleusfactories establish. The cell ticks this policy for its own activity. - Upstream (bind) policy — when the cell hosts no policy of its own,
the framework walks up the upstream
Cell.bindchain and adopts the first policy it finds there. This is the "head owns the body" rule: a node bound to a governed head reportsisGoverned == trueand mirrors the head'sisInvalidatedstate.
A hosted policy always takes precedence over one found upstream, so a body part can deliberately override the policy inherited from the head of its reactive graph.
How the policy works
You provide two callbacks:
onEvent: invoked whenever the governed cell ticks the policy for an interaction (a pulse flowing through the cell, an action, a link, or a data mutation). Return the neweventscount — a usage meter, an error budget, or any other quota you choose.onInvalidate: invoked when the policy reaches its terminal condition. Perform any cleanup and returntrueto confirm the node was reclaimed.
Example: cache with a 5-minute TTL
final cachePolicy = EphemeralPolicy(
duration: Duration(minutes: 5),
onEvent: (object, {required cell, policy, arguments, user}) {
// Reset the counter on a cache hit – extends the TTL window.
return (events: 0);
},
onInvalidate: (nucleus) {
// Clear cache entries.
return true;
},
);
final cell = Cell.governed(
ephemeralPolicy: cachePolicy,
context: Context.system,
);
See also:
- Cell.isGoverned and Cell.isInvalidated for how governance cascades.
- Cell.governed and Cell.deputy for attaching a policy to a cell.
- PulseEphemeralPolicy — the equivalent lifecycle for individual pulses.
Constructors
-
EphemeralPolicy({required ({int events}) onEvent(dynamic object, {dynamic arguments, required C cell, required EphemeralPolicy<
Cell> policy, dynamic user}), required bool onInvalidate(Nucleus nucleus), int? eventLimit, Duration? duration, dynamic user}) - Synthesizes a new EphemeralPolicy to manage the Lifecycle Reclamation of a transient cell.
Properties
- duration → Duration?
-
The maximum Time-To-Live (TTL) for the associated cell.
no setter
- eventLimit → int?
-
The maximum threshold of
eventspermitted before the cell is automatically reclaimed.no setter - events → int
-
The current count of Targeted Events tracked by the lifecycle policy.
no setter
- hashCode → int
-
The hash code for this object.
no setterinherited
- isInvalidated → bool
-
Returns
trueif the Cell has reached its terminal state and has been reclaimed.no setter - runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
Methods
-
call(
dynamic object, {required C cell, dynamic arguments}) → void - Orchestrates the Lifecycle Reclamation Check across multiple interaction vectors.
-
dispose(
) → void - Disposes of active timers to prevent memory leaks.
-
invalidate(
C cell) → bool - Manually runs the invalidation sequence of this policy.
-
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