Package org.apache.pekko.cluster.singleton

Class ClusterSingletonManager

java.lang.Object

org.apache.pekko.cluster.singleton.ClusterSingletonManager

All Implemented Interfaces:

Actor, ActorLogging, FSM<ClusterSingletonManager.State,ClusterSingletonManager.Data>, Listeners

public class ClusterSingletonManager
extends 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 pekko.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 props(org.apache.pekko.actor.Props, java.lang.Object, org.apache.pekko.cluster.singleton.ClusterSingletonManagerSettings) to create the pekko.actor.Props for the actor.

Not intended for subclassing by user code.

param: singletonProps pekko.actor.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 pekko.actor.PoisonPill is a perfectly fine terminationMessage if you only need to stop the actor.

param: settings see ClusterSingletonManagerSettings

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	ClusterSingletonManager.Data	INTERNAL API public due to the with FSM type parameters
static class	ClusterSingletonManager.Internal$	INTERNAL API
static interface	ClusterSingletonManager.State	INTERNAL API public due to the with FSM type parameters

Nested classes/interfaces inherited from interface org.apache.pekko.actor.Actor

Actor.emptyBehavior$, Actor.ignoringBehavior$

Nested classes/interfaces inherited from interface org.apache.pekko.actor.FSM

FSM.$minus$greater$, FSM.CurrentState<S>, FSM.CurrentState$, FSM.Event<D>, FSM.Event$, FSM.Failure, FSM.Failure$, FSM.FixedDelayMode$, FSM.FixedRateMode$, FSM.LogEntry<S,D>, FSM.LogEntry$, FSM.Normal$, FSM.NullFunction$, FSM.Reason, FSM.Shutdown$, FSM.SilentState<S,D>, FSM.SingleMode$, FSM.State$, FSM.StateTimeout$, FSM.StopEvent<S,D>, FSM.StopEvent$, FSM.SubscribeTransitionCallBack, FSM.SubscribeTransitionCallBack$, FSM.Timer, FSM.Timer$, FSM.TimerMode, FSM.TransformHelper, FSM.Transition<S>, FSM.Transition$, FSM.UnsubscribeTransitionCallBack, FSM.UnsubscribeTransitionCallBack$

Constructor Summary

Constructors

Constructor	Description
ClusterSingletonManager(Props singletonProps, Object terminationMessage, ClusterSingletonManagerSettings settings)

Method Summary

