ClusterSingletonManager

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 akka.cluster.Member#isOlderThan. 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 ClusterSingletonManager#props to create the akka.actor.Props for the actor.

Not intended for subclassing by user code.

Annotations: @DoNotInherit()
Source: ClusterSingletonManager.scala

Linear Supertypes

FSM[ClusterSingletonManager.State, Data], ActorLogging, Listeners, Actor, AnyRef, Any

Type Hierarchy

Instance Constructors

new ClusterSingletonManager(singletonProps: Props, terminationMessage: Any, settings: ClusterSingletonManagerSettings)

singletonProps
akka.actor.Props of the singleton actor instance.
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 akka.actor.PoisonPill is a perfectly fine terminationMessage if you only need to stop the actor.
settings
see ClusterSingletonManagerSettings

Type Members

type Event = actor.FSM.Event[Data]

Definition Classes
FSM
type Receive = PartialFunction[Any, Unit]

Definition Classes
Actor
type State = actor.FSM.State[ClusterSingletonManager.State, Data]

Definition Classes
FSM
type StateFunction = PartialFunction[Event, State]

Definition Classes
FSM
type StopEvent = actor.FSM.StopEvent[ClusterSingletonManager.State, Data]

Definition Classes
FSM
type Timeout = Option[FiniteDuration]

Definition Classes
FSM
final class TransformHelper extends AnyRef

Definition Classes
FSM
type TransitionHandler = PartialFunction[(ClusterSingletonManager.State, ClusterSingletonManager.State), Unit]

Definition Classes
FSM

Value Members

final def !=(arg0: Any): Boolean

Definition Classes
AnyRef → Any
final def ##(): Int

Definition Classes
AnyRef → Any
def +(other: String): String

Implicit information
This member is added by an implicit conversion from ClusterSingletonManager to any2stringadd[ClusterSingletonManager] performed by method any2stringadd in scala.Predef.
Definition Classes
any2stringadd
val ->: actor.FSM.->.type

Definition Classes
FSM
final def ==(arg0: Any): Boolean

Definition Classes
AnyRef → Any
val Event: actor.FSM.Event.type

Definition Classes
FSM
val StateTimeout: actor.FSM.StateTimeout.type

Definition Classes
FSM
val StopEvent: actor.FSM.StopEvent.type

Definition Classes
FSM
def addRemoved(node: UniqueAddress): Unit
def aroundPostRestart(reason: Throwable): Unit

Attributes
protected[akka]
Definition Classes
Actor
Annotations
@InternalApi()
def aroundPostStop(): Unit

Attributes
protected[akka]
Definition Classes
Actor
Annotations
@InternalApi()
def aroundPreRestart(reason: Throwable, message: Option[Any]): Unit

Attributes
protected[akka]
Definition Classes
Actor
Annotations
@InternalApi()
def aroundPreStart(): Unit

Attributes
protected[akka]
Definition Classes
Actor
Annotations
@InternalApi()
def aroundReceive(receive: actor.Actor.Receive, msg: Any): Unit

Attributes
protected[akka]
Definition Classes
Actor
Annotations
@InternalApi()
final def asInstanceOf[T0]: T0

Definition Classes
Any
final def cancelTimer(name: String): Unit

Definition Classes
FSM
def cleanupOverdueNotMemberAnyMore(): Unit
def clone(): AnyRef

Attributes
protected[java.lang]
Definition Classes
AnyRef
Annotations
@throws( ... )
val cluster: Cluster
implicit val context: ActorContext

Definition Classes
Actor
val coordShutdown: CoordinatedShutdown
def ensuring(cond: (ClusterSingletonManager) ⇒ Boolean, msg: ⇒ Any): ClusterSingletonManager

Implicit information
This member is added by an implicit conversion from ClusterSingletonManager to Ensuring[ClusterSingletonManager] performed by method Ensuring in scala.Predef.
Definition Classes
Ensuring
def ensuring(cond: (ClusterSingletonManager) ⇒ Boolean): ClusterSingletonManager

