Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8269688

Clarify the behavior of PhantomReference::refersTo

    XMLWordPrintable

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P4
    • Resolution: Approved
    • Fix Version/s: 17
    • Component/s: core-libs
    • Labels:
      None
    • Subcomponent:
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      No behavioral change. This is spec clarification only.
    • Interface Kind:
      Java API
    • Scope:
      SE

      Description

      Summary

      Clarify in the spec of PhantomReference that refersTo can be used for phantom reference.

      Problem

      Reference::refersTo behaves the same for soft, weak, and phantom references whereas PhantomReference::get always returns null which is different than soft and weak references. The specification of PhantomReference should be improved to clarify the behavior of refersTo.

      Solution

      Clarify the specification of PhantomReference to make it clear that refersTo can be used for phantom references. With refersTo, phantom references if not registered in a reference queue are not completely useless and the javadoc of the constructor is updated to reflect that.

      Specification

      --- a/src/java.base/share/classes/java/lang/ref/PhantomReference.java
      +++ b/src/java.base/share/classes/java/lang/ref/PhantomReference.java
      @@ -43,6 +43,8 @@ import jdk.internal.vm.annotation.IntrinsicCandidate;
        * <p> In order to ensure that a reclaimable object remains so, the referent of
        * a phantom reference may not be retrieved: The {@code get} method of a
        * phantom reference always returns {@code null}.
      + * The {@link #refersTo(Object) refersTo} method can be used to test
      + * whether some object is the referent of a phantom reference.
        *
        * @author   Mark Reinhold
        * @since    1.2
      @@ -75,9 +77,7 @@ public class PhantomReference<T> extends Reference<T> {
            * is registered with the given queue.
            *
            * <p> It is possible to create a phantom reference with a {@code null}
      -     * queue, but such a reference is completely useless: Its {@code get}
      -     * method will always return {@code null} and, since it does not have a queue,
      -     * it will never be enqueued.
      +     * 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,

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              mchung Mandy Chung
              Reporter:
              webbuggrp Webbug Group
              Reviewed By:
              Alan Bateman, Kim Barrett
              Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: