org.agrona.collections

Class Long2ObjectCache<V>

java.lang.Object

org.agrona.collections.Long2ObjectCache<V>

Type Parameters:

V - type of values stored in the Map

All Implemented Interfaces:

java.io.Serializable, java.util.Map<java.lang.Long,V>

public class Long2ObjectCache<V>
extends java.lang.Object
implements java.util.Map<java.lang.Long,V>, java.io.Serializable

A cache implementation specialised for long keys using open addressing to probe a set of fixed size.

The eviction strategy is to remove the oldest in a set if the key is not found, or if found then that item. The newly inserted item becomes the youngest in the set. Sets are evicted on a first in, first out, manner unless replacing a matching key.

A good set size would be in the range of 2 to 16 so that the references/keys can fit in a cache-line (assuming references are 32 bit references and 64 byte cache lines, YMMV). A linear search within a cache line is much much less costly than a cache-miss to another line.

Null values are not supported by this cache.

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	Long2ObjectCache.EntryIterator
class	Long2ObjectCache.EntrySet
class	Long2ObjectCache.KeyIterator
class	Long2ObjectCache.KeySet
class	Long2ObjectCache.ValueCollection
class	Long2ObjectCache.ValueIterator

Nested classes/interfaces inherited from interface java.util.Map

java.util.Map.Entry<K,V>

Constructor Summary

Constructors

Constructor and Description
Long2ObjectCache(int numSets, int setSize, java.util.function.Consumer<V> evictionConsumer)

Method Summary

Modifier and Type	Method and Description
long	cacheHits() The number of times a cache hit has occurred on the get(long) method.
long	cacheMisses() The number of times a cache miss has occurred on the get(long) method.
long	cachePuts() The number of items that have been put in the cache.
int	capacity() Get the total capacity for the map to which the load factor will be a fraction of.
void	clear() Clear down all items in the cache.
V	computeIfAbsent(long key, java.util.function.LongFunction<? extends V> mappingFunction) Get a value for a given key, or if it does ot exist then default the value via a LongFunction and put it in the cache.
boolean	containsKey(long key) Overloaded version of Map.containsKey(Object) that takes a primitive long key.
boolean	containsKey(java.lang.Object key)
boolean	containsValue(java.lang.Object value)
Long2ObjectCache.EntrySet	entrySet()
boolean	equals(java.lang.Object o)
V	get(long key) Overloaded version of Map.get(Object) that takes a primitive long key.
V	get(java.lang.Object key)
int	hashCode()
boolean	isEmpty()
Long2ObjectCache.KeySet	keySet()
V	put(long key, V value) Overloaded version of Map.put(Object, Object) that takes a primitive long key.
V	put(java.lang.Long key, V value)
void	putAll(java.util.Map<? extends java.lang.Long,? extends V> map)
V	remove(long key) Overloaded version of Map.remove(Object) that takes a primitive long key.
V	remove(java.lang.Object key)
void	resetCounters() Reset the cache statistics counters to zero.
int	size()
java.lang.String	toString()
Long2ObjectCache.ValueCollection	values()

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.Map

compute, computeIfAbsent, computeIfPresent, forEach, getOrDefault, merge, putIfAbsent, remove, replace, replace, replaceAll

Constructor Detail

Long2ObjectCache

public Long2ObjectCache(int numSets,
                        int setSize,
                        java.util.function.Consumer<V> evictionConsumer)

Method Detail

cacheHits

public long cacheHits()

The number of times a cache hit has occurred on the get(long) method.

Returns:

the number of times a cache hit has occurred on the get(long) method.

cacheMisses

public long cacheMisses()

The number of times a cache miss has occurred on the get(long) method.

Returns:

the number of times a cache miss has occurred on the get(long) method.

cachePuts

public long cachePuts()

The number of items that have been put in the cache.

Returns:

number of items that have been put in the cache.

resetCounters

public void resetCounters()

Reset the cache statistics counters to zero.

capacity

public int capacity()

Get the total capacity for the map to which the load factor will be a fraction of.

Returns:

the total capacity for the map.

size

public int size()

Specified by:

size in interface java.util.Map<java.lang.Long,V>

isEmpty

public boolean isEmpty()

Specified by:

isEmpty in interface java.util.Map<java.lang.Long,V>

containsKey

public boolean containsKey(java.lang.Object key)

Specified by:

containsKey in interface java.util.Map<java.lang.Long,V>

containsKey

public boolean containsKey(long key)

Overloaded version of Map.containsKey(Object) that takes a primitive long key.

Parameters:

key - for indexing the Map

Returns:

true if the key is found otherwise false.

containsValue

public boolean containsValue(java.lang.Object value)

Specified by:

containsValue in interface java.util.Map<java.lang.Long,V>

get

public V get(java.lang.Object key)

Specified by:

get in interface java.util.Map<java.lang.Long,V>

get

public V get(long key)

Overloaded version of Map.get(Object) that takes a primitive long key.

Parameters:

key - for indexing the Map

Returns:

the value if found otherwise null

computeIfAbsent

public V computeIfAbsent(long key,
                         java.util.function.LongFunction<? extends V> mappingFunction)

Get a value for a given key, or if it does ot exist then default the value via a LongFunction and put it in the cache.

Primitive specialized version of Map.computeIfAbsent(K, java.util.function.Function<? super K, ? extends V>).

Parameters:

key - to search on.

mappingFunction - to provide a value if the get returns null.

Returns:

the value if found otherwise the default.

put

public V put(java.lang.Long key,
             V value)

Specified by:

put in interface java.util.Map<java.lang.Long,V>

put

public V put(long key,
             V value)

Overloaded version of Map.put(Object, Object) that takes a primitive long key.

Parameters:

key - for indexing the Map

value - to be inserted in the Map

Returns:

always null (as per JCache API, as opposed to Map)

remove

public V remove(java.lang.Object key)

Specified by:

remove in interface java.util.Map<java.lang.Long,V>

remove

public V remove(long key)

Overloaded version of Map.remove(Object) that takes a primitive long key.

Parameters:

key - for indexing the Map

Returns:

the value if found otherwise null

clear

public void clear()

Clear down all items in the cache.

If an exception occurs during the eviction function callback then clear may need to be called again to complete.

If an exception occurs the cache should only be used when size() reports zero.

Specified by:

clear in interface java.util.Map<java.lang.Long,V>

putAll

public void putAll(java.util.Map<? extends java.lang.Long,? extends V> map)

Specified by:

putAll in interface java.util.Map<java.lang.Long,V>

keySet

public Long2ObjectCache.KeySet keySet()

Specified by:

keySet in interface java.util.Map<java.lang.Long,V>

values

public Long2ObjectCache.ValueCollection values()

Specified by:

values in interface java.util.Map<java.lang.Long,V>

entrySet

public Long2ObjectCache.EntrySet entrySet()

Specified by:

entrySet in interface java.util.Map<java.lang.Long,V>

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

equals

public boolean equals(java.lang.Object o)

Specified by:

equals in interface java.util.Map<java.lang.Long,V>

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Specified by:

hashCode in interface java.util.Map<java.lang.Long,V>

Overrides:

hashCode in class java.lang.Object