public abstract class KetchLeader extends Object
A leader instance starts up in
KetchLeader.State.CANDIDATE
and tries
to begin a new term by sending an
ElectionRound
to all replicas. Its
term starts if a majority of replicas have accepted this leader instance for
the term.
Once elected by a majority the instance enters
KetchLeader.State.LEADER
and runs
proposals offered to queueProposal(Proposal)
. This continues until
the leader is timed out for inactivity, or is deposed by a competing leader
gaining its own majority.
Once timed out or deposed this KetchLeader
instance should be
discarded, and a new instance takes over.
Each leader instance coordinates a group of
KetchReplica
s. Replica instances are
owned by the leader instance and must be discarded when the leader is
discarded.
In Ketch all push requests are issued through the leader. The steps are as
follows (see KetchPreReceive
for an
example):
Proposal
with the
ReceiveCommand
s that represent the push.
queueProposal(Proposal)
on the leader instance.
Proposal.await()
.
Proposal.getCommands()
, looking at
Command.getResult()
.
The leader gains consensus by first pushing the needed objects and a
RefTree
representing the
desired target repository state to the refs/txn/accepted
branch on
each of the replicas. Once a majority has succeeded, the leader commits the
state by either pushing the refs/txn/accepted
value to
refs/txn/committed
(for Ketch-aware replicas) or by pushing updates
to refs/heads/master
, etc. for stock Git replicas.
Internally, the actual transport to replicas is performed on background
threads via the KetchSystem
's
executor service. For performance, the
KetchLeader
,
KetchReplica
and
Proposal
objects share some state,
and may invoke each other's methods on different threads. This access is
protected by the leader's lock
object. Care must be taken to prevent
concurrent access by correctly obtaining the leader's lock.
Modifier and Type | Class and Description |
---|---|
static class |
KetchLeader.State
Current state of the leader instance.
|
Modifier | Constructor and Description |
---|---|
protected |
KetchLeader(KetchSystem system)
Construct a leader for a Ketch instance.
|
Modifier and Type | Method and Description |
---|---|
protected abstract Repository |
openRepository()
Get an instance of the repository for use by a leader thread.
|
void |
queueProposal(Proposal proposal)
Queue a reference update proposal for consensus.
|
void |
setReplicas(Collection<KetchReplica> replicas)
Configure the replicas used by this Ketch instance.
|
void |
shutdown()
Gracefully shutdown this leader and cancel outstanding operations.
|
LeaderSnapshot |
snapshot()
Snapshot this leader
|
String |
toString() |
protected KetchLeader(KetchSystem system)
system
- Ketch system configuration the leader must adhere to.public void setReplicas(Collection<KetchReplica> replicas)
Replicas should be configured once at creation before any proposals are executed. Once elections happen, reconfiguration is a complicated concept that is not currently supported.
replicas
- members participating with the same repository.protected abstract Repository openRepository() throws IOException
The caller will close the repository.
IOException
- cannot reopen the repository for the leader.public void queueProposal(Proposal proposal) throws InterruptedException, IOException
This method does not wait for consensus to be reached. The proposal is checked to look for risks of conflicts, and then submitted into the queue for distribution as soon as possible.
Callers must use Proposal.await()
to see if the proposal is done.
proposal
- the proposed reference updates to queue for consideration.
Once execution is complete the individual reference result
fields will be populated with the outcome.InterruptedException
- current thread was interrupted. The proposal may have been
aborted if it was not yet queued for execution.IOException
- unrecoverable error preventing proposals from being attempted
by this leader.public LeaderSnapshot snapshot()
public void shutdown()
Copyright © 2020 Eclipse JGit Project. All rights reserved.