8052260: Reference.isEnqueued() spec does not match the long-standing behavior returning true iff it's in the ref queue

Reviewed-by: kbarrett, alanb

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

@@ -411,14 +411,35 @@ public abstract class Reference<T> {
     /* -- Queue operations -- */
 
     /**
-     * Tells whether or not this reference object has been enqueued, either by
-     * the program or by the garbage collector.  If this reference object was
-     * not registered with a queue when it was created, then this method will
-     * always return {@code false}.
+     * Tests if this reference object is in its associated queue, if any.
+     * This method returns {@code true} only if all of the following conditions
+     * are met:
+     * <ul>
+     * <li>this reference object was registered with a queue when it was created; and
+     * <li>the garbage collector has added this reference object to the queue
+     *     or {@link #enqueue()} is called; and
+     * <li>this reference object is not yet removed from the queue.
+     * </ul>
+     * Otherwise, this method returns {@code false}.
+     * This method may return {@code false} if this reference object has been cleared
+     * but not enqueued due to the race condition.
      *
-     * @return   {@code true} if and only if this reference object has
-     *           been enqueued
+     * @deprecated
+     * This method was originally specified to test if a reference object has
+     * been cleared and enqueued but was never implemented to do this test.
+     * This method could be misused due to the inherent race condition
+     * or without an associated {@code ReferenceQueue}.
+     * An application relying on this method to release critical resources
+     * could cause serious performance issue.
+     * An application should use {@link ReferenceQueue} to reliably determine
+     * what reference objects that have been enqueued or
+     * {@link #refersTo(Object) refersTo(null)} to determine if this reference
+     * object has been cleared.
+     *
+     * @return   {@code true} if and only if this reference object is
+     *           in its associated queue (if any).
      */
+    @Deprecated(since="16")
     public boolean isEnqueued() {
         return (this.queue == ReferenceQueue.ENQUEUED);
     }