ai.eloquent.raft

Class KeyValueStateMachine

java.lang.Object

ai.eloquent.raft.RaftStateMachine

ai.eloquent.raft.KeyValueStateMachine

public class KeyValueStateMachine
extends RaftStateMachine

This is the standard state machine we use to implement our RAFT distributed storage. It has two maps: - string to lock (for distributed locking) - string to byte[] (for distributed state) The state machine implements locks as queues. All changes can be listened for with custom listeners on the state machine.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	KeyValueStateMachine.ChangeListener This holds a locally registered callback that will be called whenever the state machine changes.

Field Summary

Fields

Modifier and Type	Field and Description
java.util.Optional<java.lang.String>	serverName The server that this state machine is running on.

Constructor Summary

Constructors

Constructor and Description
KeyValueStateMachine(java.lang.String serverName) Create a new state machine, with knowledge of what node it's running on

Method Summary

Modifier and Type	Method and Description
void	addChangeListener(KeyValueStateMachine.ChangeListener changeListener) This registers a listener that will be called whenever the key-value store changes.
protected void	addErrorListener(RaftErrorListener errorListener) Keeps track of an additional RaftErrorListener in this class
void	applyTransition(byte[] transition, long now, java.util.concurrent.ExecutorService pool) This is responsible for applying a transition to the state machine.
void	applyTransition(KeyValueStateMachineProto.Transition serializedTransition, long now, java.util.concurrent.ExecutorService pool)
protected void	clearErrorListeners() Clears all the RaftErrorListeners attached to this class.
static byte[]	createClearTransition(java.lang.String owner) This creates a serialized ClearTransient transition.
static byte[]	createGroupedTransition(byte[]... transitions) Creates a grouped transition, which executes several transitions atomically.
static byte[]	createReleaseLockTransition(java.lang.String lock, java.lang.String requester, java.lang.String uniqueHash) This creates a serialized ReleaseLock transition.
static byte[]	createRemoveValueTransition(java.lang.String key) This creates a serialized RemoveValue transition that will delete an entry in the map, if it's currently present.
static byte[]	createRequestLockTransition(java.lang.String lock, java.lang.String requester, java.lang.String uniqueHash) This creates a serialized RequestLock transition.
static byte[]	createSetValueTransition(java.lang.String key, byte[] value) This creates a serialized SetValue transition that will set an entry in the values map.
static byte[]	createSetValueTransitionWithOwner(java.lang.String key, byte[] value, java.lang.String owner) This creates a serialized SetValue transition that will set an entry in the values map, with an "owner" who is responsible for the value, which will be automatically cleaned up when the owner disconnects from the cluster.
static byte[]	createTryLockTransition(java.lang.String lock, java.lang.String requester, java.lang.String uniqueHash) This creates a serialized TryLock transition.
java.lang.String	debugTransition(byte[] transition) This is used for debugging log entries.
java.util.Collection<java.util.Map.Entry<java.lang.String,ai.eloquent.raft.KeyValueStateMachine.ValueWithOptionalOwner>>	entries() This returns the full list of entries in the state machine.
boolean	equals(java.lang.Object o)
java.util.Optional<byte[]>	get(java.lang.String key, long now) This gets a value from the values map, if it's present.
int	hashCode()
java.util.Collection<java.lang.String>	keys() This gets the current set of keys in the state machine.
java.util.Set<java.lang.String>	keysIdleSince(java.time.Duration idleTime, long now) Returns entries which have not been modified in at least |age| amount of time.
java.util.Set<java.lang.String>	keysPresentSince(java.time.Duration timeInRaft, long now) Returns entries which have not been modified in at least |age| amount of time.
java.util.Map<java.lang.String,byte[]>	map() This returns a copy of the key->value map in the state machine.
void	overwriteWithSerializedImpl(byte[] serialized, long now, java.util.concurrent.ExecutorService pool) This overwrites the current state of the state machine with a serialized proto.
java.util.Set<java.lang.String>	owners() The set of nodes that own anything in the state machine.
void	removeChangeListener(KeyValueStateMachine.ChangeListener changeListener) This removes a listener that will be called whenever the key-value store changes.
protected void	removeErrorListener(RaftErrorListener errorListener) Stop listening from a specific RaftErrorListener
com.google.protobuf.ByteString	serializeImpl() This serializes the state machine's current state into a proto that can be read from RaftStateMachine.overwriteWithSerialized(byte[], long, ExecutorService).
protected void	throwRaftError(java.lang.String incidentKey, java.lang.String debugMessage) Alert each of the RaftErrorListeners attached to this class.

