com.bigdata.quorum

Interface QuorumActor<S extends Remote,C extends QuorumClient<S>>

All Known Implementing Classes:

AbstractQuorum.QuorumActorBase, MockQuorumFixture.MockQuorum.MockQuorumActor

public interface QuorumActor<S extends Remote,C extends QuorumClient<S>>

An interface that causes various changes in the distributed quorum state required to execute the intention of a QuorumMember service and its cognizant AbstractQuorum. The QuorumActor is responsible for making coherent changes in the distributed quorum state. However, when a service terminates abnormally, is partitioned from the distributed quorum, etc., then the distributed quorum state MAY temporary be inconsistent. For example, when a service loses its zookeeper connection, zookeeper will remove all ephemeral znodes for that service, but the order in which those tokens are removed is not specified.

The QuorumActor will reject operations whose preconditions are not met (on member add, pipeline add, vote cast, service join, set token, etc.) and for take additional operations as necessary to ensure that postconditions are satisfied (on remove). This asymmetry in the API is intended to make it easier for a service to "remove" itself from the various collections maintained in the distributed quorum state.

The preconditions for add are:

memberAdd()

none.

pipelineAdd()

member.

castVote(long)

member (service implicitly joins pipeline if not present).

serviceJoin()

member, pipeline, consensus around cast vote, predecessor in the vote order is joined

setToken(long)

member, pipeline, consensus around cast vote, first in the vote order, new value is GT the lastValidToken.

The post-conditions for remove are:

memberRemove()

not joined, no vote cast, not in pipeline, not member.

pipelineRemove()

not in pipeline, vote withdrawn, service not joined.

withdrawVote()

vote withdrawn, service not joined.

serviceLeave()

vote withdrawn, not in pipeline, service not joined.

clearToken()

This operation does not have any pre- or post-conditions. However, services will quickly recognize that the quorum token is no longer valid and will initiate local state changes required to prepare themselves to form a new quorum.

The methods on this interface must be atomic with respect to the observed state change reported by the paired QuorumWatcher and the update of the local Quorum object's internal state. Without this postcondition, a QuorumActor could issue two requests, such as memberAdd(); pipelineAdd(); and have the second request rejected based on preconditions if the QuorumWatcher had not yet seen the state change for the first request.

Author:

thompsonbry@users.sourceforge.net

See Also:

QuorumWatcher

Method Summary

Methods

Modifier and Type	Method and Description
void	castVote(long lastCommitTime) Cast a vote on the behalf of the associated service.
void	clearToken() Clear the quorum token.
void	forceRemoveService(UUID serviceId) Remove the service from the quorum.
QuorumMember<S>	getQuorumMember() The service on whose behalf this class is acting.
Quorum<S,C>	getQuourm() The Quorum.
UUID	getServiceId() The UUID of the service on whose behalf this class is acting.
void	memberAdd() Add the service to the set of quorum members.
void	memberRemove() Remove the service from the set of quorum members.
void	pipelineAdd() Add the service to the write pipeline.
void	pipelineRemove() Remove the service from the write pipeline.
void	serviceJoin() Add the associated service to the set of joined services for the quorum.
void	serviceLeave() Remove the associated service from the set of joined services for the quorum.
void	setToken(long newToken) Atomically set the lastValidToken and the current token on the quorum equal to the given token.
void	withdrawVote() Withdraw the vote cast by the service (a service has only one vote).

Method Detail

getQuourm

Quorum<S,C> getQuourm()

The Quorum.

getQuorumMember

QuorumMember<S> getQuorumMember()

The service on whose behalf this class is acting.

getServiceId

UUID getServiceId()

The UUID of the service on whose behalf this class is acting.

memberAdd

void memberAdd()

Add the service to the set of quorum members.

memberRemove

void memberRemove()

Remove the service from the set of quorum members.

pipelineAdd

void pipelineAdd()

Add the service to the write pipeline.

pipelineRemove

void pipelineRemove()

Remove the service from the write pipeline.

castVote

void castVote(long lastCommitTime)

Cast a vote on the behalf of the associated service. If the service is not part of the pipeline, then it is implicitly added to the pipeline. If the service has already voted for some other lastCommitTime, then that vote is withdrawn before the new vote is cast. Services do not withdraw their cast votes until a quorum breaks and a new consensus needs to be established. When it does, then need to consult their root blocks and vote their then current lastCommitTime.

When a service needs to re-synchronize with a quorum, it initially votes its current lastCommitTime. Once the service is receiving writes from the write pipeline and has synchronized any historical delta, it will update its vote and join the quorum at the next commit point (or immediately if there are no outstanding writes against the quorum).

Parameters:

lastCommitTime - The lastCommitTime timestamp for which the service casts its vote.

Throws:

IllegalArgumentException - if the lastCommitTime is negative.

withdrawVote

void withdrawVote()

Withdraw the vote cast by the service (a service has only one vote).

serviceJoin

void serviceJoin()

Add the associated service to the set of joined services for the quorum.

serviceLeave

void serviceLeave()

Remove the associated service from the set of joined services for the quorum.

setToken

void setToken(long newToken)

Atomically set the lastValidToken and the current token on the quorum equal to the given token. This method is invoked when the leader is elected, passing in newToken := lastValidToken + 1.

clearToken

void clearToken()

Clear the quorum token.

forceRemoveService

void forceRemoveService(UUID serviceId)

Remove the service from the quorum. This should be called when a problem with the service is reported to the quorum leader, for example as a result of a failed RMI request or failed socket level write replication. Such errors arise either from network connectivity or service death. These problems will generally be cured, but the heatbeat timeout to cure the problem can cause write replication to block. This method may be used to force the timely reordering of the pipeline in order to work around the replication problem. This is not a permenant disabling of the service - the service may be restarted or may recover and reenter the quorum at any time.

Parameters:

serviceId - The UUID of the service to be removed.

See Also:

HA wire pulling and sure kill testing