Class Long2ObjectCache<V>

  • Type Parameters:
    V - type of values stored in the Map
    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.

    • 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 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, 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 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 a LongFunction 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 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)
      void forEach​(java.util.function.BiConsumer<? super java.lang.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​(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 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)
      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 to null) associates it with the given value and returns null, else returns the current value.
      V putIfAbsent​(java.lang.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​(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()
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
      • Methods inherited from interface java.util.Map

        getOrDefault
    • 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
    • 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 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
      • 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 interface java.util.Map<java.lang.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​(java.lang.Long key,
                                 java.util.function.Function<? super java.lang.Long,​? extends V> mappingFunction)
        Specified by:
        computeIfAbsent in interface java.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 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​(java.lang.Long key,
                                  java.util.function.BiFunction<? super java.lang.Long,​? super V,​? extends V> remappingFunction)
        Specified by:
        computeIfPresent in interface java.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 interface java.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 (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​(java.lang.Long key,
                       V value,
                       java.util.function.BiFunction<? super V,​? super V,​? extends V> remappingFunction)
        Specified by:
        merge in interface java.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 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​(java.lang.Long key,
                             V value)
        Specified by:
        putIfAbsent in interface java.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 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​(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 boolean remove​(java.lang.Object key,
                              java.lang.Object value)
        Specified by:
        remove in interface java.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 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
      • replace

        public boolean replace​(java.lang.Long key,
                               V oldValue,
                               V newValue)
        Specified by:
        replace in interface java.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 interface java.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 interface java.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 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>
      • 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 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