org.apache.ratis.statemachine

接口 StateMachine

所有超级接口:

AutoCloseable, Closeable

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). A StateMachine implementation must be threadsafe. For example, the applyTransaction(TransactionContext) method and the query(Message) method can be invoked in parallel.

嵌套类概要

嵌套类

限定符和类型	接口和说明
static interface	StateMachine.DataApi An optional API for managing data outside the raft log.
static interface	StateMachine.DataChannel For write state machine data.
static interface	StateMachine.DataStream For streaming state machine data.
static interface	StateMachine.EventApi An optional API for event notifications.
static interface	StateMachine.FollowerEventApi An optional API for follower-only event notifications.
static interface	StateMachine.LeaderEventApi An optional API for leader-only event notifications.
static interface	StateMachine.Registry A registry to support different state machines in multi-raft environment.

字段概要

字段

限定符和类型	字段和说明
static org.slf4j.Logger	LOG

方法概要

限定符和类型	方法和说明
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 StateMachine.DataApi object.
default StateMachine.EventApi	event() Get the StateMachine.EventApi object.
default StateMachine.FollowerEventApi	followerEvent() Get the StateMachine.FollowerEventApi 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 raftServer, RaftGroupId raftGroupId, RaftStorage storage) Initializes the State Machine with the given parameter.
default StateMachine.LeaderEventApi	leaderEvent() Get the StateMachine.LeaderEventApi object.
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) Start a transaction for the given request.
default TransactionContext	startTransaction(org.apache.ratis.proto.RaftProtos.LogEntryProto entry, org.apache.ratis.proto.RaftProtos.RaftPeerRole role) Start a transaction for the given log entry for non-leaders.
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 given proto to a string.

从接口继承的方法 java.io.Closeable

close

字段详细资料

LOG

static final org.slf4j.Logger LOG

方法详细资料

data

default StateMachine.DataApi data()

Get the StateMachine.DataApi object. If this StateMachine chooses to support the optional 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.

返回:

The StateMachine.DataApi object.

event

default StateMachine.EventApi event()

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

返回:

The StateMachine.EventApi object.

leaderEvent

default StateMachine.LeaderEventApi leaderEvent()

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

返回:

The StateMachine.LeaderEventApi object.

followerEvent

default StateMachine.FollowerEventApi followerEvent()

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

返回:

The StateMachine.LeaderEventApi object.

initialize

void initialize(RaftServer raftServer,
                RaftGroupId raftGroupId,
                RaftStorage storage)
         throws IOException

Initializes the State Machine with the given parameter. The state machine must, if there is any, read the latest snapshot.

抛出:

IOException

getLifeCycleState

LifeCycle.State getLifeCycleState()

Returns the lifecycle state for this StateMachine.

返回:

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.

抛出:

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.

返回:

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.

抛出:

IOException

getStateMachineStorage

StateMachineStorage getStateMachineStorage()

返回:

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

Start a transaction for the given request. This method can be invoked in parallel when there are multiple requests. The implementation should validate the request, prepare a RaftProtos.StateMachineLogEntryProto, and then build a TransactionContext. The implementation should also be light-weighted.

返回:

a transaction with the content to be written to the log.

抛出:

IOException - thrown by the state machine while validation

另请参阅:

TransactionContext.Builder

startTransaction

default TransactionContext startTransaction(org.apache.ratis.proto.RaftProtos.LogEntryProto entry,
                                            org.apache.ratis.proto.RaftProtos.RaftPeerRole role)

Start a transaction for the given log entry for non-leaders. This method can be invoked in parallel when there are multiple requests. The implementation should prepare a RaftProtos.StateMachineLogEntryProto, and then build a TransactionContext. The implementation should also be light-weighted.

返回:

a transaction with the content to be written to the log.

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 is called with the same strict serial order as the transaction order 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.

返回:

The Transaction context.

抛出:

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.

参数:

trx - the transaction to cancel

返回:

cancelled transaction

抛出:

IOException

applyTransactionSerial

TransactionContext applyTransactionSerial(TransactionContext trx)
                                   throws org.apache.ratis.thirdparty.com.google.protobuf.InvalidProtocolBufferException

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.

参数:

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

返回:

The Transaction context.

抛出:

org.apache.ratis.thirdparty.com.google.protobuf.InvalidProtocolBufferException

applyTransaction

CompletableFuture<Message> applyTransaction(TransactionContext trx)

Apply a committed log entry to the state machine. This method is called sequentially in strict serial order that the transactions have been committed in the log. Note that this method, which returns a future, is asynchronous. The state machine implementation may choose to apply the log entries in parallel. In that case, the order of applying entries to state machine could possibly be different from the log commit order. The implementation must be deterministic so that the raft log can be replayed in any raft peers. Note that, if there are three or more servers, the Raft algorithm makes sure the that log remains consistent even if there are hardware errors in one machine (or less than the majority number of machines). Any exceptions thrown in this method are treated as unrecoverable errors (such as hardware errors). The server will be shut down when it occurs. Administrators should manually fix the underlying problem and then restart the machine.

参数:

trx - the transaction state including the log entry that has been replicated to a majority of the raft peers.

返回:

a future containing the result message of the transaction, where the result message will be replied to the client. When there is an application level exception (e.g. access denied), the state machine may complete the returned future exceptionally. The exception will be wrapped in an StateMachineException and then replied to the client.

getLastAppliedTermIndex

TermIndex getLastAppliedTermIndex()

返回:

the last term-index applied by this StateMachine.

toStateMachineLogEntryString

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

Converts the given proto to a string.

参数:

proto - state machine proto

返回:

the string representation of the proto.