ai.eloquent.raft

Class RaftBackedCache<V>

java.lang.Object

ai.eloquent.raft.RaftBackedCache<V>

All Implemented Interfaces:

java.lang.AutoCloseable, java.lang.Iterable<java.util.Map.Entry<java.lang.String,V>>

public abstract class RaftBackedCache<V>
extends java.lang.Object
implements java.lang.Iterable<java.util.Map.Entry<java.lang.String,V>>, java.lang.AutoCloseable

A cache that keeps values in Raft, but saves them to a given persistence store when they have been unmodified in Raft for too long.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	RaftBackedCache.ChangeListener<V> This holds a locally registered callback that will be called whenever the cache changes.

Field Summary

Fields

Modifier and Type	Field and Description
Theseus	raft The implementing Raft for the cache.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	RaftBackedCache(Theseus raft, java.time.Duration idleDuration, java.time.Duration elementLifetime) Create a Raft backed cache with the default Raft implementation.
protected	RaftBackedCache(Theseus raft, java.time.Duration idleDuration, java.time.Duration elementLifetime, int maxSizeBytes) Create a Raft backed cache with a particular Raft implementation.

Method Summary

Modifier and Type	Method and Description
void	addChangeListener(RaftBackedCache.ChangeListener<V> changeListener)
void	addChangeListener(RaftBackedCache.ChangeListener<V> changeListener, java.lang.Object owner) This registers a listener that will be called whenever the key-value store changes.
java.util.concurrent.CompletableFuture<java.lang.Void>	allOutstandingEvictionsFuture() This creates a new CompletableFuture for all the currently outstanding eviction tasks.
java.util.concurrent.CompletableFuture<java.lang.Boolean>	clearCache() This iterates through all the elements in the Raft backed cache and evicts them, using only a single Raft commit to do it.
void	close() This cleans up the eviction timer.
abstract java.util.Optional<V>	deserialize(byte[] serialized) Read an object in our cache, written with serialize(Object), into a value type.
java.util.concurrent.CompletableFuture<java.lang.Boolean>	evictWithoutSaving(java.lang.String key) Remove an element in Raft.
java.util.Optional<V>	get(java.lang.String key) Get an element from the cache.
java.util.Optional<V>	getIfPresent(java.lang.String key) Get an element from the cache, if it's present in the cache itself.
java.util.Iterator<java.util.Map.Entry<java.lang.String,V>>	iterator()
protected void	onSet(V object) Run every time an object is set in the cache.
abstract void	persist(java.lang.String key, V value, boolean async) Evict an element from our cache.
protected abstract java.lang.String	prefix() The raft prefix to use on get(String) and put(String, Object, boolean) to translate from our local namespace to Raft's global namespace
java.util.concurrent.CompletableFuture<java.lang.Boolean>	put(java.lang.String key, V value, boolean persist) Set an element in Raft.
void	removeChangeListener(RaftBackedCache.ChangeListener changeListener) This registers a listener that will be called whenever the key-value store changes.
abstract java.util.Optional<V>	restore(java.lang.String key) Get a value from wherever it was evicted to, if we can.
abstract byte[]	serialize(V object) Serialize an object of our value type into a byte array.
java.util.concurrent.CompletableFuture<java.lang.Boolean>	withElementAsync(java.lang.String key, java.util.function.BiFunction<V,java.util.function.Consumer<V>,V> mutator)
java.util.concurrent.CompletableFuture<java.lang.Boolean>	withElementAsync(java.lang.String key, java.util.function.BiFunction<V,java.util.function.Consumer<V>,V> mutator, java.util.function.Supplier<V> createNew, boolean unlocked) Perform a computation on the given element.
java.util.concurrent.CompletableFuture<java.lang.Boolean>	withElementAsync(java.lang.String key, java.util.function.Function<V,V> mutator)
java.util.concurrent.CompletableFuture<java.lang.Boolean>	withElementAsync(java.lang.String key, java.util.function.Function<V,V> mutator, java.util.function.Supplier<V> createNew)
java.util.concurrent.CompletableFuture<java.lang.Boolean>	withElementAsync(java.lang.String key, java.util.function.Function<V,V> mutator, java.util.function.Supplier<V> createNew, boolean unlocked)

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Field Detail

raft

public final Theseus raft

The implementing Raft for the cache.

Constructor Detail

RaftBackedCache

protected RaftBackedCache(Theseus raft,
                          java.time.Duration idleDuration,
                          java.time.Duration elementLifetime,
                          int maxSizeBytes)

Create a Raft backed cache with a particular Raft implementation.

RaftBackedCache

protected RaftBackedCache(Theseus raft,
                          java.time.Duration idleDuration,
                          java.time.Duration elementLifetime)

Create a Raft backed cache with the default Raft implementation.

Method Detail

onSet

protected void onSet(V object)

Run every time an object is set in the cache.

Parameters:

object - The object we're setting in the cache.

allOutstandingEvictionsFuture

public java.util.concurrent.CompletableFuture<java.lang.Void> allOutstandingEvictionsFuture()

This creates a new CompletableFuture for all the currently outstanding eviction tasks.

Returns:

a NEW CompletableFuture for all the outstanding eviction tasks. If none outstanding, returns a completed future.

close

public void close()

This cleans up the eviction timer. It also

Specified by:

close in interface java.lang.AutoCloseable

prefix

protected abstract java.lang.String prefix()

The raft prefix to use on get(String) and put(String, Object, boolean) to translate from our local namespace to Raft's global namespace

serialize

public abstract byte[] serialize(V object)

