Manages singleton actor instance among all cluster nodes or a group of nodes tagged with a specific role. At most one singleton instance is running at any point in time.
The ClusterSingletonManager is supposed to be started on all nodes, or all nodes with specified role, in the cluster with ActorOf(Props, String). The actual singleton is started on the oldest node by creating a child actor from the supplied `singletonProps`.
The singleton actor is always running on the oldest member with specified role. The oldest member is determined by IsOlderThan(Member). This can change when removing members. A graceful hand over can normally be performed when current oldest node is leaving the cluster. Be aware that there is a short time period when there is no active singleton during the hand-over process.
The cluster failure detector will notice when oldest node becomes unreachable due to things like CLR crash, hard shut down, or network failure. When the crashed node has been removed (via down) from the cluster then a new oldest node will take over and a new singleton actor is created.For these failure scenarios there will not be a graceful hand-over, but more than one active singletons is prevented by all reasonable means. Some corner cases are eventually resolved by configurable timeouts.
You access the singleton actor with ClusterSingletonProxy. Alternatively the singleton actor may broadcast its existence when it is started.
Thrown when a consistent state can't be determined within the defined retry limits. Eventually it will reach a stable state and can continue, and that is simplified by starting over with a clean state. Parent supervisor should typically restart the actor, i.e. default decision.
The settings used for the ClusterSingletonManager
The proxy can be started on every node where the singleton needs to be reached and used as if it were the singleton itself. It will then act as a router to the currently running singleton instance. If the singleton is not currently available, e.g., during hand off or startup, the proxy will buffer the messages sent to the singleton and then deliver them when the singleton is finally available. The size of the buffer is configurable and it can be disabled by using a buffer size of 0. When the buffer is full old messages will be dropped when new messages are sent via the proxy.
The proxy works by keeping track of the oldest cluster member. When a new oldest member is identified, e.g. because the older one left the cluster, or at startup, the proxy will try to identify the singleton on the oldest member by periodically sending an Identify message until the singleton responds with its ActorIdentity.
Note that this is a best effort implementation: messages can always be lost due to the distributed nature of the actors involved.
Control messages used for the cluster singleton