Modifier and Type	Method	Description
FSM.$minus$greater$	$minus$greater()	This extractor is just convenience for matching a (S, S) pair, including a reminder what the new state is.
void	addRemoved(UniqueAddress node)
void	cleanupOverdueNotMemberAnyMore()
Cluster	cluster()
ActorContext	context()	Scala API: Stores the context for this actor, including self, and sender.
CoordinatedShutdown	coordShutdown()
FSM.Event$	Event()
void	getNextOldestChanged()
FSM.State<ClusterSingletonManager.State,ClusterSingletonManager.Data>	gotoHandingOver(scala.Option<ActorRef> singleton, scala.Option<ActorRef> handOverTo)
FSM.State<ClusterSingletonManager.State,ClusterSingletonManager.Data>	gotoOldest()
FSM.State<ClusterSingletonManager.State,ClusterSingletonManager.Data>	gotoStopping(ActorRef singleton)
FSM.State<ClusterSingletonManager.State,ClusterSingletonManager.Data>	handleMemberEvent(ClusterEvent.MemberEvent event)
FSM.State<ClusterSingletonManager.State,ClusterSingletonManager.Data>	handleOldestChanged(scala.Option<ActorRef> singleton, scala.Option<UniqueAddress> oldestOption)
FSM.State<ClusterSingletonManager.State,ClusterSingletonManager.Data>	handOverDone(scala.Option<ActorRef> handOverTo)
scala.Option<Lease>	lease()
scala.concurrent.duration.FiniteDuration	leaseRetryInterval()
protected Set<ActorRef>	listeners()
MarkerLoggingAdapter	log()
void	logInfo(String message)
void	logInfo(String template, Object arg1)
void	logInfo(String template, Object arg1, Object arg2)
void	logInfo(String template, Object arg1, Object arg2, Object arg3)
void	logInfo(LogMarker marker, String message)
void	logInfo(LogMarker marker, String template, Object arg1)
void	logInfo(LogMarker marker, String template, Object arg1, Object arg2)
int	maxHandOverRetries()
int	maxTakeOverRetries()
scala.concurrent.Promise<Done>	memberExitingProgress()
ActorRef	oldestChangedBuffer()
void	oldestChangedBuffer_$eq(ActorRef x$1)
boolean	oldestChangedReceived()
void	oldestChangedReceived_$eq(boolean x$1)
protected void	org$apache$pekko$actor$Actor$_setter_$context_$eq(ActorContext x$1)	Scala API: Stores the context for this actor, including self, and sender.
protected final void	org$apache$pekko$actor$Actor$_setter_$self_$eq(ActorRef x$1)	The 'self' field holds the ActorRef for this actor.
protected void	org$apache$pekko$actor$FSM$_setter_$Event_$eq(FSM.Event$ x$1)
protected void	org$apache$pekko$actor$FSM$_setter_$StateTimeout_$eq(FSM.StateTimeout$ x$1)	This case object is received in case of a state timeout.
protected void	org$apache$pekko$actor$FSM$_setter_$StopEvent_$eq(FSM.StopEvent$ x$1)
protected void	org$apache$pekko$routing$Listeners$_setter_$listeners_$eq(Set<ActorRef> x$1)
ActorSelection	peer(Address at)
void	postStop()	User overridable callback.
boolean	preparingForFullShutdown()
void	preparingForFullShutdown_$eq(boolean x$1)
void	preStart()	User overridable callback.
static Props	props(Props singletonProps, Object terminationMessage, ClusterSingletonManagerSettings settings)	Scala API: Factory method for ClusterSingletonManager pekko.actor.Props.
scala.concurrent.duration.FiniteDuration	removalMargin()
scala.collection.immutable.Map<UniqueAddress,scala.concurrent.duration.Deadline>	removed()
void	removed_$eq(scala.collection.immutable.Map<UniqueAddress,scala.concurrent.duration.Deadline> x$1)
void	scheduleDelayedMemberRemoved(Member m)
final ActorRef	self()	The 'self' field holds the ActorRef for this actor.
boolean	selfExited()
void	selfExited_$eq(boolean x$1)
void	selfMemberExited()
scala.Some<UniqueAddress>	selfUniqueAddressOption()
FSM.StateTimeout$	StateTimeout()	This case object is received in case of a state timeout.
FSM.StopEvent$	StopEvent()
FSM.State<ClusterSingletonManager.State,ClusterSingletonManager.Data>	tryAcquireLease()
FSM.State<ClusterSingletonManager.State,ClusterSingletonManager.Data>	tryGotoOldest()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.apache.pekko.actor.Actor

aroundPostRestart, aroundPostStop, aroundPreRestart, aroundPreStart, aroundReceive, postRestart, preRestart, sender, supervisorStrategy, unhandled

Methods inherited from interface org.apache.pekko.actor.ActorLogging

_log_$eq

Methods inherited from interface org.apache.pekko.actor.FSM

applyState, cancelTimer, currentState_$eq, debugEvent, generation_$eq, handleEvent_$eq, handleTransition, initialize, isStateTimerActive, isTimerActive, logTermination, makeTransition, nextState_$eq, nextStateData, onTermination, onTransition, processEvent, processMsg, receive, register, setStateTimeout, startSingleTimer, startTimer, startTimerAtFixedRate, startTimerWithFixedDelay, startWith, startWith$default$3, stateData, stateName, stay, stop, stop, stop, super$postStop, terminate, terminateEvent_$eq, timeoutFuture_$eq, total2pf, transform, transitionEvent_$eq, when, when$default$2, whenUnhandled

Methods inherited from interface org.apache.pekko.routing.Listeners

gossip, gossip$default$2, listenerManagement

Constructor Details

ClusterSingletonManager

public ClusterSingletonManager(Props singletonProps,
 Object terminationMessage,
 ClusterSingletonManagerSettings settings)

Method Details

props

public static Props props(Props singletonProps,
 Object terminationMessage,
 ClusterSingletonManagerSettings settings)

Scala API: Factory method for ClusterSingletonManager pekko.actor.Props.

Event

