Long2ObjectCache (Agrona)

java.lang.Object
- org.agrona.collections.Long2ObjectCache<V>

Type Parameters:

V - type of values stored in the Map

All Implemented Interfaces:

Map<Long,V>
```
public class Long2ObjectCache<V>
extends Object
implements Map<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 and Description
`class`	`Long2ObjectCache.EntryIterator` Iterator over entries which supports access to unboxed keys via `Long2ObjectCache.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 via `Long2ObjectCache.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.

Nested classes/interfaces inherited from interface java.util.Map
Map.Entry<K,V>

Constructor Summary

Constructors
Constructor and Description
`Long2ObjectCache(int numSets, int setSize, Consumer<V> evictionConsumer)` Constructs cache with provided configuration.

Method Summary

All Methods Instance Methods Concrete Methods
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`	`compute(Long key, BiFunction<? super Long,? super V,? extends V> remappingFunction)`
`V`	`compute(long key, LongObjectToObjectFunction<? super V,? extends V> remappingFunction)` Attempts to compute a mapping for the specified key and its current mapped value (or `null` if there is no current mapping).
`V`	`computeIfAbsent(Long key, Function<? super Long,? extends V> mappingFunction)`
`V`	`computeIfAbsent(long key, 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.
`V`	`computeIfPresent(Long key, BiFunction<? super Long,? super V,? extends V> remappingFunction)`
`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.
`boolean`	`containsKey(long key)` Overloaded version of `Map.containsKey(Object)` that takes a primitive long key.
`boolean`	`containsKey(Object key)`
`boolean`	`containsValue(Object value)`
`Long2ObjectCache.EntrySet`	`entrySet()`
`boolean`	`equals(Object o)`
`void`	`forEach(BiConsumer<? super Long,? super V> action)`
`void`	`forEachLong(LongObjConsumer<? super V> consumer)` Implementation of the `forEach(BiConsumer)` that avoids boxing of keys.
`V`	`get(long key)` Overloaded version of `Map.get(Object)` that takes a primitive long key.
`V`	`get(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, 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(Long key, V value, BiFunction<? super V,? super V,? extends V> remappingFunction)`
`V`	`put(long key, V value)` Overloaded version of `Map.put(Object, Object)` that takes a primitive long key.
`V`	`put(Long key, V value)`
`void`	`putAll(Long2ObjectCache<? extends V> map)` Put all values from the given map longo this one without allocation.
`void`	`putAll(Map<? extends Long,? extends V> map)`
`V`	`putIfAbsent(long key, V value)` If the specified key is not already associated with a value (or is mapped to `null`) associates it with the given value and returns `null`, else returns the current value.
`V`	`putIfAbsent(Long key, V value)`
`V`	`remove(long key)` Overloaded version of `Map.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(Object key)`
`boolean`	`remove(Object key, Object value)`
`V`	`replace(long key, V value)` Replaces the entry for the specified key only if it is currently mapped to some value.
`V`	`replace(Long key, V value)`
`boolean`	`replace(long key, V oldValue, V newValue)` Replaces the entry for the specified key only if currently mapped to the specified value.
`boolean`	`replace(Long key, V oldValue, V newValue)`
`void`	`replaceAll(BiFunction<? super 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.
`int`	`size()`
`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
getOrDefault

- Constructor Detail
  - Long2ObjectCache
```
public Long2ObjectCache(int numSets,
                        int setSize,
                        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 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 Map<Long,V>
  - isEmpty
```
public boolean isEmpty()
```
    Specified by:
    
    isEmpty in interface Map<Long,V>
  - containsKey
```
public boolean containsKey(Object key)
```
    Specified by:
    
    containsKey in interface Map<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(Object value)
```
    Specified by:
    
    containsValue in interface Map<Long,V>
  - get
```
public V get(Object key)
```
    Specified by:
    
    get in interface Map<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
  - 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(BiConsumer<? super Long,? super V> action)
```
    Specified by:
    
    forEach in interface Map<Long,V>
  - forEachLong
```
public void forEachLong(LongObjConsumer<? super V> consumer)
```
    Implementation of the forEach(BiConsumer) that avoids boxing of keys.
    
    Parameters:
    
    consumer - to be called for each key/value pair.
  - computeIfAbsent
```
public V computeIfAbsent(Long key,
                         Function<? super Long,? extends V> mappingFunction)
```
    Specified by:
    
    computeIfAbsent in interface Map<Long,V>
  - computeIfAbsent
```
public V computeIfAbsent(long key,
                         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.
  - computeIfPresent
```
public V computeIfPresent(Long key,
                          BiFunction<? super Long,? super V,? extends V> remappingFunction)
```
    Specified by:
    
    computeIfPresent in interface Map<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(Long key,
                 BiFunction<? super Long,? super V,? extends V> remappingFunction)
```
    Specified by:
    
    compute in interface Map<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 (or null 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(Long key,
               V value,
               BiFunction<? super V,? super V,? extends V> remappingFunction)
```
    Specified by:
    
    merge in interface Map<Long,V>
  - merge
```
public V merge(long key,
               V value,
               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 is null.
    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(Long key,
                     V value)
```
    Specified by:
    
    putIfAbsent in interface Map<Long,V>
  - putIfAbsent
```
public V putIfAbsent(long key,
                     V value)
```
    If the specified key is not already associated with a value (or is mapped to null) associates it with the given value and returns null, 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(Long key,
             V value)
```
    Specified by:
    
    put in interface Map<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 boolean remove(Object key,
                      Object value)
```
    Specified by:
    
    remove in interface Map<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(Object key)
```
    Specified by:
    
    remove in interface Map<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
  - replace
```
public boolean replace(Long key,
                       V oldValue,
                       V newValue)
```
    Specified by:
    
    replace in interface Map<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(Long key,
                 V value)
```
    Specified by:
    
    replace in interface Map<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(BiFunction<? super Long,? super V,? extends V> function)
```
    Specified by:
    
    replaceAll in interface Map<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.
  - 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 Map<Long,V>
  - putAll
```
public void putAll(Map<? extends Long,? extends V> map)
```
    Specified by:
    
    putAll in interface Map<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 interface Map<Long,V>
  - values
```
public Long2ObjectCache.ValueCollection values()
```
    Specified by:
    
    values in interface Map<Long,V>
  - entrySet
```
public Long2ObjectCache.EntrySet entrySet()
```
    Specified by:
    
    entrySet in interface Map<Long,V>
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - equals
```
public boolean equals(Object o)
```
    Specified by:
    
    equals in interface Map<Long,V>
    
    Overrides:
    
    equals in class Object
  - hashCode
```
public int hashCode()
```
    Specified by:
    
    hashCode in interface Map<Long,V>
    
    Overrides:
    
    hashCode in class Object

Class Long2ObjectCache<V>

Nested Class Summary

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

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.util.Map

Constructor Detail

Long2ObjectCache

Method Detail

cacheHits

cacheMisses

cachePuts

resetCounters

capacity

size

isEmpty

containsKey

containsKey

containsValue

get

get

getOrDefault

forEach

forEachLong

computeIfAbsent

computeIfAbsent

computeIfPresent

computeIfPresent

compute

compute

merge

merge

putIfAbsent

putIfAbsent

put

put

remove

remove

remove

remove

replace

replace

replace

replace

replaceAll

replaceAllLong

clear

putAll

putAll

keySet

values

entrySet

toString

equals

hashCode