Package org.onosproject.store.service

Interface AsyncLeaderElector

  • All Superinterfaces:
    DistributedPrimitive
    public interface AsyncLeaderElector
extends DistributedPrimitive
    Distributed mutual exclusion primitive.

    AsyncLeaderElector facilitates mutually exclusive access to a shared resource by various cluster members. Each resource is identified by a unique topic name and members register their desire to access the resource by calling the run method. Access is grated on a FIFO basis. An instance can unregister itself from the leadership election by calling withdraw method. If an instance currently holding the resource dies then the next instance waiting to be leader (in FIFO order) will be automatically granted access to the resource.

    One can register listeners to be notified when a leadership change occurs. The Listeners are notified via a Leadership change subject.

    Additionally, AsyncLeaderElector provides methods to query the current state of leadership for topics.

    All methods of this interface return a future immediately after a successful invocation. The operation itself is executed asynchronous and the returned future will be completed when the operation finishes.

    • Method Detail

      • run

        java.util.concurrent.CompletableFuture<Leadership> run​(java.lang.String topic,
                                                       NodeId nodeId)
        Attempts to become leader for a topic.
        Parameters:
        topic - leadership topic
        nodeId - instance identifier of the node
        Returns:
        CompletableFuture that is completed with the current Leadership state of the topic

      • withdraw

        java.util.concurrent.CompletableFuture<java.lang.Void> withdraw​(java.lang.String topic)
        Withdraws from leadership race for a topic.
        Parameters:
        topic - leadership topic
        Returns:
        CompletableFuture that is completed when the withdraw is done

      • anoint

        java.util.concurrent.CompletableFuture<java.lang.Boolean> anoint​(java.lang.String topic,
                                                                 NodeId nodeId)
        Attempts to promote a node to leadership displacing the current leader.
        Parameters:
        topic - leadership topic
        nodeId - instance identifier of the new leader
        Returns:
        CompletableFuture that is completed with a boolean when the operation is done. Boolean is true if leadership transfer was successfully executed; false if it failed. This operation can fail (i.e. return false) if the node to be made new leader is not registering to run for election for the topic.

      • evict

        java.util.concurrent.CompletableFuture<java.lang.Void> evict​(NodeId nodeId)
        Attempts to evict a node from all leadership elections it is registered for.

        If the node is the current leader for a topic, this call will promote the next top candidate (if one exists) to leadership.

        Parameters:
        nodeId - node instance identifier
        Returns:
        CompletableFuture that is completed when the operation is done.

      • promote

        java.util.concurrent.CompletableFuture<java.lang.Boolean> promote​(java.lang.String topic,
                                                                  NodeId nodeId)
        Attempts to promote a node to top of candidate list without displacing the current leader.
        Parameters:
        topic - leadership topic
        nodeId - instance identifier of the new top candidate
        Returns:
        CompletableFuture that is completed with a boolean when the operation is done. Boolean is true if node is now the top candidate. This operation can fail (i.e. return false) if the node is not registered to run for election for the topic.

      • getLeadership

        java.util.concurrent.CompletableFuture<Leadership> getLeadership​(java.lang.String topic)
        Returns the Leadership for the specified topic.
        Parameters:
        topic - leadership topic
        Returns:
        CompletableFuture that is completed with the current Leadership state of the topic

      • getLeaderships

        java.util.concurrent.CompletableFuture<java.util.Map<java.lang.String,​Leadership>> getLeaderships()
        Returns the current Leaderships for all topics.
        Returns:
        CompletableFuture that is completed with the topic to Leadership mapping

      • addChangeListener

        java.util.concurrent.CompletableFuture<java.lang.Void> addChangeListener​(java.util.function.Consumer<Change<Leadership>> consumer)
        Registers a listener to be notified of Leadership changes for all topics.
        Parameters:
        consumer - listener to notify
        Returns:
        CompletableFuture that is completed when the operation completes

      • removeChangeListener

        java.util.concurrent.CompletableFuture<java.lang.Void> removeChangeListener​(java.util.function.Consumer<Change<Leadership>> consumer)
        Unregisters a previously registered change notification listener.

        If the specified listener was not previously registered, this operation will be a noop.

        Parameters:
        consumer - listener to remove
        Returns:
        CompletableFuture that is completed when the operation completes

      • asLeaderElector

        default LeaderElector asLeaderElector​(long timeoutMillis)
        Returns a new LeaderElector that is backed by this instance.
        Parameters:
        timeoutMillis - timeout duration for the returned LeaderElector operations
        Returns:
        new LeaderElector instance

      • asLeaderElector

        default LeaderElector asLeaderElector()
        Returns a new LeaderElector that is backed by this instance and with a default operation timeout.
        Returns:
        new LeaderElector instance