Skip to main content

​
States

A PID tracks its state through a set of flags. The main states: Use pid.IsRunning(), pid.IsSuspended(), pid.IsStopping() to query state when needed.

​
Lifecycle hooks

  • PreStart: Called once when the actor is spawned. Use for initialization.
  • Receive: Called for each message. This is where your logic lives.
  • PostStop: Called once when the actor is about to stop. Use for cleanup.

​
Spawn and stop

  • Spawn: Creates the actor, registers it, calls PreStart, and starts the mailbox dispatch loop.
  • Stop: Sends a stop signal. The actor finishes current work, runs PostStop, and is removed from the tree.
When a parent stops, all children stop first (depth-first). The order among descendants is not guaranteed.

​
Lifecycle hooks (Actor interface)

The Actor interface defines three lifecycle hooks. See Actor Model for the full interface. If PreStart returns an error, the actor is not started and the supervisor handles the failure.

​
Init timeout

PreStart runs under a deadline. When it does not complete within the init timeout, initialization fails and the actor is not started. The system-wide default is set with WithActorInitTimeout on the actor system; override it per actor with the WithInitTimeout spawn option:
A non-positive duration is ignored, leaving the system-wide timeout in effect. Child actors and relocated actors honor an explicit WithInitTimeout; without one they use the hosting node’s system-wide timeout. The override travels with remote spawns and cluster relocation so an actor keeps its configured init timeout wherever it is placed.

​
System messages

The framework injects system messages into the actor’s mailbox to drive lifecycle and coordination. These are plain Go structs in the actor package. Handle them in Receive when you need to react.

​
Lifecycle control

​
Death watch

​
Event stream (observability)

These events are published to the event stream for subscribers. You typically do not handle them in Receive unless you have a specific need:

​
Handling system messages

Add a case for the system messages you care about. For messages you don’t handle, call ctx.Unhandled() so the framework can apply default behavior (e.g., logging, event publishing).