public FSM.Event$ Event()

Specified by:

Event in interface FSM<ClusterSingletonManager.State,ClusterSingletonManager.Data>

StopEvent

public FSM.StopEvent$ StopEvent()

Specified by:

StopEvent in interface FSM<ClusterSingletonManager.State,ClusterSingletonManager.Data>

$minus$greater

public FSM.$minus$greater$ $minus$greater()

Description copied from interface: FSM

This extractor is just convenience for matching a (S, S) pair, including a reminder what the new state is.

Specified by:

$minus$greater in interface FSM<ClusterSingletonManager.State,ClusterSingletonManager.Data>

StateTimeout

public FSM.StateTimeout$ StateTimeout()

Description copied from interface: FSM

This case object is received in case of a state timeout.

Specified by:

StateTimeout in interface FSM<ClusterSingletonManager.State,ClusterSingletonManager.Data>

org$apache$pekko$actor$FSM$_setter_$Event_$eq

protected void org$apache$pekko$actor$FSM$_setter_$Event_$eq(FSM.Event$ x$1)

Specified by:

org$apache$pekko$actor$FSM$_setter_$Event_$eq in interface FSM<ClusterSingletonManager.State,ClusterSingletonManager.Data>

org$apache$pekko$actor$FSM$_setter_$StopEvent_$eq

protected void org$apache$pekko$actor$FSM$_setter_$StopEvent_$eq(FSM.StopEvent$ x$1)

Specified by:

org$apache$pekko$actor$FSM$_setter_$StopEvent_$eq in interface FSM<ClusterSingletonManager.State,ClusterSingletonManager.Data>

org$apache$pekko$actor$FSM$_setter_$StateTimeout_$eq

protected void org$apache$pekko$actor$FSM$_setter_$StateTimeout_$eq(FSM.StateTimeout$ x$1)

Description copied from interface: FSM

This case object is received in case of a state timeout.

Specified by:

org$apache$pekko$actor$FSM$_setter_$StateTimeout_$eq in interface FSM<ClusterSingletonManager.State,ClusterSingletonManager.Data>

listeners

protected Set<ActorRef> listeners()

Specified by:

listeners in interface Listeners

org$apache$pekko$routing$Listeners$_setter_$listeners_$eq

protected void org$apache$pekko$routing$Listeners$_setter_$listeners_$eq(Set<ActorRef> x$1)

Specified by:

org$apache$pekko$routing$Listeners$_setter_$listeners_$eq in interface Listeners

context

public ActorContext context()

Description copied from interface: Actor

Scala API: Stores the context for this actor, including self, and sender. It is implicit to support operations such as forward.

WARNING: Only valid within the Actor itself, so do not close over it and publish it to other threads!

pekko.actor.ActorContext is the Scala API. getContext returns a pekko.actor.AbstractActor.ActorContext, which is the Java API of the actor context.

Specified by:

context in interface Actor

self

public final ActorRef self()

Description copied from interface: Actor

The 'self' field holds the ActorRef for this actor.

Can be used to send messages to itself:

 self ! message
 

Specified by:

self in interface Actor

org$apache$pekko$actor$Actor$_setter_$context_$eq

protected void org$apache$pekko$actor$Actor$_setter_$context_$eq(ActorContext x$1)

Description copied from interface: Actor

Scala API: Stores the context for this actor, including self, and sender. It is implicit to support operations such as forward.

WARNING: Only valid within the Actor itself, so do not close over it and publish it to other threads!

pekko.actor.ActorContext is the Scala API. getContext returns a pekko.actor.AbstractActor.ActorContext, which is the Java API of the actor context.

Specified by:

org$apache$pekko$actor$Actor$_setter_$context_$eq in interface Actor

org$apache$pekko$actor$Actor$_setter_$self_$eq

protected final void org$apache$pekko$actor$Actor$_setter_$self_$eq(ActorRef x$1)

Description copied from interface: Actor

The 'self' field holds the ActorRef for this actor.

Can be used to send messages to itself:

 self ! message
 

Specified by:

org$apache$pekko$actor$Actor$_setter_$self_$eq in interface Actor

cluster

public Cluster cluster()

selfUniqueAddressOption

public scala.Some<UniqueAddress> selfUniqueAddressOption()

log

