alluxio.master.metastore.caching

Class Cache<K,V>

java.lang.Object

alluxio.master.metastore.caching.Cache<K,V>

Type Parameters:

K - the cache key type

V - the cache value type

All Implemented Interfaces:

Closeable, AutoCloseable

@ThreadSafe
public abstract class Cache<K,V>
extends Object
implements Closeable

Base class for write-back caches which asynchronously evict entries to backing stores. The cache uses water mark based eviction. A dedicated thread waits for the cache to reach its high water mark, then evicts entries until the cache size reaches the low water mark. All backing store write operations are performed asynchronously in the eviction thread, unless the cache hits maximum capacity. At maximum capacity, methods interact synchronously with the backing store. For best performance, maximum capacity should never be reached. This requires that the eviction thread can keep up cache writes. Cache hit reads are served without any locking. Writes and cache miss reads take locks on their cache key. This class leverages the entry-level locks of ConcurrentHashMap to synchronize operations on the same key.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected class	Cache.Entry

Constructor Summary

Constructors

Constructor and Description
Cache(CacheConfiguration conf, String name, MetricKey evictionsKey, MetricKey hitsKey, MetricKey loadTimesKey, MetricKey missesKey, MetricKey sizeKey)

Method Summary

Modifier and Type	Method and Description
void	clear() Clears all entries from the map.
void	close()
void	flush() Flushes all data to the backing store.
protected abstract void	flushEntries(List<Cache.Entry> candidates) Attempts to flush the given entries to the backing store.
Optional<V>	get(K key)
Optional<V>	get(K key, ReadOption option) Retrieves a value from the cache, loading it from the backing store if necessary.
protected Map<K,Cache.Entry>	getCacheMap()
protected abstract Optional<V>	load(K key) Loads a key from the backing store.
protected void	onCacheRemove(K key) Callback triggered when a key is removed from the cache.
protected void	onCacheUpdate(K key, V value) Callback triggered when an update is made to a key/value pair in the cache.
protected void	onPut(K key, V existingValue, V value, boolean isNewKey) Callback triggered whenever a new key/value pair is added by put(key, value).
protected void	onRemove(K key) Callback triggered whenever a key is removed by remove(key).
void	put(K key, V value) Writes a key/value pair to the cache.
void	putNewEntry(K key, V value) Writes a key/value pair to the cache.
void	remove(K key) Removes a key from the cache.
protected abstract void	removeFromBackingStore(K key) Removes a key from the backing store.
protected abstract void	writeToBackingStore(K key, V value) Writes a key/value pair to the backing store.

Methods inherited from class java.lang.Object

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

Constructor Detail

Cache

public Cache(CacheConfiguration conf,
             String name,
             MetricKey evictionsKey,
             MetricKey hitsKey,
             MetricKey loadTimesKey,
             MetricKey missesKey,
             MetricKey sizeKey)

Parameters:

conf - cache configuration

name - a name for the cache

evictionsKey - the cache evictions metric key

hitsKey - the cache hits metrics key

loadTimesKey - the load times metrics key

missesKey - the misses metrics key

sizeKey - the size metrics key

Method Detail

get

public Optional<V> get(K key,
                       ReadOption option)

Retrieves a value from the cache, loading it from the backing store if necessary. If the value needs to be loaded, concurrent calls to get(key) will block while waiting for the first call to finish loading the value. If option.shouldSkipCache() is true, then the value loaded from the backing store will not be cached and the eviction thread will not be woken up.

Parameters:

key - the key to get the value for

option - the read options

Returns:

the value, or empty if the key doesn't exist in the cache or in the backing store

get

public Optional<V> get(K key)

Parameters:

key - the key to get the value for

Returns:

the result of get(Object, ReadOption) with default option

putNewEntry

public void putNewEntry(K key,
                        V value)

Writes a key/value pair to the cache. This method is similar to put(Object, Object), but with an added information that the entry is new.

Parameters:

key - the key

value - the value

put

public void put(K key,
                V value)

Writes a key/value pair to the cache. If it is known that the entry is new, prefer putNewEntry(Object, Object).

Parameters:

key - the key

value - the value

remove

public void remove(K key)

Removes a key from the cache. The key is not immediately removed from the backing store. Instead, we set the entry's value to null to indicate to the eviction thread that to evict the entry, it must first remove the key from the backing store. However, if the cache is full we must synchronously write to the backing store instead.

Parameters:

key - the key to remove

flush

public void flush()
           throws InterruptedException

Flushes all data to the backing store.

Throws:

InterruptedException

clear

public void clear()

Clears all entries from the map. This is not threadsafe, and requires external synchronization to prevent concurrent modifications to the cache.

close

public void close()

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

getCacheMap

protected Map<K,Cache.Entry> getCacheMap()

onCacheUpdate

protected void onCacheUpdate(K key,
                             @Nullable
                             V value)

Callback triggered when an update is made to a key/value pair in the cache. For removals, value will be null.

Parameters:

key - the updated key

value - the updated value, or null if the key is being removed

onCacheRemove

protected void onCacheRemove(K key)

Callback triggered when a key is removed from the cache. This may be used in conjunction with onCacheUpdate to keep track of all changes to the cache.

Parameters:

key - the removed key

onPut

protected void onPut(K key,
                     @Nullable
                     V existingValue,
                     V value,
                     boolean isNewKey)

Callback triggered whenever a new key/value pair is added by put(key, value).

Parameters:

key - the added key

existingValue - the current value if exists, otherwise null

value - the added value

isNewKey - a user input boolean indicates if the key is a new key or not

onRemove

protected void onRemove(K key)

Callback triggered whenever a key is removed by remove(key).

Parameters:

key - the removed key

load

protected abstract Optional<V> load(K key)

Loads a key from the backing store.

Parameters:

key - the key to load

Returns:

the value for the key, or empty if the key doesn't exist in the backing store

writeToBackingStore

protected abstract void writeToBackingStore(K key,
                                            V value)

Writes a key/value pair to the backing store.

Parameters:

key - the key

value - the value

removeFromBackingStore

protected abstract void removeFromBackingStore(K key)

Removes a key from the backing store.

Parameters:

key - the key

flushEntries

protected abstract void flushEntries(List<Cache.Entry> candidates)

Attempts to flush the given entries to the backing store. The subclass is responsible for setting each candidate's mDirty field to false on success.

Parameters:

candidates - the candidate entries to flush