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 therun
method. Access is grated on a FIFO basis. An instance can unregister itself from the leadership election by callingwithdraw
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 becompleted
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
-
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description CompletableFuture<Void>
addChangeListener(Consumer<Change<Leadership>> consumer)
Registers a listener to be notified of Leadership changes for all topics.CompletableFuture<Boolean>
anoint(String topic, NodeId nodeId)
Attempts to promote a node to leadership displacing the current leader.default LeaderElector
asLeaderElector()
Returns a newLeaderElector
that is backed by this instance and with a default operation timeout.default LeaderElector
asLeaderElector(long timeoutMillis)
Returns a newLeaderElector
that is backed by this instance.CompletableFuture<Void>
evict(NodeId nodeId)
Attempts to evict a node from all leadership elections it is registered for.CompletableFuture<Leadership>
getLeadership(String topic)
Returns theLeadership
for the specified topic.CompletableFuture<Map<String,Leadership>>
getLeaderships()
Returns the currentLeadership
s for all topics.default DistributedPrimitive.Type
primitiveType()
Returns the type of primitive.CompletableFuture<Boolean>
promote(String topic, NodeId nodeId)
Attempts to promote a node to top of candidate list without displacing the current leader.CompletableFuture<Void>
removeChangeListener(Consumer<Change<Leadership>> consumer)
Unregisters a previously registered change notification listener.CompletableFuture<Leadership>
run(String topic, NodeId nodeId)
Attempts to become leader for a topic.CompletableFuture<Void>
withdraw(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 interfaceDistributedPrimitive
- Returns:
- primitive type
-
run
CompletableFuture<Leadership> run(String topic, NodeId nodeId)
Attempts to become leader for a topic.- Parameters:
topic
- leadership topicnodeId
- instance identifier of the node- Returns:
- CompletableFuture that is completed with the current Leadership state of the topic
-
withdraw
CompletableFuture<Void> withdraw(String topic)
Withdraws from leadership race for a topic.- Parameters:
topic
- leadership topic- Returns:
- CompletableFuture that is completed when the withdraw is done
-
anoint
CompletableFuture<Boolean> anoint(String topic, NodeId nodeId)
Attempts to promote a node to leadership displacing the current leader.- Parameters:
topic
- leadership topicnodeId
- 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
CompletableFuture<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
CompletableFuture<Boolean> promote(String topic, NodeId nodeId)
Attempts to promote a node to top of candidate list without displacing the current leader.- Parameters:
topic
- leadership topicnodeId
- 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
CompletableFuture<Leadership> getLeadership(String topic)
Returns theLeadership
for the specified topic.- Parameters:
topic
- leadership topic- Returns:
- CompletableFuture that is completed with the current Leadership state of the topic
-
getLeaderships
CompletableFuture<Map<String,Leadership>> getLeaderships()
Returns the currentLeadership
s for all topics.- Returns:
- CompletableFuture that is completed with the topic to Leadership mapping
-
addChangeListener
CompletableFuture<Void> addChangeListener(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
CompletableFuture<Void> removeChangeListener(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 newLeaderElector
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 newLeaderElector
that is backed by this instance and with a default operation timeout.- Returns:
- new
LeaderElector
instance
-
-