Search Results for

    Show / Hide Table of Contents

    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

    | Edit this page View Source

    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

    | Edit this page View Source

    DowningProvider

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

    Declaration
    public IDowningProvider DowningProvider { get; }
    Property Value
    Type Description
    IDowningProvider
    | Edit this page View Source

    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>
    | Edit this page View Source

    IsTerminated

    Determine whether or not this cluster instance has been shutdown.

    Declaration
    public bool IsTerminated { get; }
    Property Value
    Type Description
    bool
    | Edit this page View Source

    IsUp

    Determine whether the cluster is in the UP state.

    Declaration
    public bool IsUp { get; }
    Property Value
    Type Description
    bool
    | Edit this page View Source

    SelfAddress

    The address of this cluster member.

    Declaration
    public Address SelfAddress { get; }
    Property Value
    Type Description
    Address
    | Edit this page View Source

    SelfMember

    Access to the current member info for this node.

    Declaration
    public Member SelfMember { get; }
    Property Value
    Type Description
    Member
    | Edit this page View Source

    SelfRoles

    The roles that this cluster member is currently a part.

    Declaration
    public ImmutableHashSet<string> SelfRoles { get; }
    Property Value
    Type Description
    ImmutableHashSet<string>
    | Edit this page View Source

    SelfUniqueAddress

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

    Declaration
    public UniqueAddress SelfUniqueAddress { get; }
    Property Value
    Type Description
    UniqueAddress
    | Edit this page View Source

    Settings

    The settings for the cluster.

    Declaration
    public ClusterSettings Settings { get; }
    Property Value
    Type Description
    ClusterSettings
    | Edit this page View Source

    State

    The current snapshot state of the cluster.

    Declaration
    public ClusterEvent.CurrentClusterState State { get; }
    Property Value
    Type Description
    ClusterEvent.CurrentClusterState
    | Edit this page View Source

    System

    The underlying ActorSystem supported by this plugin.

    Declaration
    public ExtendedActorSystem System { get; }
    Property Value
    Type Description
    ExtendedActorSystem

    Methods

    | Edit this page View Source

    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

    | Edit this page View Source

    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.

    | Edit this page View Source

    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.

    | Edit this page View Source

    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)
    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.

    | Edit this page View Source

    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

    | Edit this page View Source

    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)
    Parameters
    Type Name Description
    IEnumerable<Address> seedNodes

    TBD

    CancellationToken token

    TBD

    Returns
    Type Description
    Task
    | Edit this page View Source

    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.

    | Edit this page View Source

    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.

    | Edit this page View Source

    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).

    | Edit this page View Source

    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

    | Edit this page View Source

    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

    | Edit this page View Source

    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.

    | Edit this page View Source

    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.

    | Edit this page View Source

    Subscribe(IActorRef, SubscriptionInitialStateMode, params 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.

    | Edit this page View Source

    Subscribe(IActorRef, params 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

    | Edit this page View Source

    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.

    | Edit this page View Source

    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)
    In this article
    • githubEdit this page
    • View Source
    Back to top
    Contribute
    • Project Chat
    • Discussion Forum
    • Source Code
    Support
    • Akka.NET Support Plans
    • Akka.NET Observability Tools
    • Akka.NET Training & Consulting
    Maintained By
    • Petabridge - The Akka.NET Company
    • Learn Akka.NET