Guava: Google Core Libraries for Java 32.1.2-jre · com.google.common.collect.MapMaker

A builder of ConcurrentMap 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 a ConcurrentHashMap.

The returned map is implemented as a hash table with similar performance characteristics to ConcurrentHashMap. It supports all optional operations of the ConcurrentMap 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, if weakKeys was specified, the map uses identity (==) comparisons instead for keys. Likewise, if weakValues 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 or weakValues 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 by Map#size, but will never be visible to read or write operations. A partially-reclaimed entry is never exposed to the user. Any Map.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, support Map.Entry#setValue, which simply calls Map#put 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 for java.util.WeakHashMap, but note that it compares keys using object identity whereas WeakHashMap uses Object#equals.

Nested and Inner Type Summary

Modifier and Type	Class and Description
pack-priv static enum	MapMaker.Dummy A dummy singleton value type used by `Interners`.

Field Summary

Modifier and Type	Field and Description
pack-priv int	concurrencyLevel
private static final int	DEFAULT_CONCURRENCY_LEVEL
private static final int	DEFAULT_INITIAL_CAPACITY
pack-priv int	initialCapacity
pack-priv Equivalence<Object>	keyEquivalence
pack-priv MapMakerInternalMap.Strength	keyStrength
pack-priv static final int	UNSET_INT
pack-priv boolean	useCustomMap
pack-priv MapMakerInternalMap.Strength	valueStrength

Constructor Summary

Access	Constructor and Description
public	MapMaker() Constructs a new `MapMaker` instance with default settings, including strong keys, strong values, and no automatic eviction of any kind.

Method Summary

Modifier and Type	Method and Description
public MapMaker	concurrencyLevel(int concurrencyLevel) Guides the allowed concurrency among update operations.
pack-priv int	getConcurrencyLevel()
pack-priv int	getInitialCapacity()
pack-priv Equivalence<Object>	getKeyEquivalence()
pack-priv MapMakerInternalMap.Strength	getKeyStrength()
pack-priv MapMakerInternalMap.Strength	getValueStrength()
public MapMaker	initialCapacity(int initialCapacity) Sets the minimum total size for the internal hash tables.
pack-priv MapMaker	keyEquivalence(Equivalence<Object> equivalence) Sets a custom `Equivalence` strategy for comparing keys.
public <K, V> ConcurrentMap<K, V>	Returns: a serializable concurrent map having the requested features makeMap() Builds a thread-safe map.
pack-priv MapMaker	setKeyStrength(MapMakerInternalMap.Strength strength)
pack-priv MapMaker	setValueStrength(MapMakerInternalMap.Strength strength)
public String	toString() Overrides java.lang.Object.toString. Returns a string representation for this MapMaker instance.
public MapMaker	weakKeys() Specifies that each key (not value) stored in the map should be wrapped in a `WeakReference` (by default, strong references are used).
public MapMaker	weakValues() Specifies that each value (not key) stored in the map should be wrapped in a `WeakReference` (by default, strong references are used).

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll wait wait wait

Field Detail

concurrencyLevel	back to summary
pack-priv int concurrencyLevel

DEFAULT_CONCURRENCY_LEVEL	back to summary
private static final int DEFAULT_CONCURRENCY_LEVEL

DEFAULT_INITIAL_CAPACITY	back to summary
private static final int DEFAULT_INITIAL_CAPACITY

initialCapacity	back to summary
pack-priv int initialCapacity

keyEquivalence	back to summary
pack-priv Equivalence<Object> keyEquivalence Annotations @CheckForNull

keyStrength	back to summary
pack-priv MapMakerInternalMap.Strength keyStrength Annotations @CheckForNull

UNSET_INT	back to summary
pack-priv static final int UNSET_INT

useCustomMap	back to summary
pack-priv boolean useCustomMap

valueStrength	back to summary
pack-priv MapMakerInternalMap.Strength valueStrength Annotations @CheckForNull

Constructor Detail

MapMaker	back to summary
public MapMaker() Constructs a new `MapMaker` instance with default settings, including strong keys, strong values, and no automatic eviction of any kind.

Method Detail

concurrencyLevel back to summary

concurrencyLevel	back to summary
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. Annotations @CanIgnoreReturnValue Exceptions IllegalArgumentException: if `concurrencyLevel` is nonpositive IllegalStateException: if a concurrency level was already set

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.

Annotations

@CanIgnoreReturnValue

Exceptions

IllegalArgumentException:: if concurrencyLevel is nonpositive
IllegalStateException:: if a concurrency level was already set

getConcurrencyLevel	back to summary
pack-priv int getConcurrencyLevel()

getInitialCapacity	back to summary
pack-priv int getInitialCapacity()

getKeyEquivalence	back to summary
pack-priv Equivalence<Object> getKeyEquivalence()

getKeyStrength	back to summary
pack-priv MapMakerInternalMap.Strength getKeyStrength()

getValueStrength	back to summary
pack-priv MapMakerInternalMap.Strength getValueStrength()

