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

StrategyConstructorTrigger
TimeBasedStrategypassivation.NewTimeBasedStrategy(timeout)No message within the configured duration
MessagesCountBasedStrategypassivation.NewMessageCountBasedStrategy(maxMessages)Actor has processed at least maxMessages since the strategy was registered
LongLivedStrategypassivation.NewLongLivedStrategy()Never passivate (opt-out)

​
Usage

pid, err := system.Spawn(ctx, "cache", actor,
    actor.WithPassivationStrategy(passivation.NewTimeBasedStrategy(5*time.Minute)))
Or use WithLongLived() to opt out: 
pid, err := system.Spawn(ctx, "service", actor, actor.WithLongLived())

​
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 passivates 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 policies

PolicyDescription
LRULeast Recently Used — passivate actors with the oldest LatestActivityTime
LFULeast Frequently Used — passivate actors with the lowest ProcessedCount
MRUMost Recently Used — passivate actors with the newest LatestActivityTime

​
Configuration

strategy, err := actor.NewEvictionStrategy(1000, actor.LRU, 20)
// limit=1000, policy=LRU, percentage=20
system, _ := actor.NewActorSystem("app",
    actor.WithEvictionStrategy(strategy, 5*time.Second))
ParameterPurpose
limitMaximum number of active actors before eviction runs. Must be > 0.
policyactor.LRU, actor.LFU, or actor.MRU
percentagePercentage of actors to passivate when over limit (0–100). Clamped automatically.
intervalHow often the eviction engine runs (e.g. 5*time.Second)

​
Behavior

  • The eviction loop runs at the configured interval.
  • When NumActors() > limit, actors are selected by policy and passivated via 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

AspectPer-actor passivationSystem eviction
ScopePer actorNode-wide
TriggerIdle timeout or message countTotal actors > limit
ConfigWithPassivationStrategy(strat) at spawnWithEvictionStrategy(strat, interval) at system creation
LongLivedOpts out of per-actor passivationDoes not opt out; can still be evicted