Interface IConcurrentStateMachine

statemachine/concurrent.go:45–176

IConcurrentStateMachine is the interface to be implemented by application's state machine when concurrent access to the state machine is required. For a typical IConcurrentStateMachine type, most of its managed data is expected to be fitted into memory, Dragonboat manages its captured snapshots and

// but without concurrent access support. Users are recommended to use the
// IStateMachine interface whenever possible.
type IConcurrentStateMachine interface {
	// Update updates the IConcurrentStateMachine instance. The input Entry slice
	// is list of continuous proposed and committed commands from clients, they
	// are provided together as a batch so the IConcurrentStateMachine
	// implementation can choose to batch them and apply together to hide latency.
	//
	// The Update method must be deterministic, meaning that given the same initial
	// state of IConcurrentStateMachine and the same input sequence, it should
	// reach to the same updated state and outputs the same returned results. The
	// input entry slice should be the only input to this method. Reading from
	// the system clock, random number generator or other similar external data
	// sources will violate the deterministic requirement of the Update method.
	//
	// The IConcurrentStateMachine implementation should not keep a reference to
	// the input entry slice after return.
	//
	// Update returns the input entry slice with the Result field of all its
	// members set.
	//
	// Update returns an error when there is unrecoverable error for updating the
	// on disk state machine, e.g. disk failure when trying to update the state
	// machine.
	Update([]Entry) ([]Entry, error)
	// Lookup queries the state of the IConcurrentStateMachine instance and
	// returns the query result as a byte slice. The input byte slice specifies
	// what to query, it is up to the IConcurrentStateMachine implementation to
	// interpret the input byte slice.
	//
	// When an error is returned by the Lookup() method, the error will be passed
	// to the caller of NodeHost's ReadLocalNode() or SyncRead() methods to be
	// handled. A typical scenario for returning an error is that the state
	// machine has already been closed or aborted from a RecoverFromSnapshot
	// procedure when Lookup is being handled.
	//
	// The IConcurrentStateMachine implementation should not keep a reference of
	// the input byte slice after return.
	//
	// The Lookup() method is a read only method, it should never change the state
	// of the IConcurrentStateMachine instance.
	Lookup(interface{}) (interface{}, error)
	// PrepareSnapshot prepares the snapshot to be concurrently captured and saved.
	// PrepareSnapshot is invoked before SaveSnapshot is called and it is invoked
	// with mutual exclusion protection from the Update method.
	//
	// PrepareSnapshot in general saves a state identifier of the current state,
	// such state identifier is usually a version number, a sequence number, a
	// change ID or some other in memory small data structure used for describing
	// the point in time state of the state machine. The state identifier is
	// returned as an interface{} and it is provided to the SaveSnapshot() method
	// so the state machine state at that identified point in time can be saved
	// when SaveSnapshot is invoked.
	//
	// PrepareSnapshot returns an error when there is unrecoverable error for
	// preparing the snapshot.
	PrepareSnapshot() (interface{}, error)
	// SaveSnapshot saves the point in time state of the IConcurrentStateMachine
	// identified by the input state identifier to the provided io.Writer backed
	// by a file on disk and the provided ISnapshotFileCollection instance. This