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

(ref) Add Reference::refersTo predicate



    • CSR
    • Status: Closed
    • P4
    • Resolution: Approved
    • 16
    • core-libs
    • None
    • source, behavioral
    • minimal
    • Hide
      A subclass of Reference could define a function of the same name, though that seems very unlikely.
      A subclass of Reference could define a function of the same name, though that seems very unlikely.
    • Java API
    • SE



      Add new java.lang.ref.Reference::refersTo method.


      There is a frequently occurring need to determine whether a Reference (still) refers to a given object, or whether it has been (possibly automatically) cleared.

      Sometimes automatic clearing detection is accomplished via the use of a ReferenceQueue, and noticing when the Reference shows up there. However, that's not always convenient.

      It also doesn't support testing whether some non-null object is the referent. That use-case arises, for example, when looking up an object in a weak-keyed hash table, where keys in a possible collision chain need to be compared to the object being looked up. One way to solve that is to use Reference::get and compare the result with the value of interest. However, such use of Reference::get interacts poorly with some GCs. Reference::get returns a strong reference to the referent. In order to ensure collector invariants are maintained and live objects are not incorrectly discarded, some collectors may treat a referent accessed by Reference::get as strongly reachable until some later collection cycle. When using such a collector, repeated checks using Reference::get could prevent a reference from ever being cleared, even though its referent object is only (weakly) reachable from the reference and occasionally, briefly, while performing those repeated checks.

      Also, such use of Reference::get only works for SoftReference and WeakReference; it does not work for PhantomReference, whose referent is inaccessible. And for SoftReferences it has the problem of introducing a recent access, potentially extending the lifetime of the referent for all collectors.


      The proposed solution is to add a new java.lang.ref.Reference::refersTo(Object o) method, which returns true if the given object is the same as the referent where o can be null to test if this reference has been cleared.


      The specification of refersTo:

       * Tests if the referent of this reference object is {@code obj}.
       * Using a {@code null} {@code obj} returns {@code true} if the
       * reference object has been cleared.
       * @param  obj the object to compare with this reference object's referent
       * @return {@code true} if {@code obj} is the referent of this reference object
       * @since 16
      public final boolean refersTo(T obj)

      In addition, add the following API note to Reference.get:

      * @apiNote
      * This method returns a strong reference to the referent. This may cause
      * the garbage collector to treat it as strongly reachable until some later
      * collection cycle.  The {@link #refersTo(Object) refersTo} method can be
      * used to avoid such strengthening when testing whether some object is
      * the referent of a reference object; that is, use {@code ref.refersTo(obj)}
      * rather than {@code ref.get() == obj}.
      * @return   The object to which this reference refers, or
      *           {@code null} if this reference object has been cleared
      * @see refersTo


      An alternative to the proposed new function would be to have the compiler intrinsify Reference.get, recognizing non-escaping uses that are compared to some other object. Such idiomatic usage could be transformed into a form that doesn't treat the referent as strongly reachable. However, relying on an optimization to produce such an application-visible behavior seems questionable. It seems better to require explicit intent via use of the new function.


        Issue Links



              kbarrett Kim Barrett
              kbarrett Kim Barrett
              Alan Bateman, Mandy Chung, Mark Reinhold
              0 Vote for this issue
              4 Start watching this issue