You are viewing a plain text version of this content. The canonical link for it is here.
Posted to derby-commits@db.apache.org by ka...@apache.org on 2007/09/14 12:20:36 UTC
svn commit: r575607 -
/db/derby/code/trunk/java/engine/org/apache/derby/impl/services/cache/CacheEntry.java
Author: kahatlen
Date: Fri Sep 14 03:20:35 2007
New Revision: 575607
URL: http://svn.apache.org/viewvc?rev=575607&view=rev
Log:
DERBY-2911 (partial) Updated class javadoc for CacheEntry with
information about its different states and how to lock more than one
entry without risking deadlocks.
Modified:
db/derby/code/trunk/java/engine/org/apache/derby/impl/services/cache/CacheEntry.java
Modified: db/derby/code/trunk/java/engine/org/apache/derby/impl/services/cache/CacheEntry.java
URL: http://svn.apache.org/viewvc/db/derby/code/trunk/java/engine/org/apache/derby/impl/services/cache/CacheEntry.java?rev=575607&r1=575606&r2=575607&view=diff
==============================================================================
--- db/derby/code/trunk/java/engine/org/apache/derby/impl/services/cache/CacheEntry.java (original)
+++ db/derby/code/trunk/java/engine/org/apache/derby/impl/services/cache/CacheEntry.java Fri Sep 14 03:20:35 2007
@@ -29,9 +29,49 @@
/**
* Class representing an entry in the cache. It is used by
* <code>ConcurrentCache</code>. When a thread invokes any of the methods in
- * this class, except <code>lock()</code>, it must have called
- * <code>lock()</code> to ensure exclusive access to the entry. No thread
- * should ever lock more than one entry in order to prevent deadlocks.
+ * this class, except <code>lock()</code>, it must first have called
+ * <code>lock()</code> to ensure exclusive access to the entry.
+ *
+ * <p>
+ *
+ * When no thread holds the lock on the entry, it must be in one of the
+ * following states:
+ *
+ * <dl>
+ *
+ * <dt>Uninitialized</dt> <dd>The entry object has just been constructed. In
+ * this state, <code>isValid()</code> and <code>isKept()</code> return
+ * <code>false</code>, and <code>getCacheable()</code> returns
+ * <code>null</code>. As long as the entry is in this state, the reference to
+ * the object should not be made available to other threads than the one that
+ * created it, since there is no way for other threads to see the difference
+ * between an uninitialized entry and a removed entry.</dd>
+ *
+ * <dt>Unkept</dt> <dd>In this state, the entry object contains a reference to
+ * a <code>Cacheable</code> and the keep count is zero. <code>isValid()</code>
+ * returns <code>true</code> and <code>isKept()</code> returns
+ * <code>false</code> in this state. <code>getCacheable()</code> returns a
+ * non-null value.<dd>
+ *
+ * <dt>Kept</dt> <dd>Same as the unkept state, except that the keep count is
+ * positive and <code>isKept()</code> returns <code>true</code>.</dd>
+ *
+ * <dt>Removed</dt> <dd>The entry has been removed from the cache. In this
+ * state, <code>isValid()</code> and <code>isKept()</code> return
+ * <code>false</code>, and <code>getCacheable()</code> returns
+ * <code>null</code>. When an entry has entered the removed state, it cannot be
+ * transitioned back to any of the other states.</dd>
+ *
+ * </dl>
+ *
+ * <p>
+ *
+ * To prevent deadlocks, each thread should normally lock only one entry at a
+ * time. In some cases it is legitimate to hold the lock on two entries, for
+ * instance if an entry must be evicted to make room for a new entry. If this
+ * is the case, exactly one of the two entries must be in the uninitialized
+ * state, and the uninitialized entry must be locked before the lock on the
+ * other entry can be requested.
*/
final class CacheEntry {
/** Mutex which guards the internal state of the entry. */