8314480: Memory ordering spec updates in java.lang.ref

src/java.base/share/classes/java/lang/ref/Cleaner.java

@@ -215,6 +215,14 @@ public static Cleaner create(ThreadFactory threadFactory) {
      * Refer to the <a href="#compatible-cleaners">API Note</a> above for
      * cautions about the behavior of cleaning actions.
      *
+     * <p>The object being registered is kept strongly-reachable (and therefore not eligible
+     * for cleaning) during the register() method.
+     *
+     * <p>Memory consistency effects: Actions in a thread prior to calling
+     * Cleaner.register()
+     * <a href="{@docRoot}/java.base/java/util/concurrent/package-summary.html#MemoryVisibility"><i>happen-before</i></a>
+     * the cleaning action is run by the Cleaner's thread.
+     *
      * @param obj   the object to monitor
      * @param action a {@code Runnable} to invoke when the object becomes phantom reachable
      * @return a {@code Cleanable} instance

src/java.base/share/classes/java/lang/ref/Reference.java

@@ -388,11 +388,22 @@ boolean refersToImpl(T obj) {
     private native boolean refersTo0(Object o);
 
     /**
-     * Clears this reference object.  Invoking this method will not cause this
-     * object to be enqueued.
+     * Clears this reference object. Invoking this method does not enqueue this
+     * object, and the garbage collector will no longer enqueue this object once
+     * the referent reaches the designated reachability level.
+     * <p>
+     * There is a potential race condition with the garbage collector. When this
+     * method is called, the garbage collector may already be in the process of
+     * (or already completed) clearing and/or enqueueing this reference.
+     *
+     * Avoid this race by ensuring the referent remains strongly-reachable until
+     * after the call to clear(), using {@link #reachabilityFence(Object)} if necessary.
+     *
      *
      * <p> This method is invoked only by Java code; when the garbage collector
-     * clears references it does so directly, without invoking this method.
+     * clears references it does so directly, without invoking this method. The
+     * {@link #enqueue} method also clears references directly, without invoking
+     * this method.
      */
     public void clear() {
         clear0();
@@ -470,11 +481,29 @@ public boolean isEnqueued() {
     }
 
     /**
-     * Clears this reference object and adds it to the queue with which
-     * it is registered, if any.
+     * Clears this reference object, then attempts to add it to the queue with
+     * which it is registered, if any.
      *
-     * <p> This method is invoked only by Java code; when the garbage collector
+     * <p>If this reference was already enqueued (by the garbage collector, or a
+     * previous call to {@code enqueue}), this method is <b><i>not successful</i></b>,
+     * and returns false.
+     *
+     * <p>Memory consistency effects: Actions in a thread prior to calling
+     * {@code enqueue} <b><i>successfully</i></b>
+     * <a href="{@docRoot}/java.base/java/util/concurrent/package-summary.html#MemoryVisibility"><i>happen-before</i></a>
+     * the reference is removed from the queue by {@link ReferenceQueue#poll}
+     * or {@link ReferenceQueue#remove}.
+     *
+     * <p>This method is invoked only by Java code; when the garbage collector
      * enqueues references it does so directly, without invoking this method.
+     *
+     * @apiNote
+     * Use of this method allows the registered queue's
+     * {@link ReferenceQueue#poll} and {@link ReferenceQueue#remove} methods
+     * to return this reference even though the referent is still strongly
+     * reachable. That is, before the referent has reached the expected
+     * reachability level.
+
      *
      * @return   {@code true} if this reference object was successfully
      *           enqueued; {@code false} if it was already enqueued or if
@@ -511,29 +540,32 @@ protected Object clone() throws CloneNotSupportedException {
     }
 
     /**
-     * Ensures that the object referenced by the given reference remains
+     * Ensures that the given object remains
      * <a href="package-summary.html#reachability"><em>strongly reachable</em></a>,
-     * regardless of any prior actions of the program that might otherwise cause
-     * the object to become unreachable; thus, the referenced object is not
+     * regardless of any other actions of the program that might otherwise cause
+     * the object to become unreachable; thus, the object is not
      * reclaimable by garbage collection at least until after the invocation of
-     * this method.  Invocation of this method does not itself initiate garbage
-     * collection or finalization.
+     * this method. References to the given object will not be cleared (or
+     * enqueued, if applicable) by the garbage collector until after invocation
+     * of this method.
+     * Invocation of this method does not itself initiate reference processing,
+     * garbage collection, or finalization.
      *
      * <p> This method establishes an ordering for <em>strong reachability</em>
      * with respect to garbage collection.  It controls relations that are
      * otherwise only implicit in a program -- the reachability conditions
-     * triggering garbage collection.  This method is designed for use in
-     * uncommon situations of premature finalization where using
-     * {@code synchronized} blocks or methods, or using other synchronization
-     * facilities are not possible or do not provide the desired control.  This
-     * method is applicable only when reclamation may have visible effects,
-     * which is possible for objects with finalizers (See Section {@jls 12.6}
-     * of <cite>The Java Language Specification</cite>) that
-     * are implemented in ways that rely on ordering control for
-     * correctness.
+     * triggering garbage collection.  This method is applicable only
+     * when reclamation may have visible effects,
+     * such as for objects with finalizers or that use Cleaner.
+     *
+     * <p>Memory consistency effects: Actions in a thread prior to calling
+     * {@code reachabilityFence(x)}
+     * <a href="{@docRoot}/java.base/java/util/concurrent/package-summary.html#MemoryVisibility"><i>happen-before</i></a>
+     * the garbage collector clears any reference to {code x}.
+
      *
      * @apiNote
-     * Finalization may occur whenever the virtual machine detects that no
+     * Reference processing or finalization may occur whenever the virtual machine detects that no
      * reference to an object will ever be stored in the heap: The garbage
      * collector may reclaim an object even if the fields of that object are
      * still in use, so long as the object has otherwise become unreachable.

src/java.base/share/classes/java/lang/ref/ReferenceQueue.java

@@ -34,6 +34,13 @@
 /**
  * Reference queues, to which registered reference objects are appended by the
  * garbage collector after the appropriate reachability changes are detected.
+ *
+ * <p>Memory consistency effects: The enqueueing of a reference on a
+ * queue (by the garbage collector, or by a successful call to {@link Reference#enqueue})
+ * <a href="{@docRoot}/java.base/java/util/concurrent/package-summary.html#MemoryVisibility"><i>happens-before</i></a>
+ * the reference is removed from the queue by {@link ReferenceQueue#poll} or
+ * {@link ReferenceQueue#remove}.
+ *
  * @param <T> the type of the reference object
  *
  * @author   Mark Reinhold
@@ -173,6 +180,12 @@ boolean enqueue(Reference<? extends T> r) { /* Called only by Reference class */
      * available without further delay then it is removed from the queue and
      * returned.  Otherwise this method immediately returns {@code null}.
      *
+     * @apiNote
+     * If the returned reference was added to this queue by a call to
+     * {@link Reference#enqueue()} instead of by the garbage collector, its
+     * former referent (which has since been cleared) could still be strongly
+     * reachable.
+     *
      * @return  A reference object, if one was immediately available,
      *          otherwise {@code null}
      */
@@ -194,6 +207,12 @@ public Reference<? extends T> poll() {
      * <p> This method does not offer real-time guarantees: It schedules the
      * timeout as if by invoking the {@link Object#wait(long)} method.
      *
+     * @apiNote
+     * If the returned reference was added to this queue by a call to
+     * {@link Reference#enqueue()} instead of by the garbage collector, its
+     * former referent (which has since been cleared) could still be strongly
+     * reachable.
+     *
      * @param  timeout  If positive, block for up to {@code timeout}
      *                  milliseconds while waiting for a reference to be
      *                  added to this queue.  If zero, block indefinitely.
@@ -225,6 +244,12 @@ public Reference<? extends T> remove(long timeout) throws InterruptedException {
      * Removes the next reference object in this queue, blocking until one
      * becomes available.
      *
+     * @apiNote
+     * If the returned reference was added to this queue by a call to
+     * {@link Reference#enqueue()} instead of by the garbage collector, its
+     * former referent (which has since been cleared) could still be strongly
+     * reachable.
+     *
      * @return A reference object, blocking until one becomes available
      * @throws  InterruptedException  If the wait is interrupted
      */

src/java.base/share/classes/java/lang/ref/package-info.java

@@ -93,6 +93,28 @@
  * structure, this check will add little overhead to the hashtable
  * access methods.
  *
+ * <h3>Memory Consistency Properties</h3>
+ * Certain interactions between the garbage collector, references, and reference
+ * queues form
+ * <a href="{@docRoot}/java.base/java/util/concurrent/package-summary.html#MemoryVisibility"><i>happens-before</i></a>
+ * relationships:
+ *
+ * <ul>
+ *
+ * <li> Actions in a thread prior to calling
+ * {@link Reference#reachabilityFence Reference.reachabilityFence(x)}
+ * <i>happen-before</i> the garbage collector clears any reference to {@code x}.</li>
+ *
+ * <li>The clearing of a reference by the garbage collector <i>happens-before</i>
+ * the garbage collector enqueues the reference.</li>
+ *
+ * <li> The enqueueing of a reference (by the garbage collector, or
+ * by a successful call to {@link Reference#enqueue}) <i>happens-before</i>
+ * the reference is removed from the queue by {@link ReferenceQueue#poll} or
+ * {@link ReferenceQueue#remove}.</li>
+ *
+ * </ul>
+ *
  * <a id="reachability"></a>
  * <h3>Reachability</h3>
  *