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

*** 23,16 ***
--- 23,19 ---
   * questions.
   */
  
  package java.lang.ref;
  
+ import java.util.Objects;
  import jdk.internal.vm.annotation.IntrinsicCandidate;
  
  /**
   * Phantom reference objects, which are enqueued after the collector
   * determines that their referents may otherwise be reclaimed.  Phantom
   * references are most often used to schedule post-mortem cleanup actions.
+  * <p>
+  * The referent must be an {@linkplain Objects#isIdentityObject(Object) identity object}.
   *
   * <p> Suppose the garbage collector determines at a certain point in time
   * that an object is <a href="package-summary.html#reachability">
   * phantom reachable</a>.  At that time it will atomically clear
   * all phantom references to that object and all phantom references to

*** 85,10 ***
--- 88,12 ---
       * queue.  Such a reference will never be enqueued.
       *
       * @param referent the object the new phantom reference will refer to
       * @param q the queue with which the reference is to be registered,
       *          or {@code null} if registration is not required
+      * @throws IdentityException if the referent is not an
+      *         {@link java.util.Objects#isIdentityObject(Object) identity object}
       */
      public PhantomReference(T referent, ReferenceQueue<? super T> q) {
          super(referent, q);
      }