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

(ref) Add Reference::refersTo predicate

XMLWordPrintable

    • Icon: CSR CSR
    • Resolution: Approved
    • Icon: P4 P4
    • 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.
      Show
      A subclass of Reference could define a function of the same name, though that seems very unlikely.
    • Java API
    • SE

      Summary

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

      Problem

      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.

      Solution

      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.

      Specification

      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

      Alternatives

      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.

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

              Created:
              Updated:
              Resolved: