An advanced hash table supporting configurable garbage collection semantics
of keys and values, optional referential-equality, full concurrency of
retrievals, and adjustable expected concurrency for updates.
This table is designed around specific advanced use-cases. If there is any
doubt whether this table is for you, you most likely should be using
java.util.concurrent.ConcurrentHashMap instead.
This table supports strong, weak, and soft keys and values. By default keys
are weak, and values are strong. Such a configuration offers similar behavior
to
java.util.WeakHashMap, entries of this table are periodically
removed once their corresponding keys are no longer referenced outside of
this table. In other words, this table will not prevent a key from being
discarded by the garbage collector. Once a key has been discarded by the
collector, the corresponding entry is no longer visible to this table;
however, the entry may occupy space until a future table operation decides to
reclaim it. For this reason, summary functions such as size and
isEmpty might return a value greater than the observed number of
entries. In order to support a high level of concurrency, stale entries are
only reclaimed during blocking (usually mutating) operations.
Enabling soft keys allows entries in this table to remain until their space
is absolutely needed by the garbage collector. This is unlike weak keys which
can be reclaimed as soon as they are no longer referenced by a normal strong
reference. The primary use case for soft keys is a cache, which ideally
occupies memory that is not in use for as long as possible.
By default, values are held using a normal strong reference. This provides
the commonly desired guarantee that a value will always have at least the
same life-span as it's key. For this reason, care should be taken to ensure
that a value never refers, either directly or indirectly, to its key, thereby
preventing reclamation. If this is unavoidable, then it is recommended to use
the same reference type in use for the key. However, it should be noted that
non-strong values may disappear before their corresponding key.
While this table does allow the use of both strong keys and values, it is
recommended you use
java.util.concurrent.ConcurrentHashMap for such a
configuration, since it is optimized for that case.
Just like
java.util.concurrent.ConcurrentHashMap, this class obeys
the same functional specification as
java.util.Hashtable, and
includes versions of methods corresponding to each method of
Hashtable. However, even though all operations are thread-safe,
retrieval operations do not entail locking, and there is
not any support for locking the entire table in a way that
prevents all access. This class is fully interoperable with
Hashtable in programs that rely on its thread safety but not on
its synchronization details.
Retrieval operations (including get) generally do not block, so they
may overlap with update operations (including put and
remove). Retrievals reflect the results of the most recently
completed update operations holding upon their onset. For
aggregate operations such as putAll and clear,
concurrent retrievals may reflect insertion or removal of only some entries.
Similarly, Iterators 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 not throw
ConcurrentModificationException. However, iterators are designed to
be used by only one thread at a time.
The allowed concurrency among update operations is guided by the optional
concurrencyLevel constructor argument (default 16),
which is used as a hint for internal sizing. The table is internally
partitioned to try to permit the indicated number of concurrent updates
without contention. Because placement in hash tables is essentially random,
the actual concurrency will vary. Ideally, you should choose a value to
accommodate as many threads as will ever concurrently modify the table. Using
a significantly higher value than you need can waste space and time, and a
significantly lower value can lead to thread contention. But overestimates
and underestimates within an order of magnitude do not usually have much
noticeable impact. A value of one is appropriate when it is known that only
one thread will modify and all others will only read. Also, resizing this or
any other kind of hash table is a relatively slow operation, so, when
possible, it is a good idea that you provide estimates of expected table sizes in
constructors.
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.
This class is a member of the
Java Collections Framework.