Passivation

Passivation is a graceful stop of an idle actor: queued messages drain, postStop runs, and the actor is removed. You choose it per actor. An actor spawned without a strategy is long-lived and runs until it is explicitly stopped.

Passivation strategies are live objects. They cannot ride a Props spawn.

import { DefaultPassivationTimeout, MessagesCountBasedStrategy, TimeBasedStrategy } from "@tochemey/nodeakt";

await system.spawn("cache", new Cache(), {
  passivationStrategy: new TimeBasedStrategy(DefaultPassivationTimeout), // 120_000 ms
});

Strategies

Class	Passivates when
LongLivedStrategy (default)	Never.
TimeBasedStrategy(timeout)	The actor has processed no message for timeout milliseconds. timeout must be a positive finite number; otherwise the constructor throws RangeError.
MessagesCountBasedStrategy(maxMessages)	The actor has processed maxMessages messages. maxMessages must be a positive integer; otherwise RangeError.

DefaultPassivationTimeout is 120_000 (two minutes). It is a suggested idle window, not applied unless you construct a TimeBasedStrategy with it.

PassivationStrategy is the union of these three classes. It is not an open interface: the runtime only schedules the strategies above.

Idle

The scheduler passivates a time-based actor only when it is idle: no message is being processed, the mailbox is empty, the stash is empty, and no request is in flight. A stashed message counts as pending work because stopping would drop it.

Time-based scheduling uses one shared timer for the system. Message processing only writes a timestamp; when the timer fires, each due actor is re-checked against its latest activity and rescheduled if it ran in the meantime.

Message-count strategies involve no timer: the actor passivates itself after it has processed the configured number of messages.