com.bigdata.quorum

Interface QuorumStateChangeListener

All Known Subinterfaces:

QuorumMember<S>, QuorumService<S>

All Known Implementing Classes:

AbstractQuorumMember, QuorumCommitImpl, QuorumPipelineImpl, QuorumReadImpl, QuorumServiceBase, QuorumStateChangeListenerBase

public interface QuorumStateChangeListener

A non-remote interface containing only and all distributed quorum state change messages for this QuorumMember. These messages are generated by the QuorumWatcher for the QuorumMember when it notices the corresponding change in the distributed quorum state. Thus, all methods on this interface indicate observed state changes. The QuorumActor is responsible for causing changes in the distributed quorum state, but it DOES NOT generate these messages - that task falls to the QuorumWatcher.

Quorum members have strict preconditions on their actions, which are documented by the QuorumActor. In addition, QuorumWatcher maintains various postconditions (for example, a member leave implies a service leave). Together, these preconditions and postconditions imply an ordering over the QuorumStateChangeListeners.

However, because this interface reports observed state changes, it is possible that some events may occur "out of order". For example, if the quorum is maintained within zookeeper and a client looses its zookeeper connection, then zookeeper will the ephemeral znodes for that client. The order in which other clients observe those state changes in essentially arbitrary.

Implementations of this interface must not block in the event thread.

Version:

$Id: QuorumStateChangeListener.java 4069 2011-01-09 20:58:02Z thompsonbry $

Author:

Bryan Thompson

See Also:

QuorumMember, QuorumActor, QuorumWatcher, HAJournalServer reports "follower" but is in SeekConsensus and is not participating in commits (javadoc clarifications)

Method Summary

Methods

Modifier and Type	Method and Description
void	consensus(long lastCommitTime) Invoked when a consensus has been achieved among (k+1)/2 services concerning a shared lastCommitTime (really, this is not a consensus but a simple majority).
void	lostConsensus() Invoked when the consensus is lost.
void	memberAdd() Invoked when this service is added as a quorum member.
void	memberRemove() Invoked when this service is removed as a quorum member.
void	pipelineAdd() Invoked when this service is added to the write pipeline.
void	pipelineChange(UUID oldDownStreamId, UUID newDownStreamId) Invoked for this service when the downstream service in the write pipeline has changed.
void	pipelineElectedLeader() Invoked for this service when the service is already in the pipeline and this service becomes the first service in the write pipeline because all previous services in the pipeline order have been removed from the pipeline (failover into the leader position).
void	pipelineRemove() Invoked when this service is removed from the write pipeline.
void	pipelineUpstreamChange() Invoked for this service when the upstream service in the write pipeline has been removed.
void	quorumBreak() Invoked when a quorum breaks.
void	quorumMeet(long token, UUID leaderId) Invoked when a quorum meets.
void	serviceJoin() Invoked when this service joins the quorum.
void	serviceLeave() Invoked when this service leaves the quorum.

Method Detail

memberAdd

void memberAdd()

Invoked when this service is added as a quorum member.

memberRemove

void memberRemove()

Invoked when this service is removed as a quorum member.

pipelineAdd

void pipelineAdd()

Invoked when this service is added to the write pipeline. The service always enters at the of the pipeline.

pipelineRemove

void pipelineRemove()

Invoked when this service is removed from the write pipeline.

pipelineElectedLeader

void pipelineElectedLeader()

Invoked for this service when the service is already in the pipeline and this service becomes the first service in the write pipeline because all previous services in the pipeline order have been removed from the pipeline (failover into the leader position).

pipelineChange

void pipelineChange(UUID oldDownStreamId,
                  UUID newDownStreamId)

Invoked for this service when the downstream service in the write pipeline has changed. Services always enter at the end of the write pipeline, but may be removed at any position in the write pipeline.

Parameters:

oldDownstreamId - The UUID of the service which was downstream from this service in the write pipeline and null iff this service was the last service in the pipeline.

newDownstreamId - The UUID of the service which is downstream from this service in the write pipeline and null iff this service is the last service in the pipeline.

pipelineUpstreamChange

void pipelineUpstreamChange()

Invoked for this service when the upstream service in the write pipeline has been removed. This hook provides an opportunity for this service to close out its connection with the old upstream service and to prepare to establish a new connection with the new downstream service.

consensus

void consensus(long lastCommitTime)

Invoked when a consensus has been achieved among (k+1)/2 services concerning a shared lastCommitTime (really, this is not a consensus but a simple majority). This message is sent to each member service regardless of whether or not they participated in the consensus.

Once a consensus has been reached, each QuorumMember which agrees on that lastCommitTime MUST do a serviceJoin() before the quorum will meet. The first quorum member to do a service join will be elected the leader. The remaining services to do a service join will be elected followers.

Parameters:

lastCommitTime - The last commit time around which a consensus was established.

See Also:

serviceJoin(), #electedLeader(long), #electedFollower(long), lostConsensus()

lostConsensus

void lostConsensus()

Invoked when the consensus is lost. Services do not withdraw their cast votes until a quorum breaks and a new consensus needs to be established. This message is sent to each member service regardless of whether or not they participated in the consensus.

See Also:

consensus(long)

serviceJoin

void serviceJoin()

Invoked when this service joins the quorum.

serviceLeave

void serviceLeave()

Invoked when this service leaves the quorum.

quorumMeet

void quorumMeet(long token,
              UUID leaderId)

Invoked when a quorum meets. The state of the met quorum can be queried using the token. Quorum members can use this to decide whether they are the leader (using #isLeader(long), joined as a follower (using #isFollower(long)), or do not participate in the quorum (this message is sent to all quorum members, so this service might not be part of the met qourum).

The following pre-conditions will be satisfied before this message is sent to the QuorumMember:

• There will be at least (k+1)/2 services which have voted for the same lastCommitTime.
• There will be at (k+1)/2 services joined with the quorum. The join order will be the same as the Quorum.getVotes() for the services which voted for the lastCommitTime
around which a consensus was formed.
• If this quorum member is joined with the quorum it will have observed its own memberAdd(), pipelineAdd(), consensus(long), and serviceJoin() events.
• The joined services will be arranged in a write pipeline, with the leader at the head of that pipeline.

When control returns from this method, the following post-conditions should be true:

• The service should be prepared to accept reads.
• If the service was elected as the quorum leader, then it should be prepared to accept writes.

If the QuorumMember is joined with the quorum but it can not satisfy these post-conditions, then it must leave the Quorum.

Parameters:

token - The newly assigned quorum token.

leaderId - The UUID of the service which was elected to be the quorum leader. This information is only valid for the scope of the accompanying quorum token. (The leaderId may be obtained from #getLeader(long) at any time for a met quorum.)

quorumBreak

void quorumBreak()

Invoked when a quorum breaks. The service MUST handle handle this event by (a) doing an abort() which will any buffered writes and reload their current root block; and (b) casting a vote for their current commit time. Once a consensus is reached on the current commit time, services will be joined in the vote order, a new leader will be elected, and the quorum will meet again. This message is sent to all member services, regardless of whether they were joined with the met quorum.