de.caff.generics

Class LeastRecentlyUsedCache<K,V>

java.lang.Object

de.caff.generics.LeastRecentlyUsedCache<K,V>

Type Parameters:

K - key type of map, as always keys are expected to not mutate during the lifetime of this object

V - value type of map

Direct Known Subclasses:

RecreatingLeastRecentlyUsedCache

public class LeastRecentlyUsedCache<K,V>
extends java.lang.Object

A map which implements a least recently used cache.

Usage here means that the latest value which is either add by put(Object, Object) or retrieved by get(Object) is the least recently used one.

The implemented map basically keeps only soft references to its values, but not its keys. Therefore keys and values must be of different types, otherwise store values will not be freed, ever.

This does deliberately not implement Map as that has too many methods mot making much sense here.

Attention: null values are not allowed for this map, as null is used to mark valeus which are removed by the garbage collector

See RecreatingLeastRecentlyUsedCache for a way to include an automatic recreation of garbage-collected values.

Since:

May 10, 2021

Author:

Rammi

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.Map<K,java.lang.ref.SoftReference<V>>	map

Constructor Summary

Constructors

Constructor and Description
LeastRecentlyUsedCache(int leastRecentLimit) Constructor.

Method Summary

Modifier and Type	Method and Description
void	cleanup() Remove all key-value pairs which are no longer available.
void	clear() Remove all entries from this cache.
V	computeIfAbsent(K key, java.util.function.Function<? super K,? extends V> creator) Get the value for the given key, or compute a new value and add it for the given key.
V	get(K key) Get the value for the given key.
int	getLeastRecentCacheDepth() Get the maximum number of values kept in the LRU cache.
java.util.List<V>	getLeastRecentlyUsed() Get the values in the LRU cache in order.
int	getNumGarbageCollected() Get the number of times an entry was garbage collected.
int	getNumHits() Get the number of times a cached value was successfully retrieved.
int	getNumMisses() Get the number of times an entry was not found in the cache.
boolean	isEmpty() Is this mapping empty?
java.util.Set<K>	keys() Get the keys currently valid in this cache.
void	put(K key, V value) Put a new key-value pair into this cache.
V	remove(K key) Remove a key-value pair from this cache.
int	size() Get the size of this mapping.

Methods inherited from class java.lang.Object

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

Field Detail

map

@NotNull
protected final java.util.Map<K,java.lang.ref.SoftReference<V>> map

Constructor Detail

LeastRecentlyUsedCache

public LeastRecentlyUsedCache(int leastRecentLimit)

Constructor. This just keeps up to leastRecentLimit values cached. It does not define a recreator, therefore values removed by garbage collection are gone, and have to be recreated and readded to this maps elsewhere.

Parameters:

leastRecentLimit - maximal number of cached values, non-negative

Method Detail

cleanup

public void cleanup()

Remove all key-value pairs which are no longer available.

size

public int size()

Get the size of this mapping. This implicitly calls cleanup() before returning the size, but as garbage collection can happen any time users should not depend too much on the returned value.

Returns:

number of currently cached values

getLeastRecentCacheDepth

public int getLeastRecentCacheDepth()

Get the maximum number of values kept in the LRU cache. This cache may keep a greater number of values as long as there is enough memory.

Returns:

cache limit

isEmpty

public boolean isEmpty()

Is this mapping empty? This implicitly calls cleanup() before returning the answer but as garbage collection can happen any time users should not depend too much on the returned value.

Returns:

number of currently cached values

get

@Nullable
public V get(@NotNull
                       K key)

Get the value for the given key.

Parameters:

key - key associated with the requested value

Returns:

null when the required value was never added to this cache or when it was garbage collected in the meantime, otherwise the cached object associated with the given key

put

public void put(K key,
                @NotNull
                V value)

Put a new key-value pair into this cache.

Parameters:

key - key for retrieving the cached value

value - value to cache

computeIfAbsent

public V computeIfAbsent(K key,
                         @NotNull
                         java.util.function.Function<? super K,? extends V> creator)

Get the value for the given key, or compute a new value and add it for the given key.

Parameters:

key - key of requested value

creator - creator for new value if key is (no longer) present

Returns:

stored or newly created vale, null only if creator returns null

keys

@NotNull
public java.util.Set<K> keys()

Get the keys currently valid in this cache. This calls cleanup() before the keys are returned. This is just a snapshot, don't depend too much on the returned keys.

Returns:

set of currently valid keys

remove

@Nullable
public V remove(K key)

Remove a key-value pair from this cache.

Parameters:

key - key of the key-value pair

Returns:

removed object if it was still cached, or null if the object was either never cached at all or has been garbage collected

clear

public void clear()

Remove all entries from this cache.

getLeastRecentlyUsed

@NotNull
public java.util.List<V> getLeastRecentlyUsed()

Get the values in the LRU cache in order.

Returns:

values in the LRU cache, most least recently used item first

getNumHits

public int getNumHits()

Get the number of times a cached value was successfully retrieved.

Returns:

number of cache hits

getNumGarbageCollected

public int getNumGarbageCollected()

Get the number of times an entry was garbage collected.

Returns:

number of garbage collected entries

getNumMisses

public int getNumMisses()

Get the number of times an entry was not found in the cache.

Returns:

number of cache misses