src/java.base/share/classes/java/util/concurrent/locks/StampedLock.java

8211283: Miscellaneous changes imported from jsr166 CVS 2018-11
Reviewed-by: martin, chegar

*** 63,97 ****
   *   waiting for non-exclusive access, returning a stamp that can be
   *   used in method {@link #unlockRead} to release the lock. Untimed
   *   and timed versions of {@code tryReadLock} are also provided.
   *
   *  <li><b>Optimistic Reading.</b> Method {@link #tryOptimisticRead}
!  *   returns a non-zero stamp only if the lock is not currently held
!  *   in write mode. Method {@link #validate} returns true if the lock
!  *   has not been acquired in write mode since obtaining a given
!  *   stamp.  This mode can be thought of as an extremely weak version
!  *   of a read-lock, that can be broken by a writer at any time.  The
!  *   use of optimistic mode for short read-only code segments often
!  *   reduces contention and improves throughput.  However, its use is
!  *   inherently fragile.  Optimistic read sections should only read
!  *   fields and hold them in local variables for later use after
!  *   validation. Fields read while in optimistic mode may be wildly
!  *   inconsistent, so usage applies only when you are familiar enough
!  *   with data representations to check consistency and/or repeatedly
!  *   invoke method {@code validate()}.  For example, such steps are
!  *   typically required when first reading an object or array
!  *   reference, and then accessing one of its fields, elements or
!  *   methods.
   *
   * </ul>
   *
   * <p>This class also supports methods that conditionally provide
   * conversions across the three modes. For example, method {@link
   * #tryConvertToWriteLock} attempts to "upgrade" a mode, returning
   * a valid write stamp if (1) already in writing mode (2) in reading
!  * mode and there are no other readers or (3) in optimistic mode and
!  * the lock is available. The forms of these methods are designed to
   * help reduce some of the code bloat that otherwise occurs in
   * retry-based designs.
   *
   * <p>StampedLocks are designed for use as internal utilities in the
   * development of thread-safe components. Their use relies on
--- 63,98 ----
   *   waiting for non-exclusive access, returning a stamp that can be
   *   used in method {@link #unlockRead} to release the lock. Untimed
   *   and timed versions of {@code tryReadLock} are also provided.
   *
   *  <li><b>Optimistic Reading.</b> Method {@link #tryOptimisticRead}
!  *   returns a non-zero stamp only if the lock is not currently held in
!  *   write mode.  Method {@link #validate} returns true if the lock has not
!  *   been acquired in write mode since obtaining a given stamp, in which
!  *   case all actions prior to the most recent write lock release
!  *   happen-before actions following the call to {@code tryOptimisticRead}.
!  *   This mode can be thought of as an extremely weak version of a
!  *   read-lock, that can be broken by a writer at any time.  The use of
!  *   optimistic read mode for short read-only code segments often reduces
!  *   contention and improves throughput.  However, its use is inherently
!  *   fragile.  Optimistic read sections should only read fields and hold
!  *   them in local variables for later use after validation. Fields read
!  *   while in optimistic read mode may be wildly inconsistent, so usage
!  *   applies only when you are familiar enough with data representations to
!  *   check consistency and/or repeatedly invoke method {@code validate()}.
!  *   For example, such steps are typically required when first reading an
!  *   object or array reference, and then accessing one of its fields,
!  *   elements or methods.
   *
   * </ul>
   *
   * <p>This class also supports methods that conditionally provide
   * conversions across the three modes. For example, method {@link
   * #tryConvertToWriteLock} attempts to "upgrade" a mode, returning
   * a valid write stamp if (1) already in writing mode (2) in reading
!  * mode and there are no other readers or (3) in optimistic read mode
!  * and the lock is available. The forms of these methods are designed to
   * help reduce some of the code bloat that otherwise occurs in
   * retry-based designs.
   *
   * <p>StampedLocks are designed for use as internal utilities in the
   * development of thread-safe components. Their use relies on
*** 127,136 ****
--- 128,150 ----
   * {@link ReadWriteLock} interfaces. However, a StampedLock may be
   * viewed {@link #asReadLock()}, {@link #asWriteLock()}, or {@link
   * #asReadWriteLock()} in applications requiring only the associated
   * set of functionality.
   *
+  * <p><b>Memory Synchronization.</b> Methods with the effect of
+  * successfully locking in any mode have the same memory
+  * synchronization effects as a <em>Lock</em> action described in
+  * <a href="https://docs.oracle.com/javase/specs/jls/se8/html/jls-17.html#jls-17.4">
+  * Chapter 17 of <cite>The Java&trade; Language Specification</cite></a>.
+  * Methods successfully unlocking in write mode have the same memory
+  * synchronization effects as an <em>Unlock</em> action.  In optimistic
+  * read usages, actions prior to the most recent write mode unlock action
+  * are guaranteed to happen-before those following a tryOptimisticRead
+  * only if a later validate returns true; otherwise there is no guarantee
+  * that the reads between tryOptimisticRead and validate obtain a
+  * consistent snapshot.
+  *
   * <p><b>Sample Usage.</b> The following illustrates some usage idioms
   * in a class that maintains simple two-dimensional points. The sample
   * code illustrates some try/catch conventions even though they are
   * not strictly needed here because no exceptions can occur in their
   * bodies.