Actor Lifecycle

​

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.

​

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).