Package akka.cluster.singleton

Class ClusterSingletonManager

  • All Implemented Interfaces:
    Actor, ActorLogging, FSM<ClusterSingletonManager.State,​ClusterSingletonManager.Data>, Listeners
    public class ClusterSingletonManager
extends java.lang.Object
implements Actor, FSM<ClusterSingletonManager.State,​ClusterSingletonManager.Data>
    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. 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 Member.isOlderThan(akka.cluster.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 JVM 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.

    Use factory method props(akka.actor.Props, java.lang.Object, akka.cluster.singleton.ClusterSingletonManagerSettings) to create the Props for the actor.

    Not intended for subclassing by user code.

    param: singletonProps Props of the singleton actor instance.

    param: terminationMessage When handing over to a new oldest node this terminationMessage is sent to the singleton actor to tell it to finish its work, close resources, and stop. The hand-over to the new oldest node is completed when the singleton actor is terminated. Note that PoisonPill is a perfectly fine terminationMessage if you only need to stop the actor.

    param: settings see ClusterSingletonManagerSettings