Methods inherited from class ai.eloquent.raft.RaftStateMachine

getHospice, overwriteWithSerialized, serialize

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

serverName

public final java.util.Optional<java.lang.String> serverName

The server that this state machine is running on.

See Also:

RaftState.serverName

Constructor Detail

KeyValueStateMachine

public KeyValueStateMachine(java.lang.String serverName)

Create a new state machine, with knowledge of what node it's running on

Method Detail

addErrorListener

protected void addErrorListener(RaftErrorListener errorListener)

Keeps track of an additional RaftErrorListener in this class

Parameters:

errorListener - The error listener to add.

removeErrorListener

protected void removeErrorListener(RaftErrorListener errorListener)

Stop listening from a specific RaftErrorListener

Parameters:

errorListener - The error listener to be removed

clearErrorListeners

protected void clearErrorListeners()

Clears all the RaftErrorListeners attached to this class.

throwRaftError

protected void throwRaftError(java.lang.String incidentKey,
                              java.lang.String debugMessage)

Alert each of the RaftErrorListeners attached to this class.

serializeImpl

public com.google.protobuf.ByteString serializeImpl()

This serializes the state machine's current state into a proto that can be read from RaftStateMachine.overwriteWithSerialized(byte[], long, ExecutorService).

Specified by:

serializeImpl in class RaftStateMachine

Returns:

a proto of this state machine

overwriteWithSerializedImpl

public void overwriteWithSerializedImpl(byte[] serialized,
                                        long now,
                                        java.util.concurrent.ExecutorService pool)

This overwrites the current state of the state machine with a serialized proto. All the current state of the state machine is overwritten, and the new state is substituted in its place.

Specified by:

overwriteWithSerializedImpl in class RaftStateMachine

Parameters:

serialized - the state machine to overwrite this one with, in serialized form

now - the current time, for mocking.

pool - an executor pool to run lock future commits on.

applyTransition

public void applyTransition(byte[] transition,
                            long now,
                            java.util.concurrent.ExecutorService pool)

This is responsible for applying a transition to the state machine. The transition is assumed to be coming in a proto, and so is serialized as a byte array.

Specified by:

applyTransition in class RaftStateMachine

Parameters:

transition - the transition to apply, in serialized form

now - the current timestamp

pool - the pool to run any listeners on

applyTransition

public void applyTransition(KeyValueStateMachineProto.Transition serializedTransition,
                            long now,
                            java.util.concurrent.ExecutorService pool)

addChangeListener

public void addChangeListener(KeyValueStateMachine.ChangeListener changeListener)

This registers a listener that will be called whenever the key-value store changes.

Parameters:

changeListener - the listener to register

removeChangeListener

public void removeChangeListener(KeyValueStateMachine.ChangeListener changeListener)

This removes a listener that will be called whenever the key-value store changes.

Parameters:

changeListener - the listener to deregister

get

public java.util.Optional<byte[]> get(java.lang.String key,
                                      long now)

This gets a value from the values map, if it's present. Otherwise returns empty.

Parameters:

key - The key to retrieve.

now - The current time, so that we can mock transport time if appropriate.

Returns:

the value, or empty

keys

public java.util.Collection<java.lang.String> keys()

This gets the current set of keys in the state machine.

map

public java.util.Map<java.lang.String,byte[]> map()

This returns a copy of the key->value map in the state machine.

keysIdleSince

