io.atomix.coordination

Class DistributedLeaderElection

java.lang.Object

io.atomix.resource.AbstractResource

io.atomix.coordination.DistributedLeaderElection

All Implemented Interfaces:

Resource

public class DistributedLeaderElection
extends AbstractResource

Provides a mechanism for coordinating cluster-wide resources with a strong leader.

Leader election allows a set of distributed processes to coordinate access to and control over resources by electing a single process to do work. This leader election implementation uses a consensus-based state machine to automatically rotate leaders as necessary.

To create a leader election, use the DistributedLeaderElection resource class when constructing a resource instance:

   
   DistributedLeaderElection election = atomix.create("election", DistributedLeaderElection::new);
   
 

Leaders are elected by simply registering an election callback on a leader election resource instance:

   
   election.onElection(epoch -> {
     // do stuff...
   });
   
 

The first election instance that registers an election callback will automatically be elected the leader. If the elected leader becomes disconnected from the cluster or crashes, a new leader will automatically be elected by selecting the next available listener. Thus, the oldest instance is always guaranteed to be the leader.

When a leader is elected, the election callback will be supplied with a monotonically increasing election number known commonly as an epoch. The epoch is guaranteed to be unique across the entire cluster and over the full lifetime of a resource for any given election.

Author:

Jordan Halterman

Constructor Summary

Constructors

Constructor and Description
DistributedLeaderElection(RaftClient client)

Method Summary

Modifier and Type	Method and Description
CompletableFuture<Boolean>	isLeader(long epoch) Verifies that this instance is the current leader.
CompletableFuture<Listener<Long>>	onElection(Consumer<Long> listener) Registers a listener to be called when this instance is elected.
DistributedLeaderElection	with(Consistency consistency)

Methods inherited from class io.atomix.resource.AbstractResource

context, delete, equals, hashCode, toString

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

DistributedLeaderElection

public DistributedLeaderElection(RaftClient client)

Method Detail

with

public DistributedLeaderElection with(Consistency consistency)

Specified by:

with in interface Resource

Overrides:

with in class AbstractResource

onElection

public CompletableFuture<Listener<Long>> onElection(Consumer<Long> listener)

Registers a listener to be called when this instance is elected.

If no leader currently exists for this resource, this instance will be elected leader and the provided listener will be completed before the returned CompletableFuture. If a leader already exists for the resource, this resource's listener will be queued until all prior listeners have failed or otherwise been lost.

This method returns a CompletableFuture which can be used to block until the listener has been registered or to be notified in a separate thread once the operation completes. To block until the operation completes, use the CompletableFuture.join() method to block the calling thread:

   
   election.onElection(epoch -> {
     ...
   }).join();
   
 

Alternatively, to execute the operation asynchronous and be notified once the lock is acquired in a different thread, use one of the many completable future callbacks:

   
   election.onElection(epoch -> {
     ...
   }).thenRun(() -> System.out.println("Waiting for election..."));
   
 

Parameters:

listener - The listener to register.

Returns:

A completable future to be completed with the listener context.

isLeader

public CompletableFuture<Boolean> isLeader(long epoch)

Verifies that this instance is the current leader.

Parameters:

epoch - The epoch for which to check if this instance is the leader.

Returns:

A completable future to be completed with a boolean value indicating whether the instance is the current leader.