Class MapMaker
- java.lang.Object
-
- com.google.common.collect.MapMaker
-
@GwtCompatible(emulated=true) public final class MapMaker extends java.lang.Object
A builder ofConcurrentMap
instances that can have keys or values automatically wrapped in weak references.Usage example:
ConcurrentMap<Request, Stopwatch> timers = new MapMaker() .concurrencyLevel(4) .weakKeys() .makeMap();
These features are all optional;
new MapMaker().makeMap()
returns a valid concurrent map that behaves similarly to aConcurrentHashMap
.The returned map is implemented as a hash table with similar performance characteristics to
ConcurrentHashMap
. It supports all optional operations of theConcurrentMap
interface. It does not permit null keys or values.Note: by default, the returned map uses equality comparisons (the
equals
method) to determine equality for keys or values. However, ifweakKeys()
was specified, the map uses identity (==
) comparisons instead for keys. Likewise, ifweakValues()
was specified, the map uses identity comparisons for values.The view collections of the returned map have weakly consistent iterators. This means that they are safe for concurrent use, but if other threads modify the map after the iterator is created, it is undefined which of these changes, if any, are reflected in that iterator. These iterators never throw
ConcurrentModificationException
.If
weakKeys()
orweakValues()
are requested, it is possible for a key or value present in the map to be reclaimed by the garbage collector. Entries with reclaimed keys or values may be removed from the map on each map modification or on occasional map accesses; such entries may be counted byMap.size()
, but will never be visible to read or write operations. A partially-reclaimed entry is never exposed to the user. AnyMap.Entry
instance retrieved from the map's entry set is a snapshot of that entry's state at the time of retrieval; such entries do, however, supportMap.Entry.setValue(V)
, which simply callsMap.put(K, V)
on the entry's key.The maps produced by
MapMaker
are serializable, and the deserialized maps retain all the configuration properties of the original map. During deserialization, if the original map had used weak references, the entries are reconstructed as they were, but it's not unlikely they'll be quickly garbage-collected before they are ever accessed.new MapMaker().weakKeys().makeMap()
is a recommended replacement forWeakHashMap
, but note that it compares keys using object identity whereasWeakHashMap
usesObject.equals(java.lang.Object)
.- Since:
- 2.0
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description (package private) static class
MapMaker.Dummy
A dummy singleton value type used byInterners
.
-
Field Summary
Fields Modifier and Type Field Description (package private) int
concurrencyLevel
private static int
DEFAULT_CONCURRENCY_LEVEL
private static int
DEFAULT_INITIAL_CAPACITY
(package private) int
initialCapacity
(package private) Equivalence<java.lang.Object>
keyEquivalence
(package private) MapMakerInternalMap.Strength
keyStrength
(package private) static int
UNSET_INT
(package private) boolean
useCustomMap
(package private) MapMakerInternalMap.Strength
valueStrength
-
Constructor Summary
Constructors Constructor Description MapMaker()
Constructs a newMapMaker
instance with default settings, including strong keys, strong values, and no automatic eviction of any kind.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description MapMaker
concurrencyLevel(int concurrencyLevel)
Guides the allowed concurrency among update operations.(package private) int
getConcurrencyLevel()
(package private) int
getInitialCapacity()
(package private) Equivalence<java.lang.Object>
getKeyEquivalence()
(package private) MapMakerInternalMap.Strength
getKeyStrength()
(package private) MapMakerInternalMap.Strength
getValueStrength()
MapMaker
initialCapacity(int initialCapacity)
Sets the minimum total size for the internal hash tables.(package private) MapMaker
keyEquivalence(Equivalence<java.lang.Object> equivalence)
Sets a customEquivalence
strategy for comparing keys.<K,V>
java.util.concurrent.ConcurrentMap<K,V>makeMap()
Builds a thread-safe map.(package private) MapMaker
setKeyStrength(MapMakerInternalMap.Strength strength)
(package private) MapMaker
setValueStrength(MapMakerInternalMap.Strength strength)
java.lang.String
toString()
Returns a string representation for this MapMaker instance.MapMaker
weakKeys()
Specifies that each key (not value) stored in the map should be wrapped in aWeakReference
(by default, strong references are used).MapMaker
weakValues()
Specifies that each value (not key) stored in the map should be wrapped in aWeakReference
(by default, strong references are used).
-
-
-
Field Detail
-
DEFAULT_INITIAL_CAPACITY
private static final int DEFAULT_INITIAL_CAPACITY
- See Also:
- Constant Field Values
-
DEFAULT_CONCURRENCY_LEVEL
private static final int DEFAULT_CONCURRENCY_LEVEL
- See Also:
- Constant Field Values
-
UNSET_INT
static final int UNSET_INT
- See Also:
- Constant Field Values
-
useCustomMap
boolean useCustomMap
-
initialCapacity
int initialCapacity
-
concurrencyLevel
int concurrencyLevel
-
keyStrength
MapMakerInternalMap.Strength keyStrength
-
valueStrength
MapMakerInternalMap.Strength valueStrength
-
keyEquivalence
Equivalence<java.lang.Object> keyEquivalence
-
-
Method Detail
-
keyEquivalence
@GwtIncompatible MapMaker keyEquivalence(Equivalence<java.lang.Object> equivalence)
Sets a customEquivalence
strategy for comparing keys.By default, the map uses
Equivalence.identity()
to determine key equality whenweakKeys()
is specified, andEquivalence.equals()
otherwise. The only place this is used is inInterners.WeakInterner
.
-
getKeyEquivalence
Equivalence<java.lang.Object> getKeyEquivalence()
-
initialCapacity
public MapMaker initialCapacity(int initialCapacity)
Sets the minimum total size for the internal hash tables. For example, if the initial capacity is60
, and the concurrency level is8
, then eight segments are created, each having a hash table of size eight. Providing a large enough estimate at construction time avoids the need for expensive resizing operations later, but setting this value unnecessarily high wastes memory.- Throws:
java.lang.IllegalArgumentException
- ifinitialCapacity
is negativejava.lang.IllegalStateException
- if an initial capacity was already set
-
getInitialCapacity
int getInitialCapacity()
-
concurrencyLevel
public MapMaker concurrencyLevel(int concurrencyLevel)
Guides the allowed concurrency among update operations. 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 assignment of entries to these partitions is not necessarily uniform, the actual concurrency observed may 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 permits only one thread to modify the map at a time, but since read operations can proceed concurrently, this still yields higher concurrency than full synchronization. Defaults to 4.Note: Prior to Guava release 9.0, the default was 16. It is possible the default will change again in the future. If you care about this value, you should always choose it explicitly.
- Throws:
java.lang.IllegalArgumentException
- ifconcurrencyLevel
is nonpositivejava.lang.IllegalStateException
- if a concurrency level was already set
-
getConcurrencyLevel
int getConcurrencyLevel()
-
weakKeys
@GwtIncompatible public MapMaker weakKeys()
Specifies that each key (not value) stored in the map should be wrapped in aWeakReference
(by default, strong references are used).Warning: when this method is used, the resulting map will use identity (
==
) comparison to determine equality of keys, which is a technical violation of theMap
specification, and may not be what you expect.- Throws:
java.lang.IllegalStateException
- if the key strength was already set- See Also:
WeakReference
-
setKeyStrength
MapMaker setKeyStrength(MapMakerInternalMap.Strength strength)
-
getKeyStrength
MapMakerInternalMap.Strength getKeyStrength()
-
weakValues
@GwtIncompatible public MapMaker weakValues()
Specifies that each value (not key) stored in the map should be wrapped in aWeakReference
(by default, strong references are used).Weak values will be garbage collected once they are weakly reachable. This makes them a poor candidate for caching.
Warning: when this method is used, the resulting map will use identity (
==
) comparison to determine equality of values. This technically violates the specifications of the methodscontainsValue
,remove(Object, Object)
andreplace(K, V, V)
, and may not be what you expect.- Throws:
java.lang.IllegalStateException
- if the value strength was already set- See Also:
WeakReference
-
setValueStrength
MapMaker setValueStrength(MapMakerInternalMap.Strength strength)
-
getValueStrength
MapMakerInternalMap.Strength getValueStrength()
-
makeMap
public <K,V> java.util.concurrent.ConcurrentMap<K,V> makeMap()
Builds a thread-safe map. This method does not alter the state of thisMapMaker
instance, so it can be invoked again to create multiple independent maps.The bulk operations
putAll
,equals
, andclear
are not guaranteed to be performed atomically on the returned map. Additionally,size
andcontainsValue
are implemented as bulk read operations, and thus may fail to observe concurrent writes.- Returns:
- a serializable concurrent map having the requested features
-
toString
public java.lang.String toString()
Returns a string representation for this MapMaker instance. The exact form of the returned string is not specified.- Overrides:
toString
in classjava.lang.Object
-
-