Cluster Singleton

Overview

A Cluster Singleton is to ensure that only one instance of a specific actor runs across an entire cluster. This approach is commonly used for tasks that require centralised coordination, resource management, or maintaining shared state within the cluster.

Features

• Single Instance: Only one instance of the singleton actor is active across all nodes in the cluster.

• Location: The singleton actor is always created on the oldest node in the cluster.

• Failover: If the oldest node shuts down or leaves the cluster, the singleton actor is automatically recreated on the next oldest node, ensuring high availability.

• Default Supervisor: The actor runs under the default actor system supervisor and directive, with no option to assign a custom mailbox.

• Access: Other actors can interact with the singleton actor using its name (alias).

Use Cases

• Coordinating distributed tasks to prevent duplicate processing.

• Managing cluster-wide shared resources, such as distributed locks.

• Acting as a centralised event aggregator or scheduler within the cluster.

Get Started

1. Cluster mode is activated via WithCluster.

2. Create a singleton actor using the method SpawnSingleton of the ActorSystem

3. Other nodes can send messages to the singleton actor using its name.

This pattern ensures both scalability and reliability while maintaining a single source of truth across the cluster.

Since a singleton can be started from any node in the cluster, it is recommended to invoke SpawnSingleton on the leader node.

Role-based Placement

You can spawn cluster singleton actors with role-aware placement. When a role is specified, the actor system selects the oldest cluster member advertising that role and spawns (or relocates) the singleton there. Nodes without the role will never host the singleton. If no members match the role, SpawnSingleton returns an error.

If no role is specified, placement falls back to the overall oldest cluster member (the default behaviour).

Singleton vs Normal Actor

Normal Actor

A normal actor is a regular actor instance created with Spawn / SpawnNamed.

• Multiplicity: you can spawn many actors of the same kind (same Go type) as long as they have different names.

• Uniqueness: the name is the identity; two actors can’t share the same name in the same system/cluster.

• Placement: created on the node you spawn it on (or via placement APIs like SpawnOn), and it may be relocatable depending on options.

• Lifecycle: can be stopped and respawned; you can run a fleet of them for throughput and scale.

Singleton actor

A singleton actor is a special cluster-wide actor created with SpawnSingleton.

• Cluster requirement: SpawnSingleton only works when the actor system is running in cluster mode.

• Multiplicity: at most one instance exists in the entire cluster for a given singleton key:

  • key = actor kind (derived from the concrete Go type via reflection)

  • or actor kind + role when you use WithSingletonRole(role)

• Name independence: the singleton guarantee is by kind(+role), not by name.

  • Spawning the same kind(+role) singleton again (even with a different name) returns ErrSingletonAlreadyExists.

• Placement:

  • Without role: hosted on the cluster coordinator.

  • With role: hosted on the oldest member that advertises the role.

  • You can call SpawnSingleton from any node; it spawns locally if the chosen host is the local node, otherwise it delegates via remoting.

• Concurrency behavior:

  • If there is a name collision during concurrent calls, SpawnSingleton checks cluster metadata:

    • if the name is already bound to the same singleton (same kind/role and marked as singleton), the call succeeds as a no-op

    • otherwise it returns ErrActorAlreadyExists

Rule of thumb

• Use a normal actor when you want many instances (scale-out).

• Use a singleton actor when you need exactly one instance per cluster for that actor kind (optionally per role).