Skip to main content
The ActorSystem is the top-level runtime that hosts actors and orchestrates messaging, clustering, remoting, and lifecycle. There is one ActorSystem per process. All actors, grains, and system services run within it.

​
Role and responsibilities

ResponsibilityDescription
Actor hostingSpawns and supervises actors under the /user guardian. Manages the actor tree and parent-child relationships.
MessagingRoutes messages locally or remotely. Serializes and deserializes when crossing node boundaries.
ClusteringWhen enabled, joins a cluster, discovers peers, and provides location-transparent actor resolution.
RemotingWhen enabled, exposes a TCP server and client for cross-node communication.
Event streamPublishes system and cluster events (ActorStarted, NodeJoined, Deadletter, etc.) to subscribers. See Event Streams.
PubSubWhen WithPubSub() or cluster is enabled, a topic actor manages application-level topics. See PubSub.
SchedulingDelivers one-time, recurring, and cron-scheduled messages to actors.
Coordinated shutdownRuns shutdown hooks, stops actors depth-first, and leaves the cluster gracefully.
See Architecture Overview for the component diagram.

​
Lifecycle

Start(ctx) → [running] → Stop(ctx) → [stopped]
  • NewActorSystem — Applies options; does not start services.
  • Start — Initializes remoting (if enabled), cluster (if enabled), scheduler, eviction, passivation, and system actors. Handle SIGTERM/SIGINT and call Stop for clean shutdown.
  • Stop — Runs coordinated shutdown hooks, stops user actors, deactivates grains, shuts down system actors, leaves cluster, stops remoting. Does not exit the process; call os.Exit if needed.
Details: Coordinated Shutdown, First Actor.

​
API surface

​
Spawning

MethodReturnsUse case
Spawn(ctx, name, actor, opts...)*PID, errorCreate a named actor locally (or on a specific host with WithHostAndPort).
SpawnOn(ctx, name, actor, opts...)*PID, errorCreate actor on a cluster node (placement: RoundRobin, Random, Local, LeastLoad) or in another data center (WithDataCenter).
SpawnFromFunc(ctx, receiveFunc, opts...)*PID, errorFunctional actor; no Actor implementation.
SpawnNamedFromFunc(ctx, name, receiveFunc, opts...)*PID, errorNamed functional actor.
SpawnRouter(ctx, name, poolSize, routeesKind, opts...)*PID, errorRouter with a pool of routees. Not cluster-relocatable.
SpawnSingleton(ctx, name, actor, opts...)*PID, errorCluster singleton; one instance across the cluster, hosted on the oldest node. See Singletons.
See Actor Lifecycle, Routers, Singletons, Clustering.

​
Resolution and inspection

MethodPurpose
ActorOf(ctx, name)Resolve a PID by name. Local or remote; use pid.IsLocal() / pid.IsRemote() when it matters.
ActorExists(ctx, name)Check if an actor exists locally or in the cluster.
Actors(ctx, timeout)Enumerate all actors visible to this node. Use sparingly; cluster scan is costly.
NumActors()Count of local actors only.
Partition(name)Partition ID for a given actor name (cluster hashing).
InCluster()Whether the system is running in cluster mode.
See PID, Location Transparency.

​
Messaging from outside

From outside the actor system (e.g. main), use system.NoSender():
  • NoSender().Tell(pid, msg) — Fire-and-forget.
  • NoSender().Ask(ctx, pid, msg, timeout) — Request-response; actor must call ctx.Response(resp).
For processes that do not run an actor system (CLI, API server, batch job), use the Client package to connect to the cluster and send messages by actor name. See Messaging.

​
Scheduling

MethodPurpose
ScheduleOnce(ctx, msg, pid, delay, opts...)One-time delivery after delay.
Schedule(ctx, msg, pid, interval, opts...)Recurring delivery at interval.
ScheduleWithCron(ctx, msg, pid, cronExpr, opts...)Cron-based delivery.
CancelSchedule(reference)Cancel by reference.
PauseSchedule(reference) / ResumeSchedule(reference)Pause or resume a scheduled task.
Use WithReference(id) when scheduling if you need to cancel, pause, or resume. See Scheduling.

​
Events and observability

MethodPurpose
Subscribe()Create an event-stream subscriber for system/cluster events. Returns eventstream.Subscriber; iterate via Iterator().
Unsubscribe(subscriber)Release subscriber; call to avoid leaks.
TopicActor()Topic actor PID for PubSub (when WithPubSub() or cluster is enabled). Send Subscribe, Unsubscribe, Publish.
Metric(ctx)Node-level metrics (actor count, mailbox sizes, throughput, uptime).
See Event Streams, PubSub, Observability.

​
Cluster and lifecycle control

MethodPurpose
Kill(ctx, name)Stop an actor by name (local or remote).
ReSpawn(ctx, name)Restart an actor; children are recreated with initial state.
Name()Actor system name.

​
Dependency injection

MethodPurpose
Inject(dependencies...)Register dependency types with the actor system after startup. Enables restoration during cluster topology changes and when creating actors on remote hosts. Must be called after Start.

​
Configuration options

Options are passed to NewActorSystem(name, opts...). Each option is documented in the source; this table groups them by concern.
OptionPurpose
Core
WithLogger(logger)Custom logger. WithLoggingDisabled() for no-op.
WithActorInitTimeout(d)Actor startup timeout.
WithActorInitMaxRetries(n)Retries for actor init.
WithShutdownTimeout(d)Total shutdown timeout (default: 3 min).
WithDefaultSupervisor(supervisor)Fallback supervisor for actors without explicit config.
Remoting & cluster
WithRemote(config)Enable remoting. See Remoting.
WithCluster(config)Enable clustering. See Clustered.
WithTLS(info)TLS for remoting.
WithoutRelocation()Disable actor relocation on node departure.
Extensions & capabilities
WithExtensions(ext...)System-wide extensions. See Extensions and Dependencies.
WithPubSub()Enable topic-based pub/sub.
WithMetrics()OpenTelemetry metrics. See Observability.
Shutdown & eviction
WithCoordinatedShutdown(hooks...)Shutdown hooks. See Coordinated Shutdown.
WithEvictionStrategy(strategy, interval)Passivation when actor count exceeds limit.
Advanced
WithPartitionHasher(hasher)Custom partition hasher for cluster placement.

​
Component relationships

The ActorSystem composes:
  • Remoting — TCP server/client; used when WithRemote is set.
  • Cluster — Membership, discovery, Olric DMap; used when WithCluster is set.
  • Event stream — In-process pub/sub; always present; topic actors when WithPubSub is set.
  • Scheduler — For ScheduleOnce, Schedule, ScheduleWithCron.
  • Extensions — Accessed via ctx.Extension(id) from actors.
Actors obtain the system via ctx.ActorSystem() (or ReceiveContext, GrainContext). Use it to spawn children, resolve actors, schedule, or access extensions. Do not store the ActorSystem in actor state; always obtain it from context.

​
Further reading