Implicit information
This member is added by an implicit conversion from ClusterSingletonManager to Ensuring[ClusterSingletonManager] performed by method Ensuring in scala.Predef.
Definition Classes
Ensuring
def ensuring(cond: Boolean, msg: ⇒ Any): ClusterSingletonManager

Implicit information
This member is added by an implicit conversion from ClusterSingletonManager to Ensuring[ClusterSingletonManager] performed by method Ensuring in scala.Predef.
Definition Classes
Ensuring
def ensuring(cond: Boolean): ClusterSingletonManager

Implicit information
This member is added by an implicit conversion from ClusterSingletonManager to Ensuring[ClusterSingletonManager] performed by method Ensuring in scala.Predef.
Definition Classes
Ensuring
final def eq(arg0: AnyRef): Boolean

Definition Classes
AnyRef
def equals(arg0: Any): Boolean

Definition Classes
AnyRef → Any
def finalize(): Unit

Attributes
protected[java.lang]
Definition Classes
AnyRef
Annotations
@throws( classOf[java.lang.Throwable] )
def formatted(fmtstr: String): String

Implicit information
This member is added by an implicit conversion from ClusterSingletonManager to StringFormat[ClusterSingletonManager] performed by method StringFormat in scala.Predef.
Definition Classes
StringFormat
Annotations
@inline()
final def getClass(): Class[_]

Definition Classes
AnyRef → Any
def getNextOldestChanged(): Unit
def gossip(msg: Any)(implicit sender: ActorRef): Unit

Attributes
protected
Definition Classes
Listeners
final def goto(nextStateName: ClusterSingletonManager.State): State

Definition Classes
FSM
def gotoHandingOver(singleton: Option[ActorRef], handOverTo: Option[ActorRef]): State
def gotoOldest(): State

Annotations
@InternalStableApi()
def gotoStopping(singleton: ActorRef): State
def handOverDone(handOverTo: Option[ActorRef]): State
def handleOldestChanged(singleton: Option[ActorRef], oldestOption: Option[UniqueAddress]): State
def hashCode(): Int

Definition Classes
AnyRef → Any
final def initialize(): Unit

Definition Classes
FSM
final def isInstanceOf[T0]: Boolean

Definition Classes
Any
final def isTimerActive(name: String): Boolean

Definition Classes
FSM
val lease: Option[Lease]
val leaseRetryInterval: FiniteDuration
def listenerManagement: actor.Actor.Receive

Attributes
protected
Definition Classes
Listeners
val listeners: Set[ActorRef]

Attributes
protected
Definition Classes
Listeners
def log: LoggingAdapter

Definition Classes
ActorLogging
def logInfo(template: String, arg1: Any, arg2: Any, arg3: Any): Unit
def logInfo(template: String, arg1: Any, arg2: Any): Unit
def logInfo(template: String, arg1: Any): Unit
def logInfo(message: String): Unit
def logTermination(reason: Reason): Unit

Attributes
protected
Definition Classes
FSM
val maxHandOverRetries: Int
val maxTakeOverRetries: Int
val memberExitingProgress: Promise[Done]
final def ne(arg0: AnyRef): Boolean

Definition Classes
AnyRef
final def nextStateData: Data

Definition Classes
FSM
final def notify(): Unit

Definition Classes
AnyRef
final def notifyAll(): Unit

Definition Classes
AnyRef
var oldestChangedBuffer: ActorRef
var oldestChangedReceived: Boolean
final def onTermination(terminationHandler: PartialFunction[StopEvent, Unit]): Unit

Definition Classes
FSM
final def onTransition(transitionHandler: TransitionHandler): Unit

Definition Classes
FSM
def peer(at: Address): ActorSelection
def postRestart(reason: Throwable): Unit

Definition Classes
Actor
Annotations
@throws( classOf[java.lang.Exception] )
def postStop(): Unit

Definition Classes
ClusterSingletonManager → FSM → Actor
def preRestart(reason: Throwable, message: Option[Any]): Unit

Definition Classes
Actor
Annotations
@throws( classOf[java.lang.Exception] )
def preStart(): Unit

Definition Classes
ClusterSingletonManager → Actor
def receive: Receive

Definition Classes
FSM → Actor
val removalMargin: FiniteDuration
var removed: Map[UniqueAddress, Deadline]
def scheduleDelayedMemberRemoved(m: Member): Unit
implicit final val self: ActorRef

Definition Classes
Actor
var selfExited: Boolean
def selfMemberExited(): Unit
val selfUniqueAddressOption: Some[UniqueAddress]
final def sender(): ActorRef

Definition Classes
Actor
final def setStateTimeout(state: ClusterSingletonManager.State, timeout: Timeout): Unit

Definition Classes
FSM
final def setTimer(name: String, msg: Any, timeout: FiniteDuration, repeat: Boolean): Unit

Definition Classes
FSM
final def startWith(stateName: ClusterSingletonManager.State, stateData: Data, timeout: Timeout): Unit

Definition Classes
FSM
final def stateData: Data

Definition Classes
FSM
final def stateName: ClusterSingletonManager.State

Definition Classes
FSM
final def stay(): State

Definition Classes
FSM
final def stop(reason: Reason, stateData: Data): State

Definition Classes
FSM
final def stop(reason: Reason): State

Definition Classes
FSM
final def stop(): State

Definition Classes
FSM
def supervisorStrategy: SupervisorStrategy

Definition Classes
Actor
final def synchronized[T0](arg0: ⇒ T0): T0

Definition Classes
AnyRef
def toString(): String

Definition Classes
AnyRef → Any
implicit final def total2pf(transitionHandler: (ClusterSingletonManager.State, ClusterSingletonManager.State) ⇒ Unit): TransitionHandler

Definition Classes
FSM
final def transform(func: StateFunction): TransformHelper

Definition Classes
FSM
def tryAcquireLease(): actor.FSM.State[ClusterSingletonManager.State, Data]
def tryGotoOldest(): State
def unhandled(message: Any): Unit

Definition Classes
Actor
final def wait(): Unit

Definition Classes
AnyRef
Annotations
@throws( ... )
final def wait(arg0: Long, arg1: Int): Unit

Definition Classes
AnyRef
Annotations
@throws( ... )
final def wait(arg0: Long): Unit

Definition Classes
AnyRef
Annotations
@throws( ... )
final def when(stateName: ClusterSingletonManager.State, stateTimeout: FiniteDuration)(stateFunction: StateFunction): Unit

Definition Classes
FSM
final def whenUnhandled(stateFunction: StateFunction): Unit

Definition Classes
FSM
def →[B](y: B): (ClusterSingletonManager, B)

Implicit information
This member is added by an implicit conversion from ClusterSingletonManager to ArrowAssoc[ClusterSingletonManager] performed by method ArrowAssoc in scala.Predef.
Definition Classes
ArrowAssoc

Shadowed Implicit Value Members

def ->[B](y: B): (ClusterSingletonManager, B)
Implicit information
This member is added by an implicit conversion from ClusterSingletonManager to ArrowAssoc[ClusterSingletonManager] performed by method ArrowAssoc in scala.Predef.
Shadowing
This implicitly inherited member is shadowed by one or more members in this class.
To access this member you can use a type ascription:
(clusterSingletonManager: ArrowAssoc[ClusterSingletonManager]).->(y)
Definition Classes
ArrowAssoc
Annotations
@inline()

Related Docs: object ClusterSingletonManager | package singleton

class ClusterSingletonManager extends Actor with FSM[State, Data]

Instance Constructors