Serialize an object of our value type into a byte array. We need to be able to do this so that we can store it in the Raft state machine. This must be able to be reread with deserialize(byte[]).

Parameters:

object - The object we are serializing.

Returns:

A byte[] representation of the object.

See Also:

deserialize(byte[])

deserialize

public abstract java.util.Optional<V> deserialize(byte[] serialized)

Read an object in our cache, written with serialize(Object), into a value type.

Parameters:

serialized - The serialized blob we are reading.

Returns:

The value corresponding to the protocol buffer.

See Also:

serialize(Object)

restore

public abstract java.util.Optional<V> restore(java.lang.String key)

Get a value from wherever it was evicted to, if we can. This is the inverse of persist(String, Object, boolean).

Parameters:

key - The key of the element we're creating / retrieving.

Returns:

The value of the element we've created / retrieved.

See Also:

persist(String, Object, boolean)

persist

public abstract void persist(java.lang.String key,
                             V value,
                             boolean async)

Evict an element from our cache. This can either actually throw it away, or save it to a persistence store. If you chose the latter, make sure to have restore(String) first try to retrieve the element from this persistence store.

Parameters:

key - The key we are evicting.

value - The value we are evicting.

async - If true, the save is allowed to be asynchronous. This is often the case where, e.g., we're saving on a creation when we should not be blocking the main thread.

clearCache

public java.util.concurrent.CompletableFuture<java.lang.Boolean> clearCache()

This iterates through all the elements in the Raft backed cache and evicts them, using only a single Raft commit to do it.

addChangeListener

public void addChangeListener(RaftBackedCache.ChangeListener<V> changeListener,
                              @Nullable
                              java.lang.Object owner)

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

Parameters:

changeListener - the listener to register

owner - the owner of the change listener. This is a failsafe to make sure we remove the listener when the owner dies, but is not required.

addChangeListener

public void addChangeListener(RaftBackedCache.ChangeListener<V> changeListener)

See Also:

addChangeListener(ChangeListener, Object)

removeChangeListener

public void removeChangeListener(RaftBackedCache.ChangeListener changeListener)

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

Parameters:

changeListener - the listener to register

withElementAsync

public java.util.concurrent.CompletableFuture<java.lang.Boolean> withElementAsync(java.lang.String key,
                                                                                  java.util.function.BiFunction<V,java.util.function.Consumer<V>,V> mutator,
                                                                                  @Nullable
                                                                                  java.util.function.Supplier<V> createNew,
                                                                                  boolean unlocked)

Perform a computation on the given element. The result of the mutation is then saved into raft, if there was any change. Note that we can always return the input element if we do not want to save anything back to Raft. If the element does not exist, we will call restore(String) to ensure that it is created.

Parameters:

key - The key of the element we're computing on.

mutator - The function to call on the value for the given key. This takes 2 arguments: the input item, and a function that can be called to sync intermediate states. It should return the final state to save. Note that saving intermediate states is done while this object still holds the lock. So, other processes can only access the result read-only,

createNew - An optional method for creating a brand new object of the relevant type - only gets called if element cannot be retrieved from storage

unlocked - If true, we are not locking the underlying Raft call.

withElementAsync

public java.util.concurrent.CompletableFuture<java.lang.Boolean> withElementAsync(java.lang.String key,
                                                                                  java.util.function.Function<V,V> mutator,
                                                                                  @Nullable
                                                                                  java.util.function.Supplier<V> createNew,
                                                                                  boolean unlocked)

See Also:

withElementAsync(String, BiFunction, Supplier, boolean)

withElementAsync

public java.util.concurrent.CompletableFuture<java.lang.Boolean> withElementAsync(java.lang.String key,
                                                                                  java.util.function.Function<V,V> mutator,
                                                                                  java.util.function.Supplier<V> createNew)

See Also:

withElementAsync(String, Function, Supplier)

withElementAsync

public java.util.concurrent.CompletableFuture<java.lang.Boolean> withElementAsync(java.lang.String key,
                                                                                  java.util.function.Function<V,V> mutator)

See Also:

withElementAsync(String, Function, Supplier)

withElementAsync

public java.util.concurrent.CompletableFuture<java.lang.Boolean> withElementAsync(java.lang.String key,
                                                                                  java.util.function.BiFunction<V,java.util.function.Consumer<V>,V> mutator)

See Also:

withElementAsync(String, BiFunction, Supplier, boolean)

get

public java.util.Optional<V> get(java.lang.String key)

Get an element from the cache.

Parameters:

key - The key of the element to get

Returns:

The element we are getting, if present.

getIfPresent

public java.util.Optional<V> getIfPresent(java.lang.String key)

Get an element from the cache, if it's present in the cache itself. This will not try to get the element from the persistent store.

Parameters:

key - The key of the element to get

Returns:

The element we are getting, if present.

put

public java.util.concurrent.CompletableFuture<java.lang.Boolean> put(java.lang.String key,
                                                                     V value,
                                                                     boolean persist)

Set an element in Raft. This is really just an alias for Theseus.setElementAsync(String, byte[], boolean, Duration) with permanent set to true and a 5 second timeout.

evictWithoutSaving

public java.util.concurrent.CompletableFuture<java.lang.Boolean> evictWithoutSaving(java.lang.String key)

Remove an element in Raft. This is really just an alias for Theseus.removeElementAsync(String, Duration).

iterator

@Nonnull
public java.util.Iterator<java.util.Map.Entry<java.lang.String,V>> iterator()

Specified by:

iterator in interface java.lang.Iterable<java.util.Map.Entry<java.lang.String,V>>