Skip to main content
The actor system supports coordinated shutdown with configurable hooks and timeout.

​
Shutdown sequence

When Stop(ctx) is called, the system:
  1. Stops background services (eviction, passivation, scheduler)
  2. Runs coordinated shutdown hooks (if registered)
  3. Stops datacenter services (if enabled)
  4. Snapshots cluster state (if clustered)
  5. Shuts down user actors depth-first (children before parents)
  6. Deactivates all grains
  7. Shuts down system actors
  8. Leaves cluster and stops remoting
Shutdown is best-effort: it continues even if individual steps fail, collecting errors. A configurable shutdownTimeout (default: 3 minutes) bounds the total time.

​
Shutdown hooks

Register hooks via WithCoordinatedShutdown(hooks...) when creating the actor system. Hooks run during shutdown, before actors are stopped.

​
The ShutdownHook interface

type ShutdownHook interface {
    Execute(ctx context.Context, actorSystem ActorSystem) error
    Recovery() *ShutdownHookRecovery
}
MethodPurpose
ExecuteRun cleanup logic. Use the actor system for final operations.
RecoveryReturn retry and recovery configuration for failures.

​
Recovery strategies

StrategyBehavior
ShouldFailStop shutdown on hook failure
ShouldRetryAndFailRetry, then stop if still failing
ShouldSkipSkip failed hook, continue
ShouldRetryAndSkipRetry, then skip and continue if still failing

​
Configuring recovery

recovery := actor.NewShutdownHookRecovery(
    actor.WithShutdownHookRetry(2, time.Second),
    actor.WithShutdownHookRecoveryStrategy(actor.ShouldRetryAndSkip),
)
Pass this from your hook’s Recovery() method.

​
Shutdown timeout

Use WithShutdownTimeout(duration) when creating the actor system to bound the total shutdown time. The default is 3 minutes.