org.apache.ratis.statemachine

Interface StateMachine

All Superinterfaces:

AutoCloseable, Closeable

All Known Implementing Classes:

BaseStateMachine

public interface StateMachine
extends Closeable

StateMachine is the entry point for the custom implementation of replicated state as defined in the "State Machine Approach" in the literature (see https://en.wikipedia.org/wiki/State_machine_replication).

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	StateMachine.DataApi
static interface	StateMachine.DataStream For streaming state machine data.
static interface	StateMachine.Registry A registry to support different state machines in multi-raft environment.

Field Summary

Fields

Modifier and Type	Field and Description
static org.slf4j.Logger	LOG

Method Summary

Modifier and Type	Method and Description
CompletableFuture<Message>	applyTransaction(TransactionContext trx) Apply a committed log entry to the state machine.
TransactionContext	applyTransactionSerial(TransactionContext trx) Called for transactions that have been committed to the RAFT log.
TransactionContext	cancelTransaction(TransactionContext trx) Called to notify the state machine that the Transaction passed cannot be appended (or synced).
default StateMachine.DataApi	data() Get the optional StateMachine.DataApi object.
TermIndex	getLastAppliedTermIndex()
SnapshotInfo	getLatestSnapshot() Returns the information for the latest durable snapshot.
LifeCycle.State	getLifeCycleState() Returns the lifecycle state for this StateMachine.
StateMachineStorage	getStateMachineStorage()
void	initialize(RaftServer server, RaftGroupId groupId, RaftStorage storage) Initializes the State Machine with the given server, group and storage.
default void	notifyExtendedNoLeader(org.apache.ratis.proto.RaftProtos.RoleInfoProto roleInfoProto) Notify the Leader's state machine that a leader has not been elected for a long time this notification is based on "raft.server.leader.election.timeout"
default void	notifyGroupRemove() Notify about group removal in the state machine.
default void	notifyIndexUpdate(long term, long index) Called to notify state machine about indexes which are processed internally by Raft Server, this currently happens when conf entries are processed in raft Server.
default CompletableFuture<TermIndex>	notifyInstallSnapshotFromLeader(org.apache.ratis.proto.RaftProtos.RoleInfoProto roleInfoProto, TermIndex firstTermIndexInLog) Notify the Follower's state machine that the leader has purged entries from its log and hence to catch up, the Follower state machine would have to install the latest snapshot.
default void	notifyLeaderChanged(RaftGroupMemberId groupMemberId, RaftPeerId raftPeerId) Notify the state machine that a RaftPeer has been elected as leader.
default void	notifyLogFailed(Throwable t, org.apache.ratis.proto.RaftProtos.LogEntryProto failedEntry) Notify the state machine that the pipeline has failed.
void	notifyNotLeader(Collection<TransactionContext> pendingEntries) Notify the state machine that the raft peer is no longer leader.
default void	notifySlowness(org.apache.ratis.proto.RaftProtos.RoleInfoProto roleInfoProto) Notify the Leader's state machine that one of the followers is slow this notification is based on "raft.server.rpc.slowness.timeout"
void	pause() Pauses the state machine.
TransactionContext	preAppendTransaction(TransactionContext trx) This is called before the transaction passed from the StateMachine is appended to the raft log.
CompletableFuture<Message>	query(Message request) Query the state machine.
CompletableFuture<Message>	queryStale(Message request, long minIndex) Query the state machine, provided minIndex <= commit index.
void	reinitialize() Re-initializes the State Machine in PAUSED state.
TransactionContext	startTransaction(RaftClientRequest request) Validate/pre-process the incoming update request in the state machine.
long	takeSnapshot() Dump the in-memory state into a snapshot file in the RaftStorage.
default String	toStateMachineLogEntryString(org.apache.ratis.proto.RaftProtos.StateMachineLogEntryProto proto) Converts the proto object into a useful log string to add information about state machine data.

Methods inherited from interface java.io.Closeable

close

Field Detail

LOG

static final org.slf4j.Logger LOG

Method Detail

data

default StateMachine.DataApi data()

Get the optional StateMachine.DataApi object. If this StateMachine chooses to support StateMachine.DataApi, it may either implement StateMachine.DataApi directly or override this method to return a StateMachine.DataApi object. Otherwise, this StateMachine does not support StateMachine.DataApi. Then, this method returns the default noop StateMachine.DataApi object.

Returns:

The optional StateMachine.DataApi object.

initialize

void initialize(RaftServer server,
                RaftGroupId groupId,
                RaftStorage storage)
         throws IOException

Initializes the State Machine with the given server, group and storage. The state machine is responsible reading the latest snapshot from the file system (if any) and initialize itself with the latest term and index there including all the edits.

Throws:

IOException

getLifeCycleState

LifeCycle.State getLifeCycleState()

Returns the lifecycle state for this StateMachine.

Returns:

the lifecycle state.

pause

void pause()

Pauses the state machine. On return, the state machine should have closed all open files so that a new snapshot can be installed.

reinitialize

void reinitialize()
           throws IOException

Re-initializes the State Machine in PAUSED state. The state machine is responsible reading the latest snapshot from the file system (if any) and initialize itself with the latest term and index there including all the edits.

Throws:

IOException

takeSnapshot

long takeSnapshot()
           throws IOException

Dump the in-memory state into a snapshot file in the RaftStorage. The StateMachine implementation can decide 1) its own snapshot format, 2) when a snapshot is taken, and 3) how the snapshot is taken (e.g., whether the snapshot blocks the state machine, and whether to purge log entries after a snapshot is done). In the meanwhile, when the size of raft log outside of the latest snapshot exceeds certain threshold, the RaftServer may choose to trigger a snapshot if RaftServerConfigKeys.Snapshot.AUTO_TRIGGER_ENABLED_KEY is enabled. The snapshot should include the latest raft configuration.

