Apache Pekko
1.2.1
API
Generated with
Apache Pekko/org.apache.pekko.cluster/org.apache.pekko.cluster.singleton

org.apache.pekko.cluster.singleton

package org.apache.pekko.cluster.singleton

Members list

Type members

Classlikes

object ClusterSingletonManager

Attributes

Companion
class
Source
ClusterSingletonManager.scala
Supertypes
class Object
trait Matchable
class Any
Self type
class ClusterSingletonManager(singletonProps: Props, terminationMessage: Any, settings: ClusterSingletonManagerSettings) extends Actor, FSM[State, 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.

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 ClusterSingletonManager#props to create the pekko.actor.Props for the actor.

Not intended for subclassing by user code.

Value parameters

settings

see ClusterSingletonManagerSettings

singletonProps

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

Attributes

Companion
object
Source
ClusterSingletonManager.scala
Supertypes
trait FSM[State, Data]
trait ActorLogging
trait Listeners
trait Actor
class Object
trait Matchable
class Any
Show all
class ClusterSingletonManagerIsStuck(message: String) extends PekkoException

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.

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.

Attributes

Source
ClusterSingletonManager.scala
Supertypes
class RuntimeException
class Exception
class Throwable
trait Serializable
class Object
trait Matchable
class Any
Show all
object ClusterSingletonManagerSettings

Attributes

Companion
class
Source
ClusterSingletonManager.scala
Supertypes
class Object
trait Matchable
class Any
Self type
final class ClusterSingletonManagerSettings(val singletonName: String, val role: Option[String], val removalMargin: FiniteDuration, val handOverRetryInterval: FiniteDuration, val leaseSettings: Option[LeaseUsageSettings]) extends NoSerializationVerificationNeeded

Value parameters

handOverRetryInterval

When a node is becoming oldest it sends hand-over request to previous oldest, that might be leaving the cluster. This is retried with this interval until the previous oldest confirms that the hand over has started or the previous oldest member is removed from the cluster (+ removalMargin).

leaseSettings

LeaseSettings for acquiring before creating the singleton actor

removalMargin

Margin until the singleton instance that belonged to a downed/removed partition is created in surviving partition. The purpose of this margin is that in case of a network partition the singleton actors in the non-surviving partitions must be stopped before corresponding actors are started somewhere else. This is especially important for persistent actors.

role

Singleton among the nodes tagged with specified role. If the role is not specified it's a singleton among all nodes in the cluster.

singletonName

The actor name of the child singleton actor.

Attributes

Companion
object
Source
ClusterSingletonManager.scala
Supertypes
class Object
trait Matchable
class Any
sealed trait ClusterSingletonMessage extends Serializable

Marker trait for remote messages with special serializer.

Marker trait for remote messages with special serializer.

Attributes

Source
ClusterSingletonManager.scala
Supertypes
trait Serializable
class Object
trait Matchable
class Any
object ClusterSingletonProxy

Attributes

Companion
class
Source
ClusterSingletonProxy.scala
Supertypes
class Object
trait Matchable
class Any
Self type
final class ClusterSingletonProxy(singletonManagerPath: String, settings: ClusterSingletonProxySettings) extends Actor, ActorLogging

The ClusterSingletonProxy works together with the pekko.cluster.singleton.ClusterSingletonManager to provide a distributed proxy to the singleton actor.

The ClusterSingletonProxy works together with the pekko.cluster.singleton.ClusterSingletonManager to provide a distributed proxy to the singleton actor.

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 pekko.actor.Identify message until the singleton responds with its pekko.actor.ActorIdentity.

Note that this is a best effort implementation: messages can always be lost due to the distributed nature of the actors involved.

Attributes

Companion
object
Source
ClusterSingletonProxy.scala
Supertypes
trait ActorLogging
trait Actor
class Object
trait Matchable
class Any
object ClusterSingletonProxySettings

Attributes

Companion
class
Source
ClusterSingletonProxy.scala
Supertypes
class Object
trait Matchable
class Any
Self type
final class ClusterSingletonProxySettings(val singletonName: String, val role: Option[String], val dataCenter: Option[DataCenter], val singletonIdentificationInterval: FiniteDuration, val bufferSize: Int) extends NoSerializationVerificationNeeded

Value parameters

bufferSize

If the location of the singleton is unknown the proxy will buffer this number of messages and deliver them when the singleton is identified. When the buffer is full old messages will be dropped when new messages are sent viea the proxy. Use 0 to disable buffering, i.e. messages will be dropped immediately if the location of the singleton is unknown.

dataCenter

The data center of the cluster nodes where the singleton is running. If None then the same data center as current node.

role

The role of the cluster nodes where the singleton can be deployed. Corresponding to the role used by the ClusterSingletonManager. If the role is not specified it's a singleton among all nodes in the cluster, and the ClusterSingletonManager must then also be configured in same way.

singletonIdentificationInterval

Interval at which the proxy will try to resolve the singleton instance.

singletonName

The actor name of the singleton actor that is started by the ClusterSingletonManager.

Attributes

Companion
object
Source
ClusterSingletonProxy.scala
Supertypes
class Object
trait Matchable
class Any
Generated with