Interface SnapshotHandle

public interface SnapshotHandle
A frozen, point-in-time view of a state machine's contents, ready for serialization.

Obtained from AsyncSnapshot.prepareSnapshot(). The handle must remain valid and independent of any state machine mutations until release() is called.

Lifecycle

The framework guarantees that release() is called exactly once, regardless of whether writeTo(DataOutput) was invoked, completed, or failed. Implementations must release all held resources in release(), database snapshot handles, pinned memory, file descriptors, etc.

Since:
2.0
Author:
José Bolina
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    release()
    Releases resources held by this snapshot handle.
    void
    writeTo(DataOutput out)
    Serializes the frozen state to the output stream.

  • Method Details

    • writeTo

      void writeTo(DataOutput out) throws Exception
      Serializes the frozen state to the output stream.

      Writes the complete state captured by AsyncSnapshot.prepareSnapshot() to the provided output stream. The output must be readable by AsyncSnapshot.readContentFrom(java.io.DataInput).

      This method may be called concurrently with StateMachine.apply(byte[], int, int, boolean). The implementation must only read from the frozen state captured during AsyncSnapshot.prepareSnapshot(), never from the live, mutating state. Failing to guarantee this requirement will lead to an undefined state in the snapshot the could violate consistency guarantees.

      Cancellation

      If the node is shutting down, the calling thread is interrupted. Implementations should either check Thread.isInterrupted() periodically or let InterruptedException propagate from blocking I/O.

      Parameters:
      out - the output stream
      Throws:
      Exception - on serialization failure

    • release

      void release()
      Releases resources held by this snapshot handle.

      Always called exactly once by the framework, regardless of whether writeTo(DataOutput) was called, completed successfully, or threw an exception. After this method returns, the handle must not hold any resources. This method can be called by a different thread, but not concurrently.