--- jsr166/src/jsr166e/StampedLock.java	2012/10/12 16:48:15	1.4
+++ jsr166/src/jsr166e/StampedLock.java	2012/10/12 23:11:14	1.7
@@ -26,7 +26,7 @@ import java.util.concurrent.TimeUnit;
  *   in method {@link #unlockWrite} to release the lock. Untimed and
  *   timed versions of {@code tryWriteLock} are also provided. When
  *   the lock is held in write mode, no read locks may be obtained,
- *   and all observer validations will fail.  </li>
+ *   and all optimistic read validations will fail.  </li>
  *
  *  <li><b>Reading.</b> Method {@link #readLock} possibly blocks
  *   waiting for non-exclusive access, returning a stamp that can be
@@ -76,8 +76,11 @@ import java.util.concurrent.TimeUnit;
  * into initial unlocked state, so they are not useful for remote
  * locking.
  *
- * <p>The scheduling policy of StampedLock does not consistently prefer
- * readers over writers or vice versa.
+ * <p>The scheduling policy of StampedLock does not consistently
+ * prefer readers over writers or vice versa.  A zero return from any
+ * "try" method for acquiring or converting locks does carry any
+ * information about the state of the lock; a subsequent invocation
+ * may succeed.
  *
  * <p><b>Sample Usage.</b> The following illustrates some usage idioms
  * in a class that maintains simple two-dimensional points. The sample
@@ -87,7 +90,7 @@ import java.util.concurrent.TimeUnit;
  *
  *  <pre>{@code
  * class Point {
- *   private volatile double x, y;
+ *   private double x, y;
  *   private final StampedLock sl = new StampedLock();
  *
  *   void move(double deltaX, double deltaY) { // an exclusively locked method
@@ -119,7 +122,7 @@ import java.util.concurrent.TimeUnit;
  *   }
  *
  *   double distanceFromOriginV2() { // combines code paths
- *     for (long stamp = sl.optimisticRead(); ; stamp = sl.readLock()) {
+ *     for (long stamp = sl.tryOptimisticRead(); ; stamp = sl.readLock()) {
  *       double currentX, currentY;
  *       try {
  *         currentX = x;
@@ -237,7 +240,7 @@ public class StampedLock implements java
     /** Maximum number of retries before blocking on acquisition */
     private static final int SPINS = (NCPU > 1) ? 1 << 6 : 1;
 
-    /** Maximum number of retries before re-blocking on write lock */
+    /** Maximum number of retries before re-blocking */
     private static final int MAX_HEAD_SPINS = (NCPU > 1) ? 1 << 12 : 1;
 
     /** The period for yielding when waiting for overflow spinlock */
@@ -329,7 +332,7 @@ public class StampedLock implements java
 
     /**
      * Exclusively acquires the lock if it is available within the
-     * given time and the current thread has not been interrupted
+     * given time and the current thread has not been interrupted.
      *
      * @return a stamp that can be used to unlock or convert mode,
      * or zero if the lock is not available
@@ -419,7 +422,7 @@ public class StampedLock implements java
 
     /**
      * Non-exclusively acquires the lock if it is available within the
-     * given time and the current thread has not been interrupted
+     * given time and the current thread has not been interrupted.
      *
      * @return a stamp that can be used to unlock or convert mode,
      * or zero if the lock is not available
@@ -1103,8 +1106,7 @@ public class StampedLock implements java
     /**
      * If node non-null, forces cancel status and unsplices from queue
      * if possible, by traversing entire queue looking for cancelled
-     * nodes, cleaning out all at head, but stopping upon first
-     * encounter otherwise.
+     * nodes.
      */
     private long cancelReader(RNode node, boolean interrupted) {
         Thread w;
@@ -1119,7 +1121,7 @@ public class StampedLock implements java
                     }
                     else {
                         U.compareAndSwapObject(pred, RNEXT, p, q);
-                        break;
+                        p = pred.next;
                     }
                 }
                 else {