Class ReplStateMachine<K,V>

java.lang.Object
org.jgroups.raft.util.ReplStateMachine<K,V>
All Implemented Interfaces:
StateMachine
public class ReplStateMachine<K,V> extends Object implements StateMachine
Dummy replicated hashmap state machine
Since:
1.0.5
Author:
Bela Ban

  • Field Details

  • Constructor Details

    • ReplStateMachine

      public ReplStateMachine()

  • Method Details

    • apply

      public byte[] apply(byte[] data, int offset, int length, boolean serialize_response)
      Description copied from interface: StateMachine
      Applies a command to the state machine.

      The contents of the byte[] buffer are interpreted by the state machine and serialized into the actual command. The serialization mechanism should be strict with the given intervals to avoid copying the byte buffer.

      This method should never throw an exception as it could leave the protocol in an undefined state. Instead, it should serialize any exception and return the buffer for the client application to handle the exception.

      Specified by:
      apply in interface StateMachine
      Parameters:
      data - The byte[] buffer
      offset - The offset at which the data starts
      length - The length of the data
      serialize_response - If true, serialize and return the response, else return null
      Returns:
      A serialized response value, or null (e.g. if the method returned void)

    • readContentFrom

      public void readContentFrom(DataInput in)
      Description copied from interface: StateMachine
      Reads the contents of the state machine from an input stream.

      This can be the case when an InstallSnapshot RPC is used to bootstrap a new node, or a node that's lagging far behind. The parsing depends on the concrete state machine implementation, but the idea is that the stream is a sequence of commands, each of which can be passed to StateMachine.apply(byte[], int, int, boolean).

      Synchronous Execution & Event Loop Blocking

      This method is invoked synchronously by the main Raft event loop. While this method is executing, the core Raft protocol is entirely blocked. The node will not process incoming client requests until the restoration is fully complete. For an asynchronous version, check AsyncSnapshot.

      Buffer Ownership & Determinism

      The framework owns the provided DataInput buffer, and this ownership is released the moment this method finishes. The implementation must completely read the buffer and restore its internal state deterministically before returning. The state machine implementation may need to remove all contents before populating itself from the stream.

      This method is never called concurrently with invocations to StateMachine.apply(byte[], int, int, boolean). No locking mechanism is needed in the state machine.

      Failures

      Similar to StateMachine.apply(byte[], int, int, boolean), exceptions must be handled carefully when restoring the state machine. If an exception is thrown, the underlying system could be left in an undefined state. You should ensure the state machine remains consistent and deterministic.

      Specified by:
      readContentFrom in interface StateMachine
      Parameters:
      in - The input stream

    • writeContentTo

      public void writeContentTo(DataOutput out) throws Exception
      Description copied from interface: StateMachine
      Writes the contents of the state machine to an output stream.

      This is typically called on the leader to provide state to a new node, or a node that's lagging far behind. All the data needed to completely recover the state machine should be written to the buffer.

      Synchronous Execution & Event Loop Blocking

      This method is invoked synchronously by the main Raft event loop. While this method is executing, the core Raft protocol is entirely blocked. Updates to the state machine may need to be put on hold while the state is written to the output stream. Otherwise, it is not possible to guarantee a consistent view of the state machine. For an asynchronous version, check AsyncSnapshot.

      Buffer Ownership & Determinism

      The framework owns the DataOutput stream. The implementation must deterministically and completely write its current state to the stream before returning, as the buffer is flushed and released immediately after the method finishes. Try to stick to the minimum data needed to restore the state machine.

      Optimization Recommendations

      Because this method blocks the main event loop until the snapshot is fully written, users are strongly encouraged to think carefully about optimizations. To minimize the blocking time, consider maintaining a fast serialization format or utilizing internal Copy-on-Write (COW) data structures so that the actual state iteration and serialization can be performed as quickly as possible.

      Failures

      If an exception is thrown while taking the snapshot, we do not submit the underlying buffer to remote nodes.

      Specified by:
      writeContentTo in interface StateMachine
      Parameters:
      out - The output stream
      Throws:
      Exception - Thrown on serialization or other failure.