Skip to main content
Passivation automatically stops actors to reclaim memory and resources. GoAkt supports two distinct mechanisms: per-actor passivation (idle-based) and system eviction (capacity-based).

​
Per-actor passivation

Per-actor passivation is configured per actor at spawn. The passivation manager tracks each actor and stops it when its strategy triggers. Only actors with a passivation strategy (other than LongLivedStrategy) are tracked.

​
Strategies

  • TimeBasedStrategy: Constructor: passivation.NewTimeBasedStrategy. Trigger: No message within the configured duration.
  • MessagesCountBasedStrategy: Constructor: passivation.NewMessageCountBasedStrategy. Trigger: Actor has processed at least maxMessages since the strategy was registered.
  • LongLivedStrategy: Constructor: passivation.NewLongLivedStrategy. Trigger: Never passivate (opt-out).
Only an idle actor is passivated. When a strategy triggers while the actor is processing a message or has messages queued, the actor is left alone and the passivation is tried again later: at the next deadline for a time-based strategy, as soon as the actor goes idle for a message-count one. PostStop therefore never runs alongside Receive during passivation, and messages already queued are not dropped by it.
This idle check covers the passivated actor itself, not its children. Passivation stops the children with Shutdown, which does not wait for a child’s handler to finish, so a child’s PostStop can run while its Receive is still handling a message.

​
Usage

Usage
Or use WithLongLived() to opt out:
Usage

​
When to use

  • Grains and virtual actors (default for many grains)
  • Actors with large per-instance state
  • High churn of short-lived entities

​
When to avoid

  • Long-lived services that must stay up
  • Actors that handle infrequent but critical messages

​
System eviction

System eviction is a node-wide mechanism that limits the total number of active actors. When the count exceeds the configured limit, the framework stops actors according to an eviction policy (LRU, LFU, or MRU). This is independent of per-actor passivation: system eviction can stop any user actor, including those with LongLivedStrategy. Eviction stops an actor at once, as Shutdown does: unlike per-actor passivation it does not wait for the actor to be idle, so PostStop can run while Receive is still handling a message. An evicted actor is reported as stopped, not passivated: the event stream publishes ActorStopped and the stopped metric is incremented, not passivated.

​
Eviction policies

  • LRU: Least Recently Used: stop actors with the oldest LatestActivityTime.
  • LFU: Least Frequently Used: stop actors with the lowest ProcessedCount.
  • MRU: Most Recently Used: stop actors with the newest LatestActivityTime.

​
Configuration

Configuration
  • limit: Maximum number of active actors before eviction runs. Must be > 0.
  • policy: actor.LRU, actor.LFU, or actor.MRU.
  • percentage: Percentage of actors to stop when over limit (0 to 100). Clamped automatically.
  • interval: How often the eviction engine runs (e.g. 5*time.Second). A zero or negative interval falls back to actor.DefaultEvictionInterval (5 seconds).

​
Behavior

  • The eviction loop runs at the configured interval.
  • When NumActors() > limit, actors are selected by policy and stopped with Shutdown.
  • The number of actors to evict is the greater of: (total − limit) and (percentage × total / 100).
  • System actors (reserved names) are excluded. Only user actors are eligible for eviction.

​
When to use

  • Memory or resource constraints on a node
  • Bounding actor count regardless of per-actor strategy
  • Coarse-grained capacity management

​
Comparison

  • Scope: Per-actor passivation: Per actor. System eviction: Node-wide.
  • Trigger: Per-actor passivation: Idle timeout or message count. System eviction: Total actors > limit.
  • Config: Per-actor passivation: WithPassivationStrategy at spawn. System eviction: WithEvictionStrategy at system creation.
  • LongLived: Per-actor passivation: Opts out of per-actor passivation. System eviction: Does not opt out; can still be evicted.