public java.util.Set<java.lang.String> keysIdleSince(java.time.Duration idleTime,
                                                     long now)

Returns entries which have not been modified in at least |age| amount of time.

Parameters:

idleTime - The amount of time an entry must have been idle in the state machine.

now - The current time.

keysPresentSince

public java.util.Set<java.lang.String> keysPresentSince(java.time.Duration timeInRaft,
                                                        long now)

Returns entries which have not been modified in at least |age| amount of time.

Parameters:

timeInRaft - The amount of time an entry must have been in the state machine.

now - The current time.

entries

public java.util.Collection<java.util.Map.Entry<java.lang.String,ai.eloquent.raft.KeyValueStateMachine.ValueWithOptionalOwner>> entries()

This returns the full list of entries in the state machine. This is threadsafe, insofar as it comes from a ConcurrentHashMap.

owners

public java.util.Set<java.lang.String> owners()

The set of nodes that own anything in the state machine. This is an optional override, only for state machines that have a notion of ownership.

Overrides:

owners in class RaftStateMachine

debugTransition

public java.lang.String debugTransition(byte[] transition)

This is used for debugging log entries. Mostly ignored, but very useful for debugging fuzz tests that are failing.

Overrides:

debugTransition in class RaftStateMachine

Parameters:

transition - the transition to debug

Returns:

a rendered string version of the transition

equals

public boolean equals(java.lang.Object o)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

createRequestLockTransition

public static byte[] createRequestLockTransition(java.lang.String lock,
                                                 java.lang.String requester,
                                                 java.lang.String uniqueHash)

This creates a serialized RequestLock transition.

Parameters:

lock - the lock name

requester - the requester of the lock

uniqueHash - the unique hash to deduplicate requests on the same machine

Returns:

a serialized RequestLock transition

createTryLockTransition

public static byte[] createTryLockTransition(java.lang.String lock,
                                             java.lang.String requester,
                                             java.lang.String uniqueHash)

This creates a serialized TryLock transition.

Parameters:

lock - the lock name

requester - the requester of the lock

uniqueHash - the unique hash to deduplicate requests on the same machine

Returns:

a serialized RequestLock transition

createReleaseLockTransition

public static byte[] createReleaseLockTransition(java.lang.String lock,
                                                 java.lang.String requester,
                                                 java.lang.String uniqueHash)

This creates a serialized ReleaseLock transition.

Parameters:

lock - the lock name

requester - the requester of the lock

uniqueHash - the unique hash to deduplicate requests on the same machine

Returns:

a serialized ReleaseLock transition

createGroupedTransition

public static byte[] createGroupedTransition(byte[]... transitions)

Creates a grouped transition, which executes several transitions atomically.

Parameters:

transitions - the transitions (serialized) to group

Returns:

a grouped transition

createSetValueTransitionWithOwner

public static byte[] createSetValueTransitionWithOwner(java.lang.String key,
                                                       byte[] value,
                                                       java.lang.String owner)

This creates a serialized SetValue transition that will set an entry in the values map, with an "owner" who is responsible for the value, which will be automatically cleaned up when the owner disconnects from the cluster.

Parameters:

key - the key to set

value - the value, as a raw byte array

owner - the owner of this key-value pair

Returns:

a serialized SetValue transition

createSetValueTransition

public static byte[] createSetValueTransition(java.lang.String key,
                                              byte[] value)

This creates a serialized SetValue transition that will set an entry in the values map.

Parameters:

key - the key to set

value - the value, as a raw byte array

Returns:

a serialized SetValue transition

createRemoveValueTransition

public static byte[] createRemoveValueTransition(java.lang.String key)

This creates a serialized RemoveValue transition that will delete an entry in the map, if it's currently present.

Parameters:

key - the key to remove

Returns:

a serialized RemoveValue transition

createClearTransition

public static byte[] createClearTransition(java.lang.String owner)

This creates a serialized ClearTransient transition.

Parameters:

owner - the owner we should clear transient values for.

Returns:

a serialized ClearTransient transition