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

rev 50108 : [mq]: tschatzl_1

@@ -74,25 +74,27 @@
      *
      * Unregistered: Not associated with a queue when created.
      * queue = ReferenceQueue.NULL.
      *
      * The collector only needs to examine the referent field and the
-     * discovered field to determine whether a normal Reference object needs
-     * special treatment.  If the referent is non-null and not known to be
-     * live, then it may need to be discovered for possible later
-     * notification.  But if the discovered field is non-null, then either (1)
-     * it has already been discovered, or (2) it is in the pending list.
+     * discovered field to determine whether a normal (non-FinalReference)
+     * Reference object needs special treatment.  If the referent is non-null
+     * and not known to be live, then it may need to be discovered for
+     * possible later notification.  But if the discovered field is non-null,
+     * then either (1) it has already been discovered, or (2) it is in the
+     * pending list.
      *
-     * FinalReference differs from other references, because a FinalReference
-     * is not cleared when notified.  The referent being null or not cannot be
-     * used to distinguish between the active state and pending or inactive
-     * states.  However, FinalReferences do not support enqueue().  Instead,
-     * the next field of a FinalReference object is set to the object when it
-     * is added to the pending list, and the use of this as the value of next
-     * in the enqueued and dequeued states maintains the non-active state.  An
-     * additional check that the next field is null is required to determine
-     * that a FinalReference object is active.
+     * FinalReference (which exists to support finalization, which was
+     * deprecated in JDK 9) differs from normal references, because a
+     * FinalReference is not cleared when notified.  The referent being null
+     * or not cannot be used to distinguish between the active state and
+     * pending or inactive states.  However, FinalReferences do not support
+     * enqueue().  Instead, the next field of a FinalReference object is set
+     * to "this" when it is added to the pending list.  The use of "this"
+     * as the value of next in the enqueued and dequeued states maintains the
+     * non-active state.  An additional check that the next field is null is
+     * required to determine that a FinalReference object is active.
      *
      * Initial states:
      *   active/registered
      *   active/unregistered [1]
      *