io.atomix.protocols.raft.storage.snapshot

Interface Snapshottable

All Known Subinterfaces:

RaftService

All Known Implementing Classes:

AbstractRaftService

public interface Snapshottable

Support for periodically persisting RaftService snapshots to disk.

To store a state machine's state, simply implement the snapshot(SnapshotWriter) method and write the complete state machine state to the snapshot via the SnapshotWriter. Raft will periodically invoke the method to take a new snapshot of the state machine's state when the underlying log rotates segments.

   
   public class MyStateMachine extends StateMachine implements Snapshottable {
     private long counter;

     public void snapshot(SnapshotWriter writer) {
       writer.writeLong(counter);
     }

     public long increment(Commit<Increment> commit) {
       counter++;
     }
   }
   
 

Snapshot writing is only one component of snapshotting. Snapshottable state machines must also be able to recover from snapshots stored on disk after a failure. When a server recovers from an existing Raft log, the log will be replayed to the state machine, and when a point in logical time (an index) at which a snapshot was taken and persisted is reached, that snapshot will be applied to the state machine via the install(SnapshotReader) method.

   
   public class MyStateMachine extends StateMachine implements Snapshottable {
     private long counter;

     public void install(SnapshotReader reader) {
       counter = reader.readLong();
     }
   }
   
 

Implementations of the install(SnapshotReader) method should always read precisely what implementations of snapshot(SnapshotWriter) write. State machines can potentially use a mixture of SNAPSHOT and other commands, and state machine implementations should take care not to overwrite non-snapshot command state with snapshots. For simpler state machines, users should use either snapshotting or log cleaning but not both.

Method Summary

Modifier and Type	Method and Description
void	install(SnapshotReader reader) Installs a snapshot of the state machine state.
void	snapshot(SnapshotWriter writer) Takes a snapshot of the state machine state.

Method Detail

snapshot

void snapshot(SnapshotWriter writer)

Takes a snapshot of the state machine state.

This method will be called each time the underlying Log rotates segments. Once the snapshot has been written, the snapshot will be stored on disk and eventually completed. Note that snapshots are normally not immediately completed upon completion of this method as servers must wait for certain conditions to be met before persisting a snapshot. Therefore, state machines should not assume that once a snapshot has been written that the state machine can or will recover from that snapshot. Snapshot writers should also ensure that all snapshottable state machine state is written on each snapshot. Typically, only the most recent snapshot is applied to a state machine upon recovery, so no assumptions should be made about the persistence or retention of older snapshots.

Parameters:

writer - The snapshot writer.

install

void install(SnapshotReader reader)

Installs a snapshot of the state machine state.

This method will be called while a server is replaying its log at startup. Typically, only the most recent snapshot of the state machine state will be installed upon log replay. State machines should recover all snapshottable state machine state from an installed snapshot.

Parameters:

reader - The snapshot reader.