Class Long2ObjectCache<V>
- java.lang.Object
-
- org.agrona.collections.Long2ObjectCache<V>
-
- Type Parameters:
V
- type of values stored in theMap
- All Implemented Interfaces:
java.util.Map<java.lang.Long,V>
public class Long2ObjectCache<V> extends java.lang.Object implements java.util.Map<java.lang.Long,V>
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 less costly than a cache-miss to another line.
Null values are not supported by this cache.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description (package private) class
Long2ObjectCache.AbstractIterator<T>
Base iterator implementation that contains basic logic of traversing the element in the backing array.class
Long2ObjectCache.EntryIterator
Iterator over entries which supports access to unboxed keys viaLong2ObjectCache.EntryIterator.getLongKey()
.class
Long2ObjectCache.EntrySet
Set of entries which supports cached iterator to avoid allocation.class
Long2ObjectCache.KeyIterator
Iterator over keys which supports access to unboxed keys viaLong2ObjectCache.KeyIterator.nextLong()
.class
Long2ObjectCache.KeySet
A key set implementation which supports cached iterator to avoid allocation.class
Long2ObjectCache.ValueCollection
Collection of values which supports cached iterator to avoid allocation.class
Long2ObjectCache.ValueIterator
An iterator over values.
-
Field Summary
Fields Modifier and Type Field Description private long
cacheHits
private long
cacheMisses
private long
cachePuts
private int
capacity
private Long2ObjectCache.EntrySet
entrySet
private java.util.function.Consumer<V>
evictionConsumer
private long[]
keys
private Long2ObjectCache.KeySet
keySet
private int
mask
private int
setSize
private int
setSizeShift
private int
size
private Long2ObjectCache.ValueCollection
valueCollection
private java.lang.Object[]
values
-
Constructor Summary
Constructors Constructor Description Long2ObjectCache(int numSets, int setSize, java.util.function.Consumer<V> evictionConsumer)
Constructs cache with provided configuration.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description long
cacheHits()
The number of times a cache hit has occurred on theget(long)
method.long
cacheMisses()
The number of times a cache miss has occurred on theget(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
compute(long key, LongObjectToObjectFunction<? super V,? extends V> remappingFunction)
Attempts to compute a mapping for the specified key and its current mapped value (ornull
if there is no current mapping).V
compute(java.lang.Long key, java.util.function.BiFunction<? super java.lang.Long,? super V,? extends V> remappingFunction)
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 aLongFunction
and put it in the cache.V
computeIfAbsent(java.lang.Long key, java.util.function.Function<? super java.lang.Long,? extends V> mappingFunction)
V
computeIfPresent(long key, LongObjectToObjectFunction<? super V,? extends V> remappingFunction)
If the value for the specified key is present attempts to compute a new mapping given the key and its current mapped value.V
computeIfPresent(java.lang.Long key, java.util.function.BiFunction<? super java.lang.Long,? super V,? extends V> remappingFunction)
boolean
containsKey(long key)
Overloaded version ofMap.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)
void
forEach(java.util.function.BiConsumer<? super java.lang.Long,? super V> action)
void
forEachLong(LongObjConsumer<? super V> consumer)
Implementation of theforEach(BiConsumer)
that avoids boxing of keys.V
get(long key)
Overloaded version ofMap.get(Object)
that takes a primitive long key.V
get(java.lang.Object key)
V
getOrDefault(long key, V defaultValue)
Returns the value to which the specified key is mapped, or defaultValue if this map contains no mapping for the key.int
hashCode()
boolean
isEmpty()
Long2ObjectCache.KeySet
keySet()
V
merge(long key, V value, java.util.function.BiFunction<? super V,? super V,? extends V> remappingFunction)
If the specified key is not already associated with a value or is associated with null, associates it with the given non-null value.V
merge(java.lang.Long key, V value, java.util.function.BiFunction<? super V,? super V,? extends V> remappingFunction)
V
put(long key, V value)
Overloaded version ofMap.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)
void
putAll(Long2ObjectCache<? extends V> map)
Put all values from the given map longo this one without allocation.V
putIfAbsent(long key, V value)
If the specified key is not already associated with a value (or is mapped tonull
) associates it with the given value and returnsnull
, else returns the current value.V
putIfAbsent(java.lang.Long key, V value)
V
remove(long key)
Overloaded version ofMap.remove(Object)
that takes a primitive long key.boolean
remove(long key, V value)
Removes the entry for the specified key only if it is currently mapped to the specified value.V
remove(java.lang.Object key)
boolean
remove(java.lang.Object key, java.lang.Object value)
V
replace(long key, V value)
Replaces the entry for the specified key only if it is currently mapped to some value.boolean
replace(long key, V oldValue, V newValue)
Replaces the entry for the specified key only if currently mapped to the specified value.V
replace(java.lang.Long key, V value)
boolean
replace(java.lang.Long key, V oldValue, V newValue)
void
replaceAll(java.util.function.BiFunction<? super java.lang.Long,? super V,? extends V> function)
void
replaceAllLong(LongObjectToObjectFunction<? super V,? extends V> function)
Replaces each entry's value with the result of invoking the given function on that entry until all entries have been processed or the function throws an exception.void
resetCounters()
Reset the cache statistics counters to zero.private void
shuffleDown(int setBeginIndex)
private void
shuffleUp(int fromIndex, int toIndex)
int
size()
java.lang.String
toString()
Long2ObjectCache.ValueCollection
values()
-
-
-
Field Detail
-
cachePuts
private long cachePuts
-
cacheHits
private long cacheHits
-
cacheMisses
private long cacheMisses
-
size
private int size
-
capacity
private final int capacity
-
setSize
private final int setSize
-
setSizeShift
private final int setSizeShift
-
mask
private final int mask
-
keys
private final long[] keys
-
values
private final java.lang.Object[] values
-
evictionConsumer
private final java.util.function.Consumer<V> evictionConsumer
-
valueCollection
private Long2ObjectCache.ValueCollection valueCollection
-
keySet
private Long2ObjectCache.KeySet keySet
-
entrySet
private Long2ObjectCache.EntrySet entrySet
-
-
Constructor Detail
-
Long2ObjectCache
public Long2ObjectCache(int numSets, int setSize, java.util.function.Consumer<V> evictionConsumer)
Constructs cache with provided configuration.- Parameters:
numSets
- number of sets, must be power or two.setSize
- size of a single set, must be power or two.evictionConsumer
- consumer to be notified when entry is being evicted from the cache.
-
-
Method Detail
-
cacheHits
public long cacheHits()
The number of times a cache hit has occurred on theget(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 theget(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 interfacejava.util.Map<java.lang.Long,V>
-
isEmpty
public boolean isEmpty()
- Specified by:
isEmpty
in interfacejava.util.Map<java.lang.Long,V>
-
containsKey
public boolean containsKey(java.lang.Object key)
- Specified by:
containsKey
in interfacejava.util.Map<java.lang.Long,V>
-
containsKey
public boolean containsKey(long key)
Overloaded version ofMap.containsKey(Object)
that takes a primitive long key.- Parameters:
key
- for indexing theMap
- Returns:
- true if the key is found otherwise false.
-
containsValue
public boolean containsValue(java.lang.Object value)
- Specified by:
containsValue
in interfacejava.util.Map<java.lang.Long,V>
-
get
public V get(java.lang.Object key)
- Specified by:
get
in interfacejava.util.Map<java.lang.Long,V>
-
get
public V get(long key)
Overloaded version ofMap.get(Object)
that takes a primitive long key.- Parameters:
key
- for indexing theMap
- Returns:
- the value if found otherwise null
-
getOrDefault
public V getOrDefault(long key, V defaultValue)
Returns the value to which the specified key is mapped, or defaultValue if this map contains no mapping for the key.- Parameters:
key
- whose associated value is to be returned.defaultValue
- the default mapping of the key.- Returns:
- the value to which the specified key is mapped, or
defaultValue
if this map contains no mapping for the key.
-
forEach
public void forEach(java.util.function.BiConsumer<? super java.lang.Long,? super V> action)
- Specified by:
forEach
in interfacejava.util.Map<java.lang.Long,V>
-
forEachLong
public void forEachLong(LongObjConsumer<? super V> consumer)
Implementation of theforEach(BiConsumer)
that avoids boxing of keys.- Parameters:
consumer
- to be called for each key/value pair.
-
computeIfAbsent
public V computeIfAbsent(java.lang.Long key, java.util.function.Function<? super java.lang.Long,? extends V> mappingFunction)
- Specified by:
computeIfAbsent
in interfacejava.util.Map<java.lang.Long,V>
-
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 aLongFunction
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.
-
computeIfPresent
public V computeIfPresent(java.lang.Long key, java.util.function.BiFunction<? super java.lang.Long,? super V,? extends V> remappingFunction)
- Specified by:
computeIfPresent
in interfacejava.util.Map<java.lang.Long,V>
-
computeIfPresent
public V computeIfPresent(long key, LongObjectToObjectFunction<? super V,? extends V> remappingFunction)
If the value for the specified key is present attempts to compute a new mapping given the key and its current mapped value.Primitive specialized version of
Map.computeIfPresent(Object, BiFunction)
.- Parameters:
key
- with which the specified value is to be associated.remappingFunction
- the function to compute a value.- Returns:
- the new value associated with the specified key, or null if none.
-
compute
public V compute(java.lang.Long key, java.util.function.BiFunction<? super java.lang.Long,? super V,? extends V> remappingFunction)
- Specified by:
compute
in interfacejava.util.Map<java.lang.Long,V>
-
compute
public V compute(long key, LongObjectToObjectFunction<? super V,? extends V> remappingFunction)
Attempts to compute a mapping for the specified key and its current mapped value (ornull
if there is no current mapping).Primitive specialized version of
Map.compute(Object, BiFunction)
.- Parameters:
key
- with which the specified value is to be associated.remappingFunction
- the function to compute a value.- Returns:
- the new value associated with the specified key, or null if none.
-
merge
public V merge(java.lang.Long key, V value, java.util.function.BiFunction<? super V,? super V,? extends V> remappingFunction)
- Specified by:
merge
in interfacejava.util.Map<java.lang.Long,V>
-
merge
public V merge(long key, V value, java.util.function.BiFunction<? super V,? super V,? extends V> remappingFunction)
If the specified key is not already associated with a value or is associated with null, associates it with the given non-null value. Otherwise, replaces the associated value with the results of the given remapping function, or removes if the result isnull
.Primitive specialized version of
Map.merge(Object, Object, BiFunction)
.- Parameters:
key
- with which the resulting value is to be associated.value
- the non-null value to be merged with the existing value associated with the key or, if no existing value or a null value is associated with the key, to be associated with the key.remappingFunction
- the function to recompute a value if present.- Returns:
- the new value associated with the specified key, or null if no value is associated with the key.
-
putIfAbsent
public V putIfAbsent(java.lang.Long key, V value)
- Specified by:
putIfAbsent
in interfacejava.util.Map<java.lang.Long,V>
-
putIfAbsent
public V putIfAbsent(long key, V value)
If the specified key is not already associated with a value (or is mapped tonull
) associates it with the given value and returnsnull
, else returns the current value.Primitive specialized version of
Map.putIfAbsent(Object, Object)
.- Parameters:
key
- with which the specified value is to be associated.value
- to be associated with the specified key.- Returns:
- the previous value associated with the specified key, or
null
if there was no mapping for the key.
-
put
public V put(java.lang.Long key, V value)
- Specified by:
put
in interfacejava.util.Map<java.lang.Long,V>
-
put
public V put(long key, V value)
Overloaded version ofMap.put(Object, Object)
that takes a primitive long key.- Parameters:
key
- for indexing theMap
value
- to be inserted in theMap
- Returns:
- always null (as per JCache API, as opposed to
Map
)
-
remove
public boolean remove(java.lang.Object key, java.lang.Object value)
- Specified by:
remove
in interfacejava.util.Map<java.lang.Long,V>
-
remove
public boolean remove(long key, V value)
Removes the entry for the specified key only if it is currently mapped to the specified value.Primitive specialized version of
Map.remove(Object, Object)
.- Parameters:
key
- key with which the specified value is associated.value
- expected to be associated with the specified key.- Returns:
true
if the value was removed.
-
remove
public V remove(java.lang.Object key)
- Specified by:
remove
in interfacejava.util.Map<java.lang.Long,V>
-
remove
public V remove(long key)
Overloaded version ofMap.remove(Object)
that takes a primitive long key.- Parameters:
key
- for indexing theMap
- Returns:
- the value if found otherwise null
-
replace
public boolean replace(java.lang.Long key, V oldValue, V newValue)
- Specified by:
replace
in interfacejava.util.Map<java.lang.Long,V>
-
replace
public boolean replace(long key, V oldValue, V newValue)
Replaces the entry for the specified key only if currently mapped to the specified value.Primitive specialized version of
Map.replace(Object, Object, Object)
.- Parameters:
key
- with which the specified value is associated.oldValue
- expected to be associated with the specified key.newValue
- to be associated with the specified key.- Returns:
true
if the value was replaced.
-
replace
public V replace(java.lang.Long key, V value)
- Specified by:
replace
in interfacejava.util.Map<java.lang.Long,V>
-
replace
public V replace(long key, V value)
Replaces the entry for the specified key only if it is currently mapped to some value.Primitive specialized version of
Map.replace(Object, Object)
.- Parameters:
key
- with which the specified value is associated.value
- to be associated with the specified key.- Returns:
- the previous value associated with the specified key.
-
replaceAll
public void replaceAll(java.util.function.BiFunction<? super java.lang.Long,? super V,? extends V> function)
- Specified by:
replaceAll
in interfacejava.util.Map<java.lang.Long,V>
-
replaceAllLong
public void replaceAllLong(LongObjectToObjectFunction<? super V,? extends V> function)
Replaces each entry's value with the result of invoking the given function on that entry until all entries have been processed or the function throws an exception.Primitive specialized version of
Map.replaceAll(BiFunction)
.NB: Renamed from forEach to avoid overloading on parameter types of lambda expression, which doesn't play well with type inference in lambda expressions.
- Parameters:
function
- the function to apply to each entry.
-
shuffleUp
private void shuffleUp(int fromIndex, int toIndex)
-
shuffleDown
private void shuffleDown(int setBeginIndex)
-
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 interfacejava.util.Map<java.lang.Long,V>
-
putAll
public void putAll(java.util.Map<? extends java.lang.Long,? extends V> map)
- Specified by:
putAll
in interfacejava.util.Map<java.lang.Long,V>
-
putAll
public void putAll(Long2ObjectCache<? extends V> map)
Put all values from the given map longo this one without allocation.- Parameters:
map
- whose value are to be added.
-
keySet
public Long2ObjectCache.KeySet keySet()
- Specified by:
keySet
in interfacejava.util.Map<java.lang.Long,V>
-
values
public Long2ObjectCache.ValueCollection values()
- Specified by:
values
in interfacejava.util.Map<java.lang.Long,V>
-
entrySet
public Long2ObjectCache.EntrySet entrySet()
- Specified by:
entrySet
in interfacejava.util.Map<java.lang.Long,V>
-
toString
public java.lang.String toString()
- Overrides:
toString
in classjava.lang.Object
-
equals
public boolean equals(java.lang.Object o)
- Specified by:
equals
in interfacejava.util.Map<java.lang.Long,V>
- Overrides:
equals
in classjava.lang.Object
-
hashCode
public int hashCode()
- Specified by:
hashCode
in interfacejava.util.Map<java.lang.Long,V>
- Overrides:
hashCode
in classjava.lang.Object
-
-