Class ReplicatedStateMachine<K,V>

java.lang.Object
org.jgroups.raft.blocks.ReplicatedStateMachine<K,V>
All Implemented Interfaces:
StateMachine
public class ReplicatedStateMachine<K,V> extends Object implements StateMachine
A key-value store replicating its contents with RAFT via consensus
Since:
0.1
Author:
Bela Ban

  • Field Details

  • Constructor Details

    • ReplicatedStateMachine

      public ReplicatedStateMachine(org.jgroups.JChannel ch)

  • Method Details

    • timeout

      public ReplicatedStateMachine<K,V> timeout(long timeout)

    • timeout

      public long timeout()

    • allowDirtyReads

      public ReplicatedStateMachine<K,V> allowDirtyReads(boolean f)

    • allowDirtyReads

      public boolean allowDirtyReads()

    • addRoleChangeListener

      public void addRoleChangeListener(RAFT.RoleChange listener)

    • addNotificationListener

      public void addNotificationListener(ReplicatedStateMachine.Notification<K,V> n)

    • removeNotificationListener

      public void removeNotificationListener(ReplicatedStateMachine.Notification<K,V> n)

    • removeRoleChangeListener

      public void removeRoleChangeListener(RAFT.RoleChange listener)

    • lastApplied

      public long lastApplied()

    • commitIndex

      public long commitIndex()

    • channel

      public org.jgroups.JChannel channel()

    • snapshot

      public void snapshot() throws Exception
      Throws:
      Exception

    • logSize

      public long logSize()

    • raftId

      public String raftId()

    • raftId

      public ReplicatedStateMachine<K,V> raftId(String id)

    • useClassLoader

      public ReplicatedStateMachine<K,V> useClassLoader(ClassLoader classLoader)

    • classLoaderInUse

      public ClassLoader classLoaderInUse(ClassLoader classLoader)

    • dumpLog

      public String dumpLog()

    • equals

      public boolean equals(Object other)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • put

      public V put(K key, V val) throws Exception
      Adds a key value pair to the state machine. The data is not added directly, but sent to the RAFT leader and only added to the hashmap after the change has been committed (by majority decision). The actual change will be applied with callback StateMachine.apply(byte[], int, int, boolean).
      Parameters:
      key - The key to be added.
      val - The value to be added
      Returns:
      Null, or the previous value associated with key (if present)
      Throws:
      Exception

    • get

      public V get(K key) throws Exception
      Returns the value for a given key.

      When allow_dirty_reads is set, the local value is returned, possibly stale and violating linearizability. Otherwise, the request is sent through RAFT and returns a consistent value.

      Parameters:
      key - The key
      Returns:
      The value associated with key (staleness configurable via allow_dirty_reads)
      Throws:
      Exception

    • remove

      public V remove(K key) throws Exception
      Removes a key-value pair from the state machine. The data is not removed directly from the hashmap, but an update is sent via RAFT and the actual removal from the hashmap is only done when that change has been committed.
      Parameters:
      key - The key to be removed
      Throws:
      Exception

    • size

      public int size()
      Returns the number of elements in the RSM

    • apply

      public byte[] apply(byte[] data, int offset, int length, boolean serialize_response)
      ////////////////////////////////////// StateMachine callbacks /////////////////////////////////////
      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.

    • toString

      public String toString()
      ////////////////////////////////// End of StateMachine callbacks ///////////////////////////////////
      Overrides:
      toString in class Object

    • invoke

      protected V invoke(byte command, K key, V val, boolean ignore_return_value, boolean isRead) throws Exception
      Throws:
      Exception

    • notifyPut

      protected void notifyPut(K key, V val, V old_val)

    • notifyRemove

      protected void notifyRemove(K key, V old_val)

    • notifyGet

      protected void notifyGet(K key, V val)