new ClusterSingletonManager(singletonProps: Props, terminationMessage: Any, settings: ClusterSingletonManagerSettings)

Type Members

type Event = actor.FSM.Event[Data]

type Receive = PartialFunction[Any, Unit]

type State = actor.FSM.State[ClusterSingletonManager.State, Data]

type StateFunction = PartialFunction[Event, State]

type StopEvent = actor.FSM.StopEvent[ClusterSingletonManager.State, Data]

type Timeout = Option[FiniteDuration]

final class TransformHelper extends AnyRef

type TransitionHandler = PartialFunction[(ClusterSingletonManager.State, ClusterSingletonManager.State), Unit]

Value Members

final def !=(arg0: Any): Boolean

final def ##(): Int

def +(other: String): String

val ->: actor.FSM.->.type

final def ==(arg0: Any): Boolean

val Event: actor.FSM.Event.type

val StateTimeout: actor.FSM.StateTimeout.type

val StopEvent: actor.FSM.StopEvent.type

def addRemoved(node: UniqueAddress): Unit

def aroundPostRestart(reason: Throwable): Unit

def aroundPostStop(): Unit

def aroundPreRestart(reason: Throwable, message: Option[Any]): Unit

def aroundPreStart(): Unit

def aroundReceive(receive: actor.Actor.Receive, msg: Any): Unit

final def asInstanceOf[T0]: T0

final def cancelTimer(name: String): Unit

def cleanupOverdueNotMemberAnyMore(): Unit

def clone(): AnyRef

val cluster: Cluster

implicit val context: ActorContext

val coordShutdown: CoordinatedShutdown

def ensuring(cond: (ClusterSingletonManager) ⇒ Boolean, msg: ⇒ Any): ClusterSingletonManager

def ensuring(cond: (ClusterSingletonManager) ⇒ Boolean): ClusterSingletonManager

def ensuring(cond: Boolean, msg: ⇒ Any): ClusterSingletonManager

def ensuring(cond: Boolean): ClusterSingletonManager

final def eq(arg0: AnyRef): Boolean

def equals(arg0: Any): Boolean

def finalize(): Unit

def formatted(fmtstr: String): String

final def getClass(): Class[_]

def getNextOldestChanged(): Unit

def gossip(msg: Any)(implicit sender: ActorRef): Unit

final def goto(nextStateName: ClusterSingletonManager.State): State

def gotoHandingOver(singleton: Option[ActorRef], handOverTo: Option[ActorRef]): State

def gotoOldest(): State

def gotoStopping(singleton: ActorRef): State

def handOverDone(handOverTo: Option[ActorRef]): State

def handleOldestChanged(singleton: Option[ActorRef], oldestOption: Option[UniqueAddress]): State

def hashCode(): Int

final def initialize(): Unit

final def isInstanceOf[T0]: Boolean

final def isTimerActive(name: String): Boolean

val lease: Option[Lease]

val leaseRetryInterval: FiniteDuration

def listenerManagement: actor.Actor.Receive

val listeners: Set[ActorRef]

def log: LoggingAdapter

def logInfo(template: String, arg1: Any, arg2: Any, arg3: Any): Unit

def logInfo(template: String, arg1: Any, arg2: Any): Unit

def logInfo(template: String, arg1: Any): Unit

def logInfo(message: String): Unit

def logTermination(reason: Reason): Unit

val maxHandOverRetries: Int

val maxTakeOverRetries: Int

val memberExitingProgress: Promise[Done]

final def ne(arg0: AnyRef): Boolean

final def nextStateData: Data

final def notify(): Unit

final def notifyAll(): Unit

var oldestChangedBuffer: ActorRef

var oldestChangedReceived: Boolean

final def onTermination(terminationHandler: PartialFunction[StopEvent, Unit]): Unit

final def onTransition(transitionHandler: TransitionHandler): Unit

def peer(at: Address): ActorSelection

def postRestart(reason: Throwable): Unit