Returns:

the largest index of the log entry that has been applied to the state machine and also included in the snapshot. Note the log purge should be handled separately.

Throws:

IOException

getStateMachineStorage

StateMachineStorage getStateMachineStorage()

Returns:

StateMachineStorage to interact with the durability guarantees provided by the state machine.

getLatestSnapshot

SnapshotInfo getLatestSnapshot()

Returns the information for the latest durable snapshot.

query

CompletableFuture<Message> query(Message request)

Query the state machine. The request must be read-only.

queryStale

CompletableFuture<Message> queryStale(Message request,
                                      long minIndex)

Query the state machine, provided minIndex <= commit index. The request must be read-only. Since the commit index of this server may lag behind the Raft service, the returned result may possibly be stale. When minIndex > getLastAppliedTermIndex(), the state machine may choose to either (1) return exceptionally, or (2) wait until minIndex <= getLastAppliedTermIndex() before running the query.

startTransaction

TransactionContext startTransaction(RaftClientRequest request)
                             throws IOException

Validate/pre-process the incoming update request in the state machine.

Returns:

the content to be written to the log entry. Null means the request should be rejected.

Throws:

IOException - thrown by the state machine while validation

preAppendTransaction

TransactionContext preAppendTransaction(TransactionContext trx)
                                 throws IOException

This is called before the transaction passed from the StateMachine is appended to the raft log. This method will be called from log append and having the same strict serial order that the transactions will have in the RAFT log. Since this is called serially in the critical path of log append, it is important to do only required operations here.

Returns:

The Transaction context.

Throws:

IOException

cancelTransaction

TransactionContext cancelTransaction(TransactionContext trx)
                              throws IOException

Called to notify the state machine that the Transaction passed cannot be appended (or synced). The exception field will indicate whether there was an exception or not.

Parameters:

trx - the transaction to cancel

Returns:

cancelled transaction

Throws:

IOException

applyTransactionSerial

TransactionContext applyTransactionSerial(TransactionContext trx)

Called for transactions that have been committed to the RAFT log. This step is called sequentially in strict serial order that the transactions have been committed in the log. The SM is expected to do only necessary work, and leave the actual apply operation to the applyTransaction calls that can happen concurrently.

Parameters:

trx - the transaction state including the log entry that has been committed to a quorum of the raft peers

Returns:

The Transaction context.

notifyIndexUpdate

default void notifyIndexUpdate(long term,
                               long index)

Called to notify state machine about indexes which are processed internally by Raft Server, this currently happens when conf entries are processed in raft Server. This keep state machine to keep a track of index updates.

Parameters:

term - term of the current log entry

index - index which is being updated

applyTransaction

CompletableFuture<Message> applyTransaction(TransactionContext trx)

Apply a committed log entry to the state machine. This method can be called concurrently with the other calls, and there is no guarantee that the calls will be ordered according to the log commit order.

Parameters:

trx - the transaction state including the log entry that has been committed to a quorum of the raft peers

getLastAppliedTermIndex

TermIndex getLastAppliedTermIndex()

notifyNotLeader

void notifyNotLeader(Collection<TransactionContext> pendingEntries)
              throws IOException

Notify the state machine that the raft peer is no longer leader.

Throws:

IOException

notifySlowness

default void notifySlowness(org.apache.ratis.proto.RaftProtos.RoleInfoProto roleInfoProto)

Notify the Leader's state machine that one of the followers is slow this notification is based on "raft.server.rpc.slowness.timeout"

Parameters:

roleInfoProto - information about the current node role and rpc delay information

notifyLogFailed

default void notifyLogFailed(Throwable t,
                             org.apache.ratis.proto.RaftProtos.LogEntryProto failedEntry)

Notify the state machine that the pipeline has failed. This notification is triggered when a log operation throws an Exception.

Parameters:

t - Exception which was caught, indicates possible cause.

failedEntry - if append failed for a specific entry, null otherwise.

notifyExtendedNoLeader

default void notifyExtendedNoLeader(org.apache.ratis.proto.RaftProtos.RoleInfoProto roleInfoProto)

Notify the Leader's state machine that a leader has not been elected for a long time this notification is based on "raft.server.leader.election.timeout"

Parameters:

roleInfoProto - information about the current node role and rpc delay information

notifyInstallSnapshotFromLeader

default CompletableFuture<TermIndex> notifyInstallSnapshotFromLeader(org.apache.ratis.proto.RaftProtos.RoleInfoProto roleInfoProto,
                                                                     TermIndex firstTermIndexInLog)

Notify the Follower's state machine that the leader has purged entries from its log and hence to catch up, the Follower state machine would have to install the latest snapshot.

Parameters:

firstTermIndexInLog - TermIndex of the first append entry available in the Leader's log.

roleInfoProto - information about the current node role and rpc delay information

Returns:

After the snapshot installation is complete, return the last included term index in the snapshot.

notifyLeaderChanged

default void notifyLeaderChanged(RaftGroupMemberId groupMemberId,
                                 RaftPeerId raftPeerId)

Notify the state machine that a RaftPeer has been elected as leader.

notifyGroupRemove

default void notifyGroupRemove()

Notify about group removal in the state machine. This function is called during group removal after all the pending transactions have been applied by the state machine.

toStateMachineLogEntryString

default String toStateMachineLogEntryString(org.apache.ratis.proto.RaftProtos.StateMachineLogEntryProto proto)

Converts the proto object into a useful log string to add information about state machine data.

Parameters:

proto - state machine proto

Returns:

the string representation of the proto.