Class Cluster

This class represents an ActorSystem extension used to create, monitor and manage a cluster of member nodes hosted within the actor system.

Each cluster Member is identified by its Address and the cluster address of this actor system is SelfAddress. A member also has a status; initially Joining followed by Up.

Inheritance

Object

Cluster

Implements

IExtension

Inherited Members

Object.Equals(Object)

Object.Equals(Object, Object)

Object.GetHashCode()

Object.GetType()

Object.MemberwiseClone()

Object.ReferenceEquals(Object, Object)

Object.ToString()

Namespace: Akka.Cluster

Assembly: Akka.Cluster.dll

Syntax

public class Cluster : IExtension

Constructors

Cluster(ActorSystemImpl)

Initializes a new instance of the Cluster class.

Declaration

public Cluster(ActorSystemImpl system)

Parameters

Type	Name	Description
ActorSystemImpl	system	The actor system that hosts the cluster.

Exceptions

Type	Condition
ConfigurationException	This exception is thrown if the system does not have a Akka.Cluster.ClusterActorRefProvider enabled in the configuration.

Properties

DowningProvider

The downing provider used to execute automatic downing inside Akka.Cluster.

Declaration

public IDowningProvider DowningProvider { get; }

Property Value

Type	Description
IDowningProvider

FailureDetector

The set of failure detectors used for monitoring one or more nodes in the cluster.

Declaration

public DefaultFailureDetectorRegistry<Address> FailureDetector { get; }

Property Value

Type	Description
DefaultFailureDetectorRegistry<Address>

IsTerminated

Determine whether or not this cluster instance has been shutdown.

Declaration

public bool IsTerminated { get; }

Property Value

Type	Description
Boolean

IsUp

Determine whether the cluster is in the UP state.

Declaration

public bool IsUp { get; }

Property Value

Type	Description
Boolean

SelfAddress

The address of this cluster member.

Declaration

public Address SelfAddress { get; }

Property Value

Type	Description
Address

SelfMember

Access to the current member info for this node.

Declaration

public Member SelfMember { get; }

Property Value

Type	Description
Member

SelfRoles

The roles that this cluster member is currently a part.

Declaration

public ImmutableHashSet<string> SelfRoles { get; }

Property Value

Type	Description
System.Collections.Immutable.ImmutableHashSet<String>

SelfUniqueAddress

The current unique address for the cluster, which includes the UID.

Declaration

public UniqueAddress SelfUniqueAddress { get; }

Property Value

Type	Description
UniqueAddress

Settings

The settings for the cluster.

Declaration

public ClusterSettings Settings { get; }

Property Value

Type	Description
ClusterSettings

State

The current snapshot state of the cluster.

Declaration

public ClusterEvent.CurrentClusterState State { get; }

Property Value

Type	Description
ClusterEvent.CurrentClusterState

System

The underlying ActorSystem supported by this plugin.

Declaration

public ExtendedActorSystem System { get; }

Property Value

Type	Description
ExtendedActorSystem

Methods

Down(Address)

Sends a command to DOWN the node specified by address.

When a member is considered by the failure detector to be unreachable the leader is not allowed to perform its duties, such as changing status of new joining members to Up. The status of the unreachable member must be changed to Down, which can be done with this method.

Declaration

public void Down(Address address)

Parameters

Type	Name	Description
Address	address	The address of the node we're going to mark as Down

Get(ActorSystem)

Retrieves the extension from the specified actor system.

Declaration

public static Cluster Get(ActorSystem system)

Parameters

Type	Name	Description
ActorSystem	system	The actor system from which to retrieve the extension.

Returns

Type	Description
Cluster	The extension retrieved from the given actor system.

Join(Address)

Try to join this cluster node specified by address. A Join(Address) command is sent to the node to join.

An actor system can only join a cluster once. Additional attempts will be ignored. When it has successfully joined it must be restarted to be able to join another cluster or to join the same cluster again.

Declaration

public void Join(Address address)

Parameters

Type	Name	Description
Address	address	The address of the node we want to join.

JoinAsync(Address, CancellationToken)

Try to asynchronously join this cluster node specified by address. A Join(Address) command is sent to the node to join. Returned task will be completed once current cluster node will be moved into Up state, or cancelled when provided token cancellation triggers. Cancelling this token doesn't prevent current node from joining the cluster, therefore a manuall call to Leave(Address)/LeaveAsync() may still be required in order to leave the cluster gracefully.

An actor system can only join a cluster once. Additional attempts will be ignored. When it has successfully joined it must be restarted to be able to join another cluster or to join the same cluster again.

Once cluster has been shutdown, JoinAsync(Address, CancellationToken) will always fail until an entire actor system is manually restarted.

Declaration

public Task JoinAsync(Address address, CancellationToken token = default(CancellationToken))

Parameters

Type	Name	Description
Address	address	The address of the node we want to join.
CancellationToken	token	An optional cancellation token used to cancel returned task before it completes.

Returns

Type	Description
Task	Task which completes, once current cluster node reaches Up state.

JoinSeedNodes(IEnumerable<Address>)

Joins the specified seed nodes without defining them in config. Especially useful from tests when Addresses are unknown before startup time.

An actor system can only join a cluster once. Additional attempts will be ignored. When it has successfully joined it must be restarted to be able to join another cluster or to join the same cluster again.

Declaration

public void JoinSeedNodes(IEnumerable<Address> seedNodes)

Parameters

Type	Name	Description
IEnumerable<Address>	seedNodes	TBD

JoinSeedNodesAsync(IEnumerable<Address>, CancellationToken)

Joins the specified seed nodes without defining them in config. Especially useful from tests when Addresses are unknown before startup time. Returns a task, which completes once current cluster node has successfully joined the cluster or which cancels, when a cancellation token has been cancelled. Cancelling this token doesn't prevent current node from joining the cluster, therefore a manuall call to Leave(Address)/LeaveAsync() may still be required in order to leave the cluster gracefully.

An actor system can only join a cluster once. Additional attempts will be ignored. When it has successfully joined it must be restarted to be able to join another cluster or to join the same cluster again.

Once cluster has been shutdown, JoinSeedNodesAsync(IEnumerable<Address>, CancellationToken) will always fail until an entire actor system is manually restarted.

Declaration

public Task JoinSeedNodesAsync(IEnumerable<Address> seedNodes, CancellationToken token = default(CancellationToken))

Parameters

Type	Name	Description
IEnumerable<Address>	seedNodes	TBD
CancellationToken	token	TBD

Returns

Type	Description
Task

Leave(Address)

Sends a command to issue state transition to LEAVING for the node specified by address. The member will go through the status changes Leaving (not published to subscribers) followed by Exiting and finally Removed.

Note that this command can be issued to any member in the cluster, not necessarily the one that is leaving. The cluster extension, but not the actor system, of the leaving member will be shutdown after the leader has changed status of the member to Exiting. Thereafter the member will be removed from the cluster. Normally this is handled automatically, but in case of network failures during this process it might still be necessary to set the node's status to Down in order to complete the removal.

Declaration

public void Leave(Address address)

Parameters

Type	Name	Description
Address	address	The address of the node leaving the cluster.

LeaveAsync()

Causes the CURRENT node, i.e. the one calling this function, to leave the cluster.

Once the returned Task completes, it means that the member has successfully been removed from the cluster.

Declaration

public Task LeaveAsync()

Returns

Type	Description
Task	A Task that will return upon the current node being removed from the cluster.

LeaveAsync(CancellationToken)

Causes the CURRENT node, i.e. the one calling this function, to leave the cluster.

Once the returned Task completes in completed or cancelled state, it means that the member has successfully been removed from the cluster or cancellation token cancelled the task.

Declaration

public Task LeaveAsync(CancellationToken cancellationToken)

Parameters

Type	Name	Description
CancellationToken	cancellationToken	The cancellation token to cancel awaiting.

Returns

