[jbosscache-commits] JBoss Cache SVN: r5471 - experimental/jsr166/src/jsr166y.
jbosscache-commits at lists.jboss.org
jbosscache-commits at lists.jboss.org
Thu Mar 27 17:03:09 EDT 2008
Author: jason.greene at 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
*/
More information about the jbosscache-commits
mailing list