Class ConcurrentLinkedHashMap<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>

    @ThreadSafe
    public final class ConcurrentLinkedHashMap<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 ConcurrentLinkedHashMap.Builder.

    An entry is evicted from the map when the weighted capacity exceeds its maximum weighted capacity threshold. A EntryWeigher determines how many units of capacity that an entry consumes. The default weigher assigns each value a weight of 1 to bound the map by the total number of key-value pairs. A map that holds collections may choose to weigh values by the number of elements in the collection and bound the map by the total number of elements that it contains. A change to a value that modifies its weight requires that an update operation is performed on the map.

    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
    • Field Detail

      • MAXIMUM_CAPACITY

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

        static final int MAXIMUM_BUFFER_SIZE
        The maximum number of pending operations per buffer.
        See Also:
        Constant Field Values
      • BUFFER_THRESHOLD

        static final int BUFFER_THRESHOLD
        The number of pending operations per buffer before attempting to drain.
        See Also:
        Constant Field Values
      • NUMBER_OF_BUFFERS

        static final int NUMBER_OF_BUFFERS
        The number of buffers to use.
      • BUFFER_MASK

        static final int BUFFER_MASK
        Mask value for indexing into the buffers.
      • AMORTIZED_DRAIN_THRESHOLD

        static final int AMORTIZED_DRAIN_THRESHOLD
        The maximum number of operations to perform per amortized drain.
      • DISCARDING_QUEUE

        static final java.util.Queue<?> DISCARDING_QUEUE
        A queue that discards all entries.
      • concurrencyLevel

        final int concurrencyLevel
      • weightedSize

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

        volatile long capacity
      • nextOrder

        volatile int nextOrder
      • drainedOrder

        int drainedOrder
      • evictionLock

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

        final java.util.concurrent.atomic.AtomicIntegerArray bufferLengths
      • 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

      • ConcurrentLinkedHashMap

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

      • ceilingNextPowerOfTwo

        static int ceilingNextPowerOfTwo​(int x)
      • 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 weighted capacity of the map.
        Returns:
        the maximum weighted capacity
      • setCapacity

        public void setCapacity​(long capacity)
        Sets the maximum weighted capacity of the map and eagerly evicts entries until it shrinks to the appropriate size.
        Parameters:
        capacity - the maximum weighted 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.
      • afterCompletion

        void afterCompletion​(ConcurrentLinkedHashMap.Task task)
        Performs the post-processing work required after the map operation.
        Parameters:
        task - the pending operation to be applied
      • schedule

        boolean schedule​(ConcurrentLinkedHashMap.Task task)
        Schedules the task to be applied to the page replacement policy.
        Parameters:
        task - the pending operation
        Returns:
        if the draining of the buffers can be delayed
      • bufferIndex

        static int bufferIndex()
        Returns the index to the buffer that the task should be scheduled on.
      • nextOrdering

        int nextOrdering()
        Returns the ordering value to assign to a task.
      • 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 buffers up to the amortized threshold and applies the pending operations.
      • moveTasksFromBuffers

        int moveTasksFromBuffers​(ConcurrentLinkedHashMap.Task[] tasks)
        Moves the tasks from the buffers into the output array.
        Parameters:
        tasks - the ordered array of the pending operations
        Returns:
        the highest index location of a task that was added to the array
      • moveTasksFromBuffer

        int moveTasksFromBuffer​(ConcurrentLinkedHashMap.Task[] tasks,
                                int bufferIndex)
        Moves the tasks from the specified buffer into the output array.
        Parameters:
        tasks - the ordered array of the pending operations
        bufferIndex - the buffer to drain into the tasks array
        Returns:
        the highest index location of a task that was added to the array
      • addTaskToChain

        void addTaskToChain​(ConcurrentLinkedHashMap.Task[] tasks,
                            ConcurrentLinkedHashMap.Task task,
                            int index)
        Adds the task as the head of the chain at the index location.
        Parameters:
        tasks - the ordered array of the pending operations
        task - the pending operation to add
        index - the array location
      • runTasks

        void runTasks​(ConcurrentLinkedHashMap.Task[] tasks,
                      int maxTaskIndex)
        Runs the pending page replacement policy operations.
        Parameters:
        tasks - the ordered array of the pending operations
        maxTaskIndex - the maximum index of the array
      • runTasksInChain

        void runTasksInChain​(ConcurrentLinkedHashMap.Task task)
        Runs the pending operations on the linked chain.
        Parameters:
        task - the first task in the chain of operations
      • updateDrainedOrder

        void updateDrainedOrder​(ConcurrentLinkedHashMap.Task[] tasks,
                                int maxTaskIndex)
        Updates the order to start the next drain from.
        Parameters:
        tasks - the ordered array of operations
        maxTaskIndex - the maximum index of the array
      • notifyListener

        void notifyListener()
        Notifies the listener of entries that were evicted.
      • 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>
      • weightedSize

        public long weightedSize()
        Returns the weighted size of this map.
        Returns:
        the combined weight of the values in this map
      • 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>
      • getQuietly

        public V getQuietly​(java.lang.Object key)
        Returns the value to which the specified key is mapped, or null if this map contains no mapping for the key. This method differs from get(Object) in that it does not record the operation with the page replacement policy.
        Parameters:
        key - the key whose associated value is to be returned
        Returns:
        the value to which the specified key is mapped, or null if this map contains no mapping for the key
        Throws:
        java.lang.NullPointerException - if the specified key is null
      • 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>
      • ascendingKeySet

        public java.util.Set<K> ascendingKeySet()
        Returns a unmodifiable snapshot Set view of the keys contained in this map. The set's iterator returns the keys whose order of iteration is the ascending order in which its entries are considered eligible for retention, from the least-likely to be retained to the most-likely.

        Beware that, unlike in keySet(), obtaining the set is NOT a constant-time operation. Because of the asynchronous nature of the page replacement policy, determining the retention ordering requires a traversal of the keys.

        Returns:
        an ascending snapshot view of the keys in this map
      • ascendingKeySetWithLimit

        public java.util.Set<K> ascendingKeySetWithLimit​(int limit)
        Returns an unmodifiable snapshot Set view of the keys contained in this map. The set's iterator returns the keys whose order of iteration is the ascending order in which its entries are considered eligible for retention, from the least-likely to be retained to the most-likely.

        Beware that, unlike in keySet(), obtaining the set is NOT a constant-time operation. Because of the asynchronous nature of the page replacement policy, determining the retention ordering requires a traversal of the keys.

        Parameters:
        limit - the maximum size of the returned set
        Returns:
        a ascending snapshot view of the keys in this map
        Throws:
        java.lang.IllegalArgumentException - if the limit is negative
      • descendingKeySet

        public java.util.Set<K> descendingKeySet()
        Returns an unmodifiable snapshot Set view of the keys contained in this map. The set's iterator returns the keys whose order of iteration is the descending order in which its entries are considered eligible for retention, from the most-likely to be retained to the least-likely.

        Beware that, unlike in keySet(), obtaining the set is NOT a constant-time operation. Because of the asynchronous nature of the page replacement policy, determining the retention ordering requires a traversal of the keys.

        Returns:
        a descending snapshot view of the keys in this map
      • descendingKeySetWithLimit

        public java.util.Set<K> descendingKeySetWithLimit​(int limit)
        Returns an unmodifiable snapshot Set view of the keys contained in this map. The set's iterator returns the keys whose order of iteration is the descending order in which its entries are considered eligible for retention, from the most-likely to be retained to the least-likely.

        Beware that, unlike in keySet(), obtaining the set is NOT a constant-time operation. Because of the asynchronous nature of the page replacement policy, determining the retention ordering requires a traversal of the keys.

        Parameters:
        limit - the maximum size of the returned set
        Returns:
        a descending snapshot view of the keys in this map
        Throws:
        java.lang.IllegalArgumentException - if the limit is negative
      • orderedKeySet

        java.util.Set<K> orderedKeySet​(boolean ascending,
                                       int limit)
      • 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>
      • ascendingMap

        public java.util.Map<K,​V> ascendingMap()
        Returns an unmodifiable snapshot Map view of the mappings contained in this map. The map's collections return the mappings whose order of iteration is the ascending order in which its entries are considered eligible for retention, from the least-likely to be retained to the most-likely.

        Beware that obtaining the mappings is NOT a constant-time operation. Because of the asynchronous nature of the page replacement policy, determining the retention ordering requires a traversal of the entries.

        Returns:
        a ascending snapshot view of this map
      • ascendingMapWithLimit

        public java.util.Map<K,​V> ascendingMapWithLimit​(int limit)
        Returns an unmodifiable snapshot Map view of the mappings contained in this map. The map's collections return the mappings whose order of iteration is the ascending order in which its entries are considered eligible for retention, from the least-likely to be retained to the most-likely.

        Beware that obtaining the mappings is NOT a constant-time operation. Because of the asynchronous nature of the page replacement policy, determining the retention ordering requires a traversal of the entries.

        Parameters:
        limit - the maximum size of the returned map
        Returns:
        a ascending snapshot view of this map
        Throws:
        java.lang.IllegalArgumentException - if the limit is negative
      • descendingMap

        public java.util.Map<K,​V> descendingMap()
        Returns an unmodifiable snapshot Map view of the mappings contained in this map. The map's collections return the mappings whose order of iteration is the descending order in which its entries are considered eligible for retention, from the most-likely to be retained to the least-likely.

        Beware that obtaining the mappings is NOT a constant-time operation. Because of the asynchronous nature of the page replacement policy, determining the retention ordering requires a traversal of the entries.

        Returns:
        a descending snapshot view of this map
      • descendingMapWithLimit

        public java.util.Map<K,​V> descendingMapWithLimit​(int limit)
        Returns an unmodifiable snapshot Map view of the mappings contained in this map. The map's collections return the mappings whose order of iteration is the descending order in which its entries are considered eligible for retention, from the most-likely to be retained to the least-likely.

        Beware that obtaining the mappings is NOT a constant-time operation. Because of the asynchronous nature of the page replacement policy, determining the retention ordering requires a traversal of the entries.

        Parameters:
        limit - the maximum size of the returned map
        Returns:
        a descending snapshot view of this map
        Throws:
        java.lang.IllegalArgumentException - if the limit is negative
      • orderedMap

        java.util.Map<K,​V> orderedMap​(boolean ascending,
                                            int limit)
      • writeReplace

        java.lang.Object writeReplace()
      • readObject

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