Class ELECTION

java.lang.Object
org.jgroups.stack.Protocol
org.jgroups.protocols.raft.ELECTION
All Implemented Interfaces:
org.jgroups.Lifecycle
public class ELECTION extends org.jgroups.stack.Protocol
The default leader election algorithm.

Performs leader election. This implementation takes full advantage of JGroup's membership events with View. When the current node is the view coordinator, it starts a voting thread to ask all members to send their information. The voting thread stops when a new leader is elected.

The process that starts the voting thread is not trying to elect itself. The process running the voting process increases its term and asks all nodes about their term and log index information to select the new leader, in the form of VoteResponse. For safety reasons, only the nodes with the most up-to-date log can be elected a leader. With a response from the majority processes, the leader with the higher term and log index is elected. The oldest process (view coordinator) in the system has a priority. Once decided, the process sends a message reliably to everyone identifying the new leader, with the LeaderElected message.

After a leader is elected, a new election round starts on view changes only if the leader left the cluster. In case of losing a majority, the leader steps down.

This implementation is more robust than building with heartbeats, leading to fewer disruptions in the cluster with unnecessary (competing) election rounds. This also means the leader is capable of stepping down. Referred to in ยง6.2 of Ongaro's dissertation to prevent stale leadership information.

More information is available in the design docs.

