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 centralized coordination, resource management, or maintaining shared state within the cluster.

Key Characteristics

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

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