[jbosscache-commits] JBoss Cache SVN: r5471 - experimental/jsr166/src/jsr166y.

Author: jason.greene(a)jboss.com Date: 2008-03-27 17:03:09 -0400 (Thu, 27 Mar 2008) New Revision: 5471 Modified: experimental/jsr166/src/jsr166y/ConcurrentReferenceHashMap.java Log: Update docs Modified: experimental/jsr166/src/jsr166y/ConcurrentReferenceHashMap.java =================================================================== --- experimental/jsr166/src/jsr166y/ConcurrentReferenceHashMap.java 2008-03-27 17:09:21 UTC (rev 5470) +++ experimental/jsr166/src/jsr166y/ConcurrentReferenceHashMap.java 2008-03-27 21:03:09 UTC (rev 5471) @@ -20,6 +20,7 @@ import java.util.Enumeration; import java.util.HashMap; import java.util.Hashtable; +import java.util.IdentityHashMap; import java.util.Iterator; import java.util.Map; import java.util.NoSuchElementException; @@ -27,9 +28,17 @@ import java.util.concurrent.locks.ReentrantLock; /** - * A hash table with <em>weak keys</em>, full concurrency of retrievals, and - * adjustable expected concurrency for updates. Similar to - * {@link java.util.WeakHashMap}, entries of this table are periodically + * 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 + * {@link 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 {@link 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 @@ -40,23 +49,34 @@ * entries. In order to support a high level of concurrency, stale entries are * only reclaimed during blocking (usually mutating) operations. * - * While keys in this table are only held using a weak reference, values are - * held using a normal strong reference. This provides the 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 weak - * values are desired, one can simply use a {@link WeakReference} for the value - * type. + * 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. * - * Just like {@link java.util.ConcurrentHashMap}, this class obeys the same - * functional specification as {@link java.util.Hashtable}, and includes - * versions of methods corresponding to each method of <tt>Hashtable</tt>. - * 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 <tt>Hashtable</tt> in programs that rely on its - * thread safety but not on its synchronization details. + * 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 to use {@link java.util.concurrent.ConcurrentHashMap} for this + * configuration, since it is optimized for that case. + * + * Just like {@link java.util.concurrent.ConcurrentHashMap}, this class obeys + * the same functional specification as {@link java.util.Hashtable}, and + * includes versions of methods corresponding to each method of + * <tt>Hashtable</tt>. 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 + * <tt>Hashtable</tt> in programs that rely on its thread safety but not on + * its synchronization details. + * * <p> * Retrieval operations (including <tt>get</tt>) generally do not block, so * may overlap with update operations (including <tt>put</tt> and @@ -113,10 +133,26 @@ * each of which itself is a concurrently readable hash table. */ - public static enum ReferenceType {STRONG, WEAK, SOFT}; + /** + * An option specifying which Java reference type should be used to refer + * to a key and/or value. + */ + public static enum ReferenceType { + /** Indicates a normal Java strong reference should be used */ + STRONG, + /** Indicates a {@link WeakReference} should be used */ + WEAK, + /** Indicates a {@link SoftReference} should be used */ + SOFT + }; - public static enum Option {IDENTITY_COMPARISONS}; + public static enum Option { + /** Indicates that referential-equality (== instead of .equals()) should + * be used when locating keys. This offers similar behavior to {@link IdentityHashMap} */ + IDENTITY_COMPARISONS + }; + /* ---------------- Constants -------------- */ static final ReferenceType DEFAULT_KEY_TYPE = ReferenceType.WEAK; @@ -193,7 +229,7 @@ /** * Applies a supplemental hash function to a given hashCode, which * defends against poor quality hash functions. This is critical - * because ConcurrentWeakHashMap uses power-of-two length hash tables, + * because ConcurrentReferenceHashMap uses power-of-two length hash tables, * that otherwise encounter collisions for hashCodes that do not * differ in lower or upper bits. */ @@ -257,7 +293,7 @@ } /** - * ConcurrentWeakHashMap list entry. Note that this is never exported + * ConcurrentReferenceHashMap list entry. Note that this is never exported * out as a user-visible Map.Entry. * * Because the value field is volatile, not final, it is legal wrt @@ -767,7 +803,10 @@ /** * Creates a new, empty map with the specified initial - * capacity, load factor and concurrency level. + * capacity, reference types, load factor and concurrency level. + * + * Behavioral changing options such as {@link Option#IDENTITY_COMPARISONS} + * can also be specified. * * @param initialCapacity the initial capacity. The implementation * performs internal sizing to accommodate this many elements. @@ -777,6 +816,9 @@ * @param concurrencyLevel the estimated number of concurrently * updating threads. The implementation performs internal sizing * to try to accommodate this many threads. + * @param keyType the reference type to use for keys + * @param valueType the reference type to use for values + * @param options the behavioral options * @throws IllegalArgumentException if the initial capacity is * negative or the load factor or concurrencyLevel are * nonpositive. @@ -842,7 +884,8 @@ /** * Creates a new, empty map with the specified initial capacity - * and load factor and with the default concurrencyLevel (16). + * and load factor and with the default reference types (weak keys, + * strong values), and concurrencyLevel (16). * * @param initialCapacity The implementation performs internal * sizing to accommodate this many elements. @@ -858,9 +901,28 @@ this(initialCapacity, loadFactor, DEFAULT_CONCURRENCY_LEVEL); } + /** + * Creates a new, empty map with the specified initial capacity, + * reference types and with default load factor (0.75) and concurrencyLevel (16). + * + * @param initialCapacity the initial capacity. The implementation + * performs internal sizing to accommodate this many elements. + * @param keyType the reference type to use for keys + * @param valueType the reference type to use for values + * @throws IllegalArgumentException if the initial capacity of + * elements is negative. + */ + public ConcurrentReferenceHashMap(int initialCapacity, + ReferenceType keyType, ReferenceType valueType) { + this(initialCapacity, DEFAULT_LOAD_FACTOR, DEFAULT_CONCURRENCY_LEVEL, + keyType, valueType, null); + } + + /** * Creates a new, empty map with the specified initial capacity, - * and with default load factor (0.75) and concurrencyLevel (16). + * and with default reference types (weak keys, strong values), + * load factor (0.75) and concurrencyLevel (16). * * @param initialCapacity the initial capacity. The implementation * performs internal sizing to accommodate this many elements. @@ -873,6 +935,7 @@ /** * Creates a new, empty map with a default initial capacity (16), + * reference types (weak keys, strong values), default * load factor (0.75) and concurrencyLevel (16). */ public ConcurrentReferenceHashMap() { @@ -1195,6 +1258,15 @@ for (int i = 0; i < segments.length; ++i) segments[i].clear(); } + + /** + * Removes any entries, whose keys have been finalized + */ + public void purgeStaleEntries() { + for (int i = 0; i < segments.length; ++i) + segments[i].removeStale(); + } + /** * Returns a {@link Set} view of the keys contained in this map. @@ -1533,7 +1605,7 @@ /* ---------------- Serialization Support -------------- */ /** - * Save the state of the <tt>ConcurrentWeakHashMap</tt> instance to a + * Save the state of the <tt>ConcurrentReferenceHashMap</tt> instance to a * stream (i.e., serialize it). * @param s the stream * @serialData @@ -1568,7 +1640,7 @@ } /** - * Reconstitute the <tt>ConcurrentWeakHashMap</tt> instance from a + * Reconstitute the <tt>ConcurrentReferenceHashMap</tt> instance from a * stream (i.e., deserialize it). * @param s the stream */