Coordinated Shutdown

The actor system supports coordinated shutdown with configurable hooks and timeout.

Shutdown sequence

When Stop(ctx) is called, the system:

Stops background services (eviction, passivation, scheduler)
Runs coordinated shutdown hooks (if registered)
Stops datacenter services (if enabled)
Snapshots cluster state (if clustered)
Shuts down user actors depth-first (children before parents)
Deactivates all grains
Shuts down system actors
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

package actor

type ShutdownHook interface {
    Execute(ctx context.Context, actorSystem ActorSystem) error
    Recovery() *ShutdownHookRecovery
}

Method	Purpose
Execute	Run cleanup logic. Use the actor system for final operations.
Recovery	Return retry and recovery configuration for failures.

Recovery strategies

Strategy	Behavior
`ShouldFail`	Stop shutdown on hook failure
`ShouldRetryAndFail`	Retry, then stop if still failing
`ShouldSkip`	Skip failed hook, continue
`ShouldRetryAndSkip`	Retry, 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.

Reactive Streams Architecture Overview

Getting Started

Actor

Grains

Remoting

Cluster

Observability

Advanced

Architecture

Contribution

Reference

Meta Framework

Coordinated Shutdown

Shutdown sequence

Shutdown hooks

The ShutdownHook interface

Recovery strategies

Configuring recovery

Shutdown timeout

​Shutdown sequence

​Shutdown hooks

​The ShutdownHook interface

​Recovery strategies

​Configuring recovery

​Shutdown timeout

Shutdown sequence

Shutdown hooks

The ShutdownHook interface

Recovery strategies

Configuring recovery

Shutdown timeout