ConcurrentHashMap

/**

• A hash table supporting full concurrency of retrievals and
• high expected concurrency for updates. This class obeys the
• same functional specification as {@link java.util.Hashtable}, and
• includes versions of methods corresponding to each method of
• {@code Hashtable}. However, even though all operations are
• thread-safe, retrieval operations do <em>not</em> entail locking,
• and there is <em>not</em> any support for locking the entire table
• in a way that prevents all access. This class is fully
• interoperable with {@code Hashtable} in programs that rely on its
• thread safety but not on its synchronization details.
• <p>Retrieval operations (including {@code get}) generally do not
• block, so may overlap with update operations (including {@code put}
• and {@code remove}). Retrievals reflect the results of the most
• recently <em>completed</em> update operations holding upon their
• onset. (More formally, an update operation for a given key bears a
• <em>happens-before</em> relation with any (non-null) retrieval for
• that key reporting the updated value.) For aggregate operations
• such as {@code putAll} and {@code clear}, concurrent retrievals may
• reflect insertion or removal of only some entries. Similarly,
• Iterators, Spliterators and Enumerations return elements reflecting the
• state of the hash table at some point at or since the creation of the
• iterator/enumeration. They do <em>not</em> throw {@link
• java.util.ConcurrentModificationException ConcurrentModificationException}.
• However, iterators are designed to be used by only one thread at a time.
• Bear in mind that the results of aggregate status methods including
• {@code size}, {@code isEmpty}, and {@code containsValue} are typically
• useful only when a map is not undergoing concurrent updates in other threads.
• Otherwise the results of these methods reflect transient states
• that may be adequate for monitoring or estimation purposes, but not
• for program control.
• <p>The table is dynamically expanded when there are too many
• collisions (i.e., keys that have distinct hash codes but fall into
• the same slot modulo the table size), with the expected average
• effect of maintaining roughly two bins per mapping (corresponding
• to a 0.75 load factor threshold for resizing). There may be much
• variance around this average as mappings are added and removed, but
• overall, this maintains a commonly accepted time/space tradeoff for
• hash tables. However, resizing this or any other kind of hash
• table may be a relatively slow operation. When possible, it is a
• good idea to provide a size estimate as an optional {@code
• initialCapacity} constructor argument. An additional optional
• {@code loadFactor} constructor argument provides a further means of
• customizing initial table capacity by specifying the table density
• to be used in calculating the amount of space to allocate for the
• given number of elements. Also, for compatibility with previous
• versions of this class, constructors may optionally specify an
• expected {@code concurrencyLevel} as an additional hint for
• internal sizing. Note that using many keys with exactly the same
• {@code hashCode()} is a sure way to slow down performance of any
• hash table. To ameliorate impact, when keys are {@link Comparable},
• this class may use comparison order among keys to help break ties.
• <p>A {@link Set} projection of a ConcurrentHashMap may be created
• (using {@link #newKeySet()} or {@link #newKeySet(int)}), or viewed
• (using {@link #keySet(Object)} when only keys are of interest, and the
• mapped values are (perhaps transiently) not used or all take the
• same mapping value.
• <p>A ConcurrentHashMap can be used as scalable frequency map (a
• form of histogram or multiset) by using {@link
• java.util.concurrent.atomic.LongAdder} values and initializing via
• {@link #computeIfAbsent computeIfAbsent}. For example, to add a count
• to a {@code ConcurrentHashMap<String,LongAdder> freqs}, you can use
• {@code freqs.computeIfAbsent(k -> new LongAdder()).increment();}
• <p>This class and its views and iterators implement all of the
• <em>optional</em> methods of the {@link Map} and {@link Iterator}
• interfaces.
• <p>Like {@link Hashtable} but unlike {@link HashMap}, this class
• does <em>not</em> allow {@code null} to be used as a key or value.
• <p>ConcurrentHashMaps support a set of sequential and parallel bulk
• operations that, unlike most {@link Stream} methods, are designed
• to be safely, and often sensibly, applied even with maps that are
• being concurrently updated by other threads; for example, when
• computing a snapshot summary of the values in a shared registry.
• There are three kinds of operation, each with four forms, accepting
• functions with Keys, Values, Entries, and (Key, Value) arguments
• and/or return values. Because the elements of a ConcurrentHashMap
• are not ordered in any particular way, and may be processed in
• different orders in different parallel executions, the correctness
• of supplied functions should not depend on any ordering, or on any
• other objects or values that may transiently change while
• computation is in progress; and except for forEach actions, should
• ideally be side-effect-free. Bulk operations on {@link java.util.Map.Entry}
• objects do not support method {@code setValue}.
• <ul>
• <li> forEach: Perform a given action on each element.
• A variant form applies a given transformation on each element
• before performing the action.</li>
• <li> search: Return the first available non-null result of
• applying a given function on each element; skipping further
• search when a result is found.</li>
• <li> reduce: Accumulate each element. The supplied reduction
• function cannot rely on ordering (more formally, it should be
• both associative and commutative). There are five variants:
• <ul>
• <li> Plain reductions. (There is not a form of this method for
• (key, value) function arguments since there is no corresponding
• return type.)</li>
• <li> Mapped reductions that accumulate the results of a given
• function applied to each element.</li>
• <li> Reductions to scalar doubles, longs, and ints, using a
• given basis value.</li>
• </ul>
• </li>
• </ul>
• <p>These bulk operations accept a {@code parallelismThreshold}
• argument. Methods proceed sequentially if the current map size is
• estimated to be less than the given threshold. Using a value of
• {@code Long.MAX_VALUE} suppresses all parallelism. Using a value
• of {@code 1} results in maximal parallelism by partitioning into
• enough subtasks to fully utilize the {@link
• ForkJoinPool#commonPool()} that is used for all parallel
• computations. Normally, you would initially choose one of these
• extreme values, and then measure performance of using in-between
• values that trade off overhead versus throughput.
• <p>The concurrency properties of bulk operations follow
• from those of ConcurrentHashMap: Any non-null result returned
• from {@code get(key)} and related access methods bears a
• happens-before relation with the associated insertion or
• update. The result of any bulk operation reflects the
• composition of these per-element relations (but is not
• necessarily atomic with respect to the map as a whole unless it
• is somehow known to be quiescent). Conversely, because keys
• and values in the map are never null, null serves as a reliable
• atomic indicator of the current lack of any result. To
• maintain this property, null serves as an implicit basis for
• all non-scalar reduction operations. For the double, long, and
• int versions, the basis should be one that, when combined with
• any other value, returns that other value (more formally, it
• should be the identity element for the reduction). Most common
• reductions have these properties; for example, computing a sum
• with basis 0 or a minimum with basis MAX_VALUE.
• <p>Search and transformation functions provided as arguments
• should similarly return null to indicate the lack of any result
• (in which case it is not used). In the case of mapped
• reductions, this also enables transformations to serve as
• filters, returning null (or, in the case of primitive
• specializations, the identity basis) if the element should not
• be combined. You can create compound transformations and
• filterings by composing them yourself under this "null means
• there is nothing there now" rule before using them in search or
• reduce operations.
• <p>Methods accepting and/or returning Entry arguments maintain
• key-value associations. They may be useful for example when
• finding the key for the greatest value. Note that "plain" Entry
• arguments can be supplied using {@code new
• AbstractMap.SimpleEntry(k,v)}.
• <p>Bulk operations may complete abruptly, throwing an
• exception encountered in the application of a supplied
• function. Bear in mind when handling such exceptions that other
• concurrently executing functions could also have thrown
• exceptions, or would have done so if the first exception had
• not occurred.
• <p>Speedups for parallel compared to sequential forms are common
• but not guaranteed. Parallel operations involving brief functions
• on small maps may execute more slowly than sequential forms if the
• underlying work to parallelize the computation is more expensive
• than the computation itself. Similarly, parallelization may not
• lead to much actual parallelism if all processors are busy
• performing unrelated tasks.
• <p>All arguments to all task methods must be non-null.
• <p>This class is a member of the
• <a href="{@docRoot}/../technotes/guides/collections/index.html">
• Java Collections Framework</a>.
• @since 1.5
• @author Doug Lea
• @param <K> the type of keys maintained by this map
• @param <V> the type of mapped values
  */