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.

Nested Class Summary

Nested classes/interfaces inherited from interface org.onosproject.store.service.DistributedPrimitive

DistributedPrimitive.Status, DistributedPrimitive.Type

Field Summary

Fields inherited from interface org.onosproject.store.service.DistributedPrimitive

DEFAULT_OPERATION_TIMEOUT_MILLIS, DEFAULT_OPERTATION_TIMEOUT_MILLIS

Method Summary

Modifier and Type	Method and Description
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.
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.
default LeaderElector	asLeaderElector() Returns a new LeaderElector that is backed by this instance and with a default operation timeout.
default LeaderElector	asLeaderElector(long timeoutMillis) Returns a new LeaderElector that is backed by this instance.
java.util.concurrent.CompletableFuture<java.lang.Void>	evict(NodeId nodeId) Attempts to evict a node from all leadership elections it is registered for.
java.util.concurrent.CompletableFuture<Leadership>	getLeadership(java.lang.String topic) Returns the Leadership for the specified topic.
java.util.concurrent.CompletableFuture<java.util.Map<java.lang.String,Leadership>>	getLeaderships() Returns the current Leaderships for all topics.
default DistributedPrimitive.Type	primitiveType() Returns the type of primitive.
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.
java.util.concurrent.CompletableFuture<java.lang.Void>	removeChangeListener(java.util.function.Consumer<Change<Leadership>> consumer) Unregisters a previously registered change notification listener.
java.util.concurrent.CompletableFuture<Leadership>	run(java.lang.String topic, NodeId nodeId) Attempts to become leader for a topic.
java.util.concurrent.CompletableFuture<java.lang.Void>	withdraw(java.lang.String topic) Withdraws from leadership race for a topic.

Methods inherited from interface org.onosproject.store.service.DistributedPrimitive

addStatusChangeListener, applicationId, destroy, name, removeStatusChangeListener, statusChangeListeners

Method Detail

primitiveType

default DistributedPrimitive.Type primitiveType()

Description copied from interface: DistributedPrimitive

Returns the type of primitive.

Specified by:

primitiveType in interface DistributedPrimitive

Returns:

primitive type

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