Type	Description
Task	A Task that will return upon the current node being removed from the cluster, or if await was cancelled.

Remarks

The cancellation token doesn't cancel leave from the cluster, it only lets to give up on awaiting (by timeout for example).

RegisterOnMemberRemoved(Action)

Registers the supplied callback to run once when the current cluster member is Removed.

Typically used in combination with Leave(Address) and Terminate().

Declaration

public void RegisterOnMemberRemoved(Action callback)

Parameters

Type	Name	Description
Action	callback	The callback that is run whenever the current member achieves a status of Down

RegisterOnMemberUp(Action)

Registers the supplied callback to run once when the current cluster member is Up. Typically used together with configuration option 'akka.cluster.min-nr-of-members' to defer some action, such as starting actors, until the cluster has reached a certain size.

Declaration

public void RegisterOnMemberUp(Action callback)

Parameters

Type	Name	Description
Action	callback	The callback that is run whenever the current member achieves a status of Up

RemotePathOf(IActorRef)

Generates the remote actor path by replacing the Address in the RootActorPath for the given ActorRef with the cluster's SelfAddress, unless address' host is already defined

Declaration

public ActorPath RemotePathOf(IActorRef actorRef)

Parameters

Type	Name	Description
IActorRef	actorRef	An IActorRef belonging to the current node.

Returns

Type	Description
ActorPath	The absolute remote ActorPath of actorRef.

SendCurrentClusterState(IActorRef)

Sends the current (full) state of the cluster to the specified actor. If you want this to happen periodically, you can use the Akka.Cluster.Cluster.Scheduler to schedule a call to this method. You can also call State directly for this information.

Declaration

public void SendCurrentClusterState(IActorRef receiver)

Parameters

Type	Name	Description
IActorRef	receiver	The actor that receives the current cluster state.

Subscribe(IActorRef, ClusterEvent.SubscriptionInitialStateMode, Type[])

Subscribe to one or more cluster domain events.

Declaration

public void Subscribe(IActorRef subscriber, ClusterEvent.SubscriptionInitialStateMode initialStateMode, params Type[] to)

Parameters

Type	Name	Description
IActorRef	subscriber	The actor who'll receive the cluster domain events
ClusterEvent.SubscriptionInitialStateMode	initialStateMode	If set to InitialStateAsEvents, then the events corresponding to the current state are sent to subscriber to mimic what it would have seen if it were listening to the events when they occurred in the past. If set to InitialStateAsSnapshot, then a snapshot of ClusterEvent.CurrentClusterState will be sent to subscriber as the first message.
Type[]	to	An array of event types that the actor receives.

Exceptions

Type	Condition
ArgumentException	This exception is thrown when the array of supplied types, to, is empty or contains types that do not implement ClusterEvent.IClusterDomainEvent.

Subscribe(IActorRef, Type[])

Subscribe to one or more cluster domain events.

Declaration

public void Subscribe(IActorRef subscriber, params Type[] to)

Parameters

Type	Name	Description
IActorRef	subscriber	The actor who'll receive the cluster domain events
Type[]	to	ClusterEvent.IClusterDomainEvent subclasses

Remarks

A snapshot of ClusterEvent.CurrentClusterState will be sent to subscriber as the first message

Unsubscribe(IActorRef)

Stops the specific actor from receiving all types of cluster domain events.

Declaration

public void Unsubscribe(IActorRef subscriber)

Parameters

Type	Name	Description
IActorRef	subscriber	The actor that no longer receives cluster domain events.

Unsubscribe(IActorRef, Type)

Stops the specific actor from receiving a specific type of cluster domain event.

Declaration

public void Unsubscribe(IActorRef subscriber, Type to)

Parameters

Type	Name	Description
IActorRef	subscriber	The actor that no longer receives cluster domain events.
Type	to	The event type that the actor no longer receives.

Implements

IExtension

Extension Methods

ObjectExtensions.IsDefaultForType<T>(T)

ObjectExtensions.AsOption<T>(T)

Extensions.AsInstanceOf<T>(Object)