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:

  1. Hosted (local) policy — the policy is stored in the cell's own Nucleus, or in its principal chain (which is how a deputy inherits the policy of the nucleus it extends). This is what Cell.governed(ephemeralPolicy: ...), Cell.deputy(ephemeralPolicy: ...), and the Tissue*Nucleus factories establish. The cell ticks this policy for its own activity.
  2. Upstream (bind) policy — when the cell hosts no policy of its own, the framework walks up the upstream Cell.bind chain and adopts the first policy it finds there. This is the "head owns the body" rule: a node bound to a governed head reports isGoverned == true and mirrors the head's isInvalidated state.

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 new events count — 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 return true to 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:

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 events permitted 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 true if 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

Static Methods

mask({required Function onEvent, required Function onInvalidate, int? eventLimit, Duration? duration, dynamic user}) → Record
Generates a memory-optimized Flyweight Record for the policy.