io.atomix.core.election

Interface AsyncLeaderElector<T>

All Superinterfaces:

AsyncPrimitive, DistributedPrimitive

public interface AsyncLeaderElector<T>
extends AsyncPrimitive

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.

Field Summary

Fields inherited from interface io.atomix.primitive.DistributedPrimitive

DEFAULT_OPERATION_TIMEOUT_MILLIS

Method Summary

Modifier and Type	Method and Description
CompletableFuture<Void>	addListener(LeadershipEventListener<T> listener) Registers a listener to be notified of Leadership changes for all topics.
CompletableFuture<Void>	addListener(String topic, LeadershipEventListener<T> listener) Registers a listener to be notified of Leadership changes for all topics.
CompletableFuture<Boolean>	anoint(String topic, T identifier) Attempts to promote a node to leadership displacing the current leader.
CompletableFuture<Void>	evict(T identifier) Attempts to evict a node from all leadership elections it is registered for.
CompletableFuture<Leadership<T>>	getLeadership(String topic) Returns the Leadership for the specified topic.
CompletableFuture<Map<String,Leadership<T>>>	getLeaderships() Returns the current Leaderships for all topics.
CompletableFuture<Boolean>	promote(String topic, T identifier) Attempts to promote a node to top of candidate list without displacing the current leader.
CompletableFuture<Void>	removeListener(LeadershipEventListener<T> listener) Unregisters a previously registered change notification listener.
CompletableFuture<Void>	removeListener(String topic, LeadershipEventListener<T> listener) Unregisters a previously registered change notification listener.
CompletableFuture<Leadership<T>>	run(String topic, T identifier) Attempts to become leader for a topic.
default LeaderElector<T>	sync() Returns a synchronous wrapper around the asynchronous primitive.
LeaderElector<T>	sync(Duration operationTimeout) Returns a synchronous wrapper around the asynchronous primitive.
CompletableFuture<Void>	withdraw(String topic, T identifier) Withdraws from leadership race for a topic.

Methods inherited from interface io.atomix.primitive.AsyncPrimitive

close, delete

Methods inherited from interface io.atomix.primitive.DistributedPrimitive

addStateChangeListener, name, protocol, removeStateChangeListener, type

Method Detail

run

CompletableFuture<Leadership<T>> run(String topic,
                                     T identifier)

Attempts to become leader for a topic.

Parameters:

topic - leadership topic

identifier - instance identifier of the candidate

Returns:

CompletableFuture that is completed with the current Leadership state of the topic

withdraw

CompletableFuture<Void> withdraw(String topic,
                                 T identifier)

Withdraws from leadership race for a topic.

Parameters:

topic - leadership topic

identifier - instance identifier of the candidate to withdraw

Returns:

CompletableFuture that is completed when the withdraw is done

anoint

CompletableFuture<Boolean> anoint(String topic,
                                  T identifier)

Attempts to promote a node to leadership displacing the current leader.

Parameters:

topic - leadership topic

identifier - instance identifier of the candidate to anoint

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(T identifier)

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:

identifier - instance identifier

Returns:

CompletableFuture that is completed when the operation is done.

promote

CompletableFuture<Boolean> promote(String topic,
                                   T identifier)

Attempts to promote a node to top of candidate list without displacing the current leader.

Parameters:

topic - leadership topic

identifier - instance identifier

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<T>> getLeadership(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

CompletableFuture<Map<String,Leadership<T>>> getLeaderships()

Returns the current Leaderships for all topics.

Returns:

CompletableFuture that is completed with the topic to Leadership mapping

addListener

CompletableFuture<Void> addListener(LeadershipEventListener<T> listener)

Registers a listener to be notified of Leadership changes for all topics.

Parameters:

listener - listener to notify

Returns:

CompletableFuture that is completed when the operation completes

removeListener

CompletableFuture<Void> removeListener(LeadershipEventListener<T> listener)

Unregisters a previously registered change notification listener.

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

Parameters:

listener - listener to remove

Returns:

CompletableFuture that is completed when the operation completes

addListener

CompletableFuture<Void> addListener(String topic,
                                    LeadershipEventListener<T> listener)

Registers a listener to be notified of Leadership changes for all topics.

Parameters:

topic - leadership topic

listener - listener to notify

Returns:

CompletableFuture that is completed when the operation completes

removeListener

CompletableFuture<Void> removeListener(String topic,
                                       LeadershipEventListener<T> listener)

Unregisters a previously registered change notification listener.

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

Parameters:

topic - leadership topic

listener - listener to remove

Returns:

CompletableFuture that is completed when the operation completes

sync

default LeaderElector<T> sync()

Description copied from interface: AsyncPrimitive

Returns a synchronous wrapper around the asynchronous primitive.

Specified by:

sync in interface AsyncPrimitive

Returns:

the synchronous primitive

sync

LeaderElector<T> sync(Duration operationTimeout)

Description copied from interface: AsyncPrimitive

Returns a synchronous wrapper around the asynchronous primitive.

Specified by:

sync in interface AsyncPrimitive

Parameters:

operationTimeout - the synchronous operation timeout

Returns:

the synchronous primitive