initialCapacity back to summary

initialCapacity	back to summary
public MapMaker initialCapacity(int initialCapacity) Sets the minimum total size for the internal hash tables. For example, if the initial capacity is `60`, and the concurrency level is `8`, 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. Annotations @CanIgnoreReturnValue Exceptions IllegalArgumentException: if `initialCapacity` is negative IllegalStateException: if an initial capacity was already set

public MapMaker initialCapacity(int initialCapacity)

Sets the minimum total size for the internal hash tables. For example, if the initial capacity is 60, and the concurrency level is 8, 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.

Annotations

@CanIgnoreReturnValue

Exceptions

IllegalArgumentException:: if initialCapacity is negative
IllegalStateException:: if an initial capacity was already set

keyEquivalence back to summary

keyEquivalence	back to summary
pack-priv MapMaker keyEquivalence(Equivalence<Object> equivalence) Sets a custom `Equivalence` strategy for comparing keys. By default, the map uses `Equivalence#identity` to determine key equality when `weakKeys` is specified, and `Equivalence#equals()` otherwise. The only place this is used is in `Interners.WeakInterner`. Annotations @CanIgnoreReturnValue @GwtIncompatible

pack-priv MapMaker keyEquivalence(Equivalence<Object> equivalence)

Sets a custom Equivalence strategy for comparing keys.

By default, the map uses Equivalence#identity to determine key equality when weakKeys is specified, and Equivalence#equals() otherwise. The only place this is used is in Interners.WeakInterner.

Annotations

@CanIgnoreReturnValue
@GwtIncompatible

makeMap back to summary

makeMap	back to summary
public <K, V> ConcurrentMap<K, V> makeMap() Builds a thread-safe map. This method does not alter the state of this `MapMaker` instance, so it can be invoked again to create multiple independent maps. The bulk operations `putAll`, `equals`, and `clear` are not guaranteed to be performed atomically on the returned map. Additionally, `size` and `containsValue` are implemented as bulk read operations, and thus may fail to observe concurrent writes. Returns:ConcurrentMap<K, V> a serializable concurrent map having the requested features

public <K, V> ConcurrentMap<K, V> makeMap()

Builds a thread-safe map. This method does not alter the state of this MapMaker instance, so it can be invoked again to create multiple independent maps.

The bulk operations putAll, equals, and clear are not guaranteed to be performed atomically on the returned map. Additionally, size and containsValue are implemented as bulk read operations, and thus may fail to observe concurrent writes.

Returns:ConcurrentMap<K, V>: a serializable concurrent map having the requested features

setKeyStrength	back to summary
pack-priv MapMaker setKeyStrength(MapMakerInternalMap.Strength strength)

setValueStrength	back to summary
pack-priv MapMaker setValueStrength(MapMakerInternalMap.Strength strength)

toString	back to summary
public String toString() Overrides java.lang.Object.toString. Returns a string representation for this MapMaker instance. The exact form of the returned string is not specified. Returns:String Doc from java.lang.Object.toString. a string representation of the object. Annotations @Override

toString

back to summary

public String toString()

Overrides java.lang.Object.toString.

Returns a string representation for this MapMaker instance. The exact form of the returned string is not specified.

Returns:String

Doc from java.lang.Object.toString.

a string representation of the object.

Annotations

@Override

weakKeys back to summary

weakKeys	back to summary
public MapMaker weakKeys() Specifies that each key (not value) stored in the map should be wrapped in a `WeakReference` (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 the `Map` specification, and may not be what you expect. Annotations @CanIgnoreReturnValue @GwtIncompatible Exceptions IllegalStateException: if the key strength was already set See Also `WeakReference`

public MapMaker weakKeys()

Specifies that each key (not value) stored in the map should be wrapped in a WeakReference (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 the Map specification, and may not be what you expect.

Annotations

@CanIgnoreReturnValue
@GwtIncompatible

Exceptions

IllegalStateException:: if the key strength was already set

See Also

WeakReference

weakValues back to summary

weakValues	back to summary
public MapMaker weakValues() Specifies that each value (not key) stored in the map should be wrapped in a `WeakReference` (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 methods `containsValue`, `remove(Object, Object)` and `replace(K, V, V)`, and may not be what you expect. Annotations @CanIgnoreReturnValue @GwtIncompatible Exceptions IllegalStateException: if the value strength was already set See Also `WeakReference`

public MapMaker weakValues()

Specifies that each value (not key) stored in the map should be wrapped in a WeakReference (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 methods containsValue, remove(Object, Object) and replace(K, V, V), and may not be what you expect.

Annotations

@CanIgnoreReturnValue
@GwtIncompatible

Exceptions

IllegalStateException:: if the value strength was already set

See Also

WeakReference

Modifier and Type	Method and Description
public static MapMaker.Dummy	valueOf(String name)
public static MapMaker.Dummy[]	values()

public final Class MapMaker

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

pack-priv final Enum MapMaker.Dummy

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail