Class PrivateMaxEntriesMap<K,​V>

  • Type Parameters:
    K - the type of keys maintained by this map
    V - the type of mapped values
    All Implemented Interfaces:
    java.io.Serializable, java.util.concurrent.ConcurrentMap<K,​V>, java.util.Map<K,​V>

    public final class PrivateMaxEntriesMap<K,​V>
    extends java.util.AbstractMap<K,​V>
    implements java.util.concurrent.ConcurrentMap<K,​V>, java.io.Serializable
    A hash table supporting full concurrency of retrievals, adjustable expected concurrency for updates, and a maximum capacity to bound the map by. This implementation differs from ConcurrentHashMap in that it maintains a page replacement algorithm that is used to evict an entry when the map has exceeded its capacity. Unlike the Java Collections Framework, this map does not have a publicly visible constructor and instances are created through a PrivateMaxEntriesMap.Builder.

    An entry is evicted from the map when the entry size exceeds its maximum capacity threshold.

    An EvictionListener may be supplied for notification when an entry is evicted from the map. This listener is invoked on a caller's thread and will not block other threads from operating on the map. An implementation should be aware that the caller's thread will not expect long execution times or failures as a side effect of the listener being notified. Execution safety and a fast turn around time can be achieved by performing the operation asynchronously, such as by submitting a task to an ExecutorService.

    The concurrency level determines the number of threads that can concurrently modify the table. Using a significantly higher or lower value than needed can waste space or lead to thread contention, but an estimate within an order of magnitude of the ideal value does not usually have a noticeable impact. Because placement in hash tables is essentially random, the actual concurrency will vary.

    This class and its views and iterators implement all of the optional methods of the Map and Iterator interfaces.

    Like Hashtable but unlike HashMap, this class does not allow null to be used as a key or value. Unlike LinkedHashMap, this class does not provide predictable iteration order. A snapshot of the keys and entries may be obtained in ascending and descending order of retention.

    See Also:
    http://code.google.com/p/concurrentlinkedhashmap/, Serialized Form
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      (package private) void afterRead​(PrivateMaxEntriesMap.Node<K,​V> node)
      Performs the post-processing work required after a read.
      (package private) void afterWrite​(java.lang.Runnable task)
      Performs the post-processing work required after a write.
      (package private) void applyRead​(PrivateMaxEntriesMap.Node<K,​V> node)
      Updates the node's location in the page replacement policy.
      long capacity()
      Retrieves the maximum capacity of the map.
      (package private) static int ceilingNextPowerOfTwo​(int x)  
      (package private) static void checkArgument​(boolean expression)
      Ensures that the argument expression is true.
      (package private) static void checkNotNull​(java.lang.Object o)
      Ensures that the object is not null.
      (package private) static void checkState​(boolean expression)
      Ensures that the state expression is true.
      void clear()  
      boolean containsKey​(java.lang.Object key)  
      boolean containsValue​(java.lang.Object value)  
      (package private) void drainBuffers()
      Drains the read and write buffers up to an amortized threshold.
      (package private) void drainOnReadIfNeeded​(int bufferIndex, long writeCount)
      Attempts to drain the buffers if it is determined to be needed when post-processing a read.
      (package private) void drainReadBuffer​(int bufferIndex)
      Drains the read buffer up to an amortized threshold.
      (package private) void drainReadBuffers()
      Drains the read buffers, each up to an amortized threshold.
      (package private) void drainWriteBuffer()
      Drains the read buffer up to an amortized threshold.
      java.util.Set<java.util.Map.Entry<K,​V>> entrySet()  
      (package private) void evict()
      Evicts entries from the map while it exceeds the capacity and appends evicted entries to the notification queue for processing.
      V get​(java.lang.Object key)  
      (package private) boolean hasOverflowed()
      Determines whether the map has exceeded its capacity.
      boolean isEmpty()  
      java.util.Set<K> keySet()  
      (package private) void makeDead​(PrivateMaxEntriesMap.Node<K,​V> node)
      Atomically transitions the node to the dead state and decrements the weightedSize.
      (package private) void makeRetired​(PrivateMaxEntriesMap.Node<K,​V> node)
      Atomically transitions the node from the alive state to the retired state, if a valid transition.
      V put​(K key, V value)  
      (package private) V put​(K key, V value, boolean onlyIfAbsent)
      Adds a node to the list and the data store.
      V putIfAbsent​(K key, V value)  
      (package private) static int readBufferIndex()
      Returns the index to the read buffer to record into.
      private static int readBufferIndex​(int bufferIndex, int entryIndex)  
      private void readObject​(java.io.ObjectInputStream stream)  
      (package private) long recordRead​(int bufferIndex, PrivateMaxEntriesMap.Node<K,​V> node)
      Records a read in the buffer and return its write count.
      V remove​(java.lang.Object key)  
      boolean remove​(java.lang.Object key, java.lang.Object value)  
      V replace​(K key, V value)  
      boolean replace​(K key, V oldValue, V newValue)  
      void setCapacity​(long capacity)
      Sets the maximum capacity of the map and eagerly evicts entries until it shrinks to the appropriate size.
      int size()  
      (package private) void tryToDrainBuffers()
      Attempts to acquire the eviction lock and apply the pending operations, up to the amortized threshold, to the page replacement policy.
      (package private) boolean tryToRetire​(PrivateMaxEntriesMap.Node<K,​V> node, PrivateMaxEntriesMap.WeightedValue<V> expect)
      Attempts to transition the node from the alive state to the retired state.
      java.util.Collection<V> values()  
      (package private) java.lang.Object writeReplace()  
      • Methods inherited from class java.util.AbstractMap

        clone, equals, hashCode, putAll, toString
      • Methods inherited from class java.lang.Object

        finalize, getClass, notify, notifyAll, wait, wait, wait
      • Methods inherited from interface java.util.concurrent.ConcurrentMap

        compute, computeIfAbsent, computeIfPresent, forEach, getOrDefault, merge, replaceAll
      • Methods inherited from interface java.util.Map

        equals, hashCode, putAll
    • Field Detail

      • NCPU

        static final int NCPU
        The number of CPUs
      • MAXIMUM_CAPACITY

        static final long MAXIMUM_CAPACITY
        The maximum capacity of the map.
        See Also:
        Constant Field Values
      • NUMBER_OF_READ_BUFFERS

        static final int NUMBER_OF_READ_BUFFERS
        The number of read buffers to use. The max of 4 was introduced due to databind#3665.
      • READ_BUFFERS_MASK

        static final int READ_BUFFERS_MASK
        Mask value for indexing into the read buffers.
      • READ_BUFFER_THRESHOLD

        static final int READ_BUFFER_THRESHOLD
        The number of pending read operations before attempting to drain. The threshold of 4 was introduced due to databind#3665.
        See Also:
        Constant Field Values
      • READ_BUFFER_DRAIN_THRESHOLD

        static final int READ_BUFFER_DRAIN_THRESHOLD
        The maximum number of read operations to perform per amortized drain.
        See Also:
        Constant Field Values
      • READ_BUFFER_SIZE

        static final int READ_BUFFER_SIZE
        The maximum number of pending reads per buffer.
        See Also:
        Constant Field Values
      • READ_BUFFER_INDEX_MASK

        static final int READ_BUFFER_INDEX_MASK
        Mask value for indexing into the read buffer.
        See Also:
        Constant Field Values
      • WRITE_BUFFER_DRAIN_THRESHOLD

        static final int WRITE_BUFFER_DRAIN_THRESHOLD
        The maximum number of write operations to perform per amortized drain.
        See Also:
        Constant Field Values
      • concurrencyLevel

        final int concurrencyLevel
      • readBufferReadCount

        final long[] readBufferReadCount
      • weightedSize

        final java.util.concurrent.atomic.AtomicLong weightedSize
      • capacity

        final java.util.concurrent.atomic.AtomicLong capacity
      • evictionLock

        final java.util.concurrent.locks.Lock evictionLock
      • writeBuffer

        final java.util.Queue<java.lang.Runnable> writeBuffer
      • readBufferWriteCount

        final java.util.concurrent.atomic.AtomicLongArray readBufferWriteCount
      • readBufferDrainAtWriteCount

        final java.util.concurrent.atomic.AtomicLongArray readBufferDrainAtWriteCount
      • keySet

        transient java.util.Set<K> keySet
      • values

        transient java.util.Collection<V> values
      • entrySet

        transient java.util.Set<java.util.Map.Entry<K,​V>> entrySet
    • Constructor Detail

      • PrivateMaxEntriesMap

        PrivateMaxEntriesMap​(PrivateMaxEntriesMap.Builder<K,​V> builder)
        Creates an instance based on the builder's configuration.
    • Method Detail

      • ceilingNextPowerOfTwo

        static int ceilingNextPowerOfTwo​(int x)
      • readBufferIndex

        private static int readBufferIndex​(int bufferIndex,
                                           int entryIndex)
      • checkNotNull

        static void checkNotNull​(java.lang.Object o)
        Ensures that the object is not null.
      • checkArgument

        static void checkArgument​(boolean expression)
        Ensures that the argument expression is true.
      • checkState

        static void checkState​(boolean expression)
        Ensures that the state expression is true.
      • capacity

        public long capacity()
        Retrieves the maximum capacity of the map.
        Returns:
        the maximum capacity
      • setCapacity

        public void setCapacity​(long capacity)
        Sets the maximum capacity of the map and eagerly evicts entries until it shrinks to the appropriate size.
        Parameters:
        capacity - the maximum capacity of the map
        Throws:
        java.lang.IllegalArgumentException - if the capacity is negative
      • hasOverflowed

        boolean hasOverflowed()
        Determines whether the map has exceeded its capacity.
      • evict

        void evict()
        Evicts entries from the map while it exceeds the capacity and appends evicted entries to the notification queue for processing.
      • afterRead

        void afterRead​(PrivateMaxEntriesMap.Node<K,​V> node)
        Performs the post-processing work required after a read.
        Parameters:
        node - the entry in the page replacement policy
      • readBufferIndex

        static int readBufferIndex()
        Returns the index to the read buffer to record into.
      • recordRead

        long recordRead​(int bufferIndex,
                        PrivateMaxEntriesMap.Node<K,​V> node)
        Records a read in the buffer and return its write count.
        Parameters:
        bufferIndex - the index to the chosen read buffer
        node - the entry in the page replacement policy
        Returns:
        the number of writes on the chosen read buffer
      • drainOnReadIfNeeded

        void drainOnReadIfNeeded​(int bufferIndex,
                                 long writeCount)
        Attempts to drain the buffers if it is determined to be needed when post-processing a read.
        Parameters:
        bufferIndex - the index to the chosen read buffer
        writeCount - the number of writes on the chosen read buffer
      • afterWrite

        void afterWrite​(java.lang.Runnable task)
        Performs the post-processing work required after a write.
        Parameters:
        task - the pending operation to be applied
      • tryToDrainBuffers

        void tryToDrainBuffers()
        Attempts to acquire the eviction lock and apply the pending operations, up to the amortized threshold, to the page replacement policy.
      • drainBuffers

        void drainBuffers()
        Drains the read and write buffers up to an amortized threshold.
      • drainReadBuffers

        void drainReadBuffers()
        Drains the read buffers, each up to an amortized threshold.
      • drainReadBuffer

        void drainReadBuffer​(int bufferIndex)
        Drains the read buffer up to an amortized threshold.
      • drainWriteBuffer

        void drainWriteBuffer()
        Drains the read buffer up to an amortized threshold.
      • tryToRetire

        boolean tryToRetire​(PrivateMaxEntriesMap.Node<K,​V> node,
                            PrivateMaxEntriesMap.WeightedValue<V> expect)
        Attempts to transition the node from the alive state to the retired state.
        Parameters:
        node - the entry in the page replacement policy
        expect - the expected weighted value
        Returns:
        if successful
      • makeRetired

        void makeRetired​(PrivateMaxEntriesMap.Node<K,​V> node)
        Atomically transitions the node from the alive state to the retired state, if a valid transition.
        Parameters:
        node - the entry in the page replacement policy
      • makeDead

        void makeDead​(PrivateMaxEntriesMap.Node<K,​V> node)
        Atomically transitions the node to the dead state and decrements the weightedSize.
        Parameters:
        node - the entry in the page replacement policy
      • isEmpty

        public boolean isEmpty()
        Specified by:
        isEmpty in interface java.util.Map<K,​V>
        Overrides:
        isEmpty in class java.util.AbstractMap<K,​V>
      • size

        public int size()
        Specified by:
        size in interface java.util.Map<K,​V>
        Overrides:
        size in class java.util.AbstractMap<K,​V>
      • clear

        public void clear()
        Specified by:
        clear in interface java.util.Map<K,​V>
        Overrides:
        clear in class java.util.AbstractMap<K,​V>
      • containsKey

        public boolean containsKey​(java.lang.Object key)
        Specified by:
        containsKey in interface java.util.Map<K,​V>
        Overrides:
        containsKey in class java.util.AbstractMap<K,​V>
      • containsValue

        public boolean containsValue​(java.lang.Object value)
        Specified by:
        containsValue in interface java.util.Map<K,​V>
        Overrides:
        containsValue in class java.util.AbstractMap<K,​V>
      • get

        public V get​(java.lang.Object key)
        Specified by:
        get in interface java.util.Map<K,​V>
        Overrides:
        get in class java.util.AbstractMap<K,​V>
      • put

        public V put​(K key,
                     V value)
        Specified by:
        put in interface java.util.Map<K,​V>
        Overrides:
        put in class java.util.AbstractMap<K,​V>
      • putIfAbsent

        public V putIfAbsent​(K key,
                             V value)
        Specified by:
        putIfAbsent in interface java.util.concurrent.ConcurrentMap<K,​V>
        Specified by:
        putIfAbsent in interface java.util.Map<K,​V>
      • put

        V put​(K key,
              V value,
              boolean onlyIfAbsent)
        Adds a node to the list and the data store. If an existing node is found, then its value is updated if allowed.
        Parameters:
        key - key with which the specified value is to be associated
        value - value to be associated with the specified key
        onlyIfAbsent - a write is performed only if the key is not already associated with a value
        Returns:
        the prior value in the data store or null if no mapping was found
      • remove

        public V remove​(java.lang.Object key)
        Specified by:
        remove in interface java.util.Map<K,​V>
        Overrides:
        remove in class java.util.AbstractMap<K,​V>
      • remove

        public boolean remove​(java.lang.Object key,
                              java.lang.Object value)
        Specified by:
        remove in interface java.util.concurrent.ConcurrentMap<K,​V>
        Specified by:
        remove in interface java.util.Map<K,​V>
      • replace

        public V replace​(K key,
                         V value)
        Specified by:
        replace in interface java.util.concurrent.ConcurrentMap<K,​V>
        Specified by:
        replace in interface java.util.Map<K,​V>
      • replace

        public boolean replace​(K key,
                               V oldValue,
                               V newValue)
        Specified by:
        replace in interface java.util.concurrent.ConcurrentMap<K,​V>
        Specified by:
        replace in interface java.util.Map<K,​V>
      • keySet

        public java.util.Set<K> keySet()
        Specified by:
        keySet in interface java.util.Map<K,​V>
        Overrides:
        keySet in class java.util.AbstractMap<K,​V>
      • values

        public java.util.Collection<V> values()
        Specified by:
        values in interface java.util.Map<K,​V>
        Overrides:
        values in class java.util.AbstractMap<K,​V>
      • entrySet

        public java.util.Set<java.util.Map.Entry<K,​V>> entrySet()
        Specified by:
        entrySet in interface java.util.Map<K,​V>
        Specified by:
        entrySet in class java.util.AbstractMap<K,​V>
      • writeReplace

        java.lang.Object writeReplace()
      • readObject

        private void readObject​(java.io.ObjectInputStream stream)
                         throws java.io.InvalidObjectException
        Throws:
        java.io.InvalidObjectException