public MarkerLoggingAdapter log()

Specified by:

log in interface ActorLogging

lease

public scala.Option<Lease> lease()

leaseRetryInterval

public scala.concurrent.duration.FiniteDuration leaseRetryInterval()

removalMargin

public scala.concurrent.duration.FiniteDuration removalMargin()

maxHandOverRetries

public int maxHandOverRetries()

maxTakeOverRetries

public int maxTakeOverRetries()

oldestChangedBuffer

public ActorRef oldestChangedBuffer()

oldestChangedBuffer_$eq

public void oldestChangedBuffer_$eq(ActorRef x$1)

oldestChangedReceived

public boolean oldestChangedReceived()

oldestChangedReceived_$eq

public void oldestChangedReceived_$eq(boolean x$1)

preparingForFullShutdown

public boolean preparingForFullShutdown()

preparingForFullShutdown_$eq

public void preparingForFullShutdown_$eq(boolean x$1)

selfExited

public boolean selfExited()

selfExited_$eq

public void selfExited_$eq(boolean x$1)

removed

public scala.collection.immutable.Map<UniqueAddress,scala.concurrent.duration.Deadline> removed()

removed_$eq

public void removed_$eq(scala.collection.immutable.Map<UniqueAddress,scala.concurrent.duration.Deadline> x$1)

addRemoved

public void addRemoved(UniqueAddress node)

cleanupOverdueNotMemberAnyMore

public void cleanupOverdueNotMemberAnyMore()

coordShutdown

public CoordinatedShutdown coordShutdown()

memberExitingProgress

public scala.concurrent.Promise<Done> memberExitingProgress()

logInfo

public void logInfo(String message)

logInfo

public void logInfo(LogMarker marker,
 String message)

logInfo

public void logInfo(String template,
 Object arg1)

logInfo

public void logInfo(LogMarker marker,
 String template,
 Object arg1)

logInfo

public void logInfo(String template,
 Object arg1,
 Object arg2)

logInfo

public void logInfo(LogMarker marker,
 String template,
 Object arg1,
 Object arg2)

logInfo

public void logInfo(String template,
 Object arg1,
 Object arg2,
 Object arg3)

preStart

public void preStart()

Description copied from interface: Actor

User overridable callback.

Is called when an Actor is started. Actors are automatically started asynchronously when created. Empty default implementation.

Specified by:

preStart in interface Actor

postStop

public void postStop()

Description copied from interface: Actor

User overridable callback.

Is called asynchronously after 'actor.stop()' is invoked. Empty default implementation.

Specified by:

postStop in interface Actor

Specified by:

postStop in interface FSM<ClusterSingletonManager.State,ClusterSingletonManager.Data>

peer

public ActorSelection peer(Address at)

getNextOldestChanged

public void getNextOldestChanged()

handleMemberEvent

public FSM.State<ClusterSingletonManager.State,ClusterSingletonManager.Data> handleMemberEvent(ClusterEvent.MemberEvent event)

scheduleDelayedMemberRemoved

public void scheduleDelayedMemberRemoved(Member m)

tryAcquireLease

public FSM.State<ClusterSingletonManager.State,ClusterSingletonManager.Data> tryAcquireLease()

tryGotoOldest

public FSM.State<ClusterSingletonManager.State,ClusterSingletonManager.Data> tryGotoOldest()

gotoOldest

public FSM.State<ClusterSingletonManager.State,ClusterSingletonManager.Data> gotoOldest()

handleOldestChanged

public FSM.State<ClusterSingletonManager.State,ClusterSingletonManager.Data> handleOldestChanged(scala.Option<ActorRef> singleton,
 scala.Option<UniqueAddress> oldestOption)

gotoHandingOver

public FSM.State<ClusterSingletonManager.State,ClusterSingletonManager.Data> gotoHandingOver(scala.Option<ActorRef> singleton,
 scala.Option<ActorRef> handOverTo)

handOverDone

public FSM.State<ClusterSingletonManager.State,ClusterSingletonManager.Data> handOverDone(scala.Option<ActorRef> handOverTo)

gotoStopping

public FSM.State<ClusterSingletonManager.State,ClusterSingletonManager.Data> gotoStopping(ActorRef singleton)

selfMemberExited

public void selfMemberExited()