Since:
0.1
Author:
Bela Ban
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final short
    ELECTION_ID
     
    static final short
    LEADER_ELECTED
     
    protected int
    num_voting_rounds
     
    static final short
    PRE_VOTE_REQ
     
    static final short
    PRE_VOTE_RSP
     
    protected RAFT
    raft
     
    protected org.jgroups.View
    view
     
    static final short
    VOTE_REQ
     
    static final short
    VOTE_RSP
     
    protected long
    vote_timeout
     

    Fields inherited from class org.jgroups.stack.Protocol

    after_creation_hook, down_prot, ergonomics, id, local_addr, log, policies, preview_warning, stack, stats, up_prot

  • Constructor Summary

    Constructors
    Constructor
    Description
    ELECTION()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    protected org.jgroups.Address
    determineLeader(org.jgroups.Address exclude)
     
    Object
    down(org.jgroups.Event evt)
     
    Instant
    electionEnd()
     
    LatencyMetrics
    electionLatency()
     
    double
    electionMeanLatency()
     
    Instant
    electionStart()
     
    org.jgroups.util.ResponseCollector<org.jgroups.protocols.raft.election.VoteResponse>
    getVotes()
     
    protected void
    handleMessage(org.jgroups.Message msg, RaftHeader hdr)
     
    protected void
    handleView(org.jgroups.View v)
     
    void
    init()
     
    protected final boolean
    isMajorityAvailable()
     
    protected boolean
    isViewCoordinator()
     
    boolean
    isVotingThreadRunning()
     
    RAFT
    raft()
     
    org.jgroups.protocols.raft.election.BaseElection
    raft(RAFT r)
     
    void
    resetStats()
     
    boolean
    runVotingThread()
     
    protected void
    sendLeaderElectedMessage(org.jgroups.Address leader, long term)
     
    protected void
    sendVoteRequest(long new_term)
     
    protected void
    sendVoteResponse(org.jgroups.Address dest, long term, long last_log_term, long last_log_index)
     
    void
    start()
     
    CompletionStage<org.jgroups.Address>
    startForcedElection(org.jgroups.Address exclude)
    Starts a forced leader election, excluding the given address from candidacy.
    org.jgroups.protocols.raft.election.BaseElection
    startVotingThread()
     
    void
    stop()
     
    org.jgroups.protocols.raft.election.BaseElection
    stopVotingThread()
     
    long
    timeSinceLastElection()
     
    Object
    up(org.jgroups.Event evt)
     
    Object
    up(org.jgroups.Message msg)
     
    void
    up(org.jgroups.util.MessageBatch batch)
     
    long
    voteTimeout()
     
    org.jgroups.protocols.raft.election.BaseElection
    voteTimeout(long timeoutMs)
    Defines the default timeout in milliseconds to utilize during any election operation.

    Methods inherited from class org.jgroups.stack.Protocol

    accept, addPolicy, addr, addr, afterCreationHook, destroy, down, down, enableStats, getAddress, getComponents, getDownProtocol, getDownServices, getId, getIdsAbove, getLevel, getLog, getName, getPolicies, getProtocolStack, getSocketFactory, getThreadFactory, getTransport, getUpProtocol, getUpServices, getValue, isErgonomics, level, parse, policies, previewWarning, previewWarning, providedDownServices, providedUpServices, removePolicy, requiredDownServices, requiredUpServices, resetStatistics, setAddress, setDownProtocol, setErgonomics, setId, setLevel, setPolicies, setProtocolStack, setSocketFactory, setUpProtocol, setValue, statsEnabled, toString

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Field Details

    • ELECTION_ID

      public static final short ELECTION_ID
      See Also:

    • VOTE_REQ

      public static final short VOTE_REQ
      See Also:

    • VOTE_RSP

      public static final short VOTE_RSP
      See Also:

    • LEADER_ELECTED

      public static final short LEADER_ELECTED
      See Also:

    • PRE_VOTE_REQ

      public static final short PRE_VOTE_REQ
      See Also:

    • PRE_VOTE_RSP

      public static final short PRE_VOTE_RSP
      See Also:

    • raft

      protected RAFT raft

    • vote_timeout

      protected long vote_timeout

    • num_voting_rounds

      protected int num_voting_rounds

    • view

      protected volatile org.jgroups.View view

  • Constructor Details

    • ELECTION

      public ELECTION()

  • Method Details

    • handleView

      protected void handleView(org.jgroups.View v)

    • voteTimeout

      public long voteTimeout()

    • voteTimeout

      public org.jgroups.protocols.raft.election.BaseElection voteTimeout(long timeoutMs)
      Defines the default timeout in milliseconds to utilize during any election operation.
      Parameters:
      timeoutMs - Timeout value in milliseconds.
      Returns:
      This election instance.
      Throws:
      IllegalArgumentException - In case timeout is less than or equal to 0.

    • raft

      public RAFT raft()

    • raft

      public org.jgroups.protocols.raft.election.BaseElection raft(RAFT r)

    • getVotes

      public org.jgroups.util.ResponseCollector<org.jgroups.protocols.raft.election.VoteResponse> getVotes()

    • isVotingThreadRunning

      public boolean isVotingThreadRunning()

    • runVotingThread

      public boolean runVotingThread()

    • electionStart

      public Instant electionStart()

    • electionEnd

      public Instant electionEnd()

    • timeSinceLastElection

      public long timeSinceLastElection()

    • electionMeanLatency

      public double electionMeanLatency()

    • resetStats

      public void resetStats()
      Overrides:
      resetStats in class org.jgroups.stack.Protocol

    • init

      public void init() throws Exception
      Specified by:
      init in interface org.jgroups.Lifecycle
      Overrides:
      init in class org.jgroups.stack.Protocol
      Throws:
      Exception

    • start

      public void start() throws Exception
      Specified by:
      start in interface org.jgroups.Lifecycle
      Overrides:
      start in class org.jgroups.stack.Protocol
      Throws:
      Exception

    • stop

      public void stop()
      Specified by:
      stop in interface org.jgroups.Lifecycle
      Overrides:
      stop in class org.jgroups.stack.Protocol

    • down

      public Object down(org.jgroups.Event evt)
      Overrides:
      down in class org.jgroups.stack.Protocol

    • up

      public Object up(org.jgroups.Event evt)
      Overrides:
      up in class org.jgroups.stack.Protocol

    • up

      public Object up(org.jgroups.Message msg)
      Overrides:
      up in class org.jgroups.stack.Protocol

    • up

      public void up(org.jgroups.util.MessageBatch batch)
      Overrides:
      up in class org.jgroups.stack.Protocol

    • electionLatency

      public LatencyMetrics electionLatency()
      Returns:
      election latency metrics, or disabled metrics if stats are off.

    • handleMessage

      protected void handleMessage(org.jgroups.Message msg, RaftHeader hdr)

    • isViewCoordinator

      protected boolean isViewCoordinator()

    • determineLeader

      protected org.jgroups.Address determineLeader(org.jgroups.Address exclude)

    • isMajorityAvailable

      protected final boolean isMajorityAvailable()

    • startForcedElection

      public CompletionStage<org.jgroups.Address> startForcedElection(org.jgroups.Address exclude)
      Starts a forced leader election, excluding the given address from candidacy.

      Must be called on the view coordinator. The excluded address still participates in quorum (votes are collected from it), but it is skipped when determining the leader.

      Parameters:
      exclude - the address to exclude from leader candidacy, or null for no exclusion.
      Returns:
      a stage that completes with the newly elected leader's address.

    • startVotingThread

      public org.jgroups.protocols.raft.election.BaseElection startVotingThread()

    • sendVoteRequest

      protected void sendVoteRequest(long new_term)

    • sendLeaderElectedMessage

      protected void sendLeaderElectedMessage(org.jgroups.Address leader, long term)

    • sendVoteResponse

      protected void sendVoteResponse(org.jgroups.Address dest, long term, long last_log_term, long last_log_index)

    • stopVotingThread

      public org.jgroups.protocols.raft.election.BaseElection stopVotingThread()