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

(ref) Reference::enqueue method should clear the reference object before enqueuing

    XMLWordPrintable

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P2
    • Resolution: Approved
    • Fix Version/s: 8u42
    • Component/s: core-libs
    • Labels:
    • Subcomponent:
    • Compatibility Kind:
      behavioral
    • Compatibility Risk:
      low
    • Compatibility Risk Description:
      Hide
      When a reference object is enqueued, `Reference::get` will return null.
      Existing code calling `Reference::get` on an enqueued reference object
      may get NPE if it expects it be non-null.

      Surveying the usage of `Reference::enqueue` in Oracle's internal Maven
      repository shows that `Reference::clear` and `Reference::enqueue` are usually called as a pair (either `clear` before `enqueue`, or vice versa). In addition, existing code which polls
      the enqueued reference from a `ReferenceQueue` usually expects that the
      reference object has been cleared.

      Accordingly, we believe that the compatibility risk of automatically clearing before enqueuing is low. The likelihood of existing applications being impacted by this change should be very low.

      Additional note for this backport:
      There has been no issue reported by customers that their applications/libraries are impacted by this change since Java 9 when this spec change was made.
      Show
      When a reference object is enqueued, `Reference::get` will return null. Existing code calling `Reference::get` on an enqueued reference object may get NPE if it expects it be non-null. Surveying the usage of `Reference::enqueue` in Oracle's internal Maven repository shows that `Reference::clear` and `Reference::enqueue` are usually called as a pair (either `clear` before `enqueue`, or vice versa). In addition, existing code which polls the enqueued reference from a `ReferenceQueue` usually expects that the reference object has been cleared. Accordingly, we believe that the compatibility risk of automatically clearing before enqueuing is low. The likelihood of existing applications being impacted by this change should be very low. Additional note for this backport: There has been no issue reported by customers that their applications/libraries are impacted by this change since Java 9 when this spec change was made.
    • Interface Kind:
      Java API
    • Scope:
      SE

      Description

      Summary

      Update Reference::enqueue to clear the reference object before enqueuing.

      Problem

      Soft, weak, and phantom references are all automatically cleared references. This means that when the garbage collector determines that an object (the "referent") reaches its reachability state, the garbage collector will (1) clear the reference object that refers to the referent, and (2) put the reference object in the pending list for enqueuing.

      User code can call Reference::enqueue to explicitly enqueue a reference object on its registered queue, if any. However, Reference::enqueue does not clear the reference object and therefore the referent can still be accessed until such time as the reference object is GC'ed or Reference::clear is explicitly called.

      This CSR proposes to change the spec of Reference::enqueue to clear the reference object before enqueuing, so to align with the behavior of garbage collectors.

      Solution

      CCC-8071507 made phantom references be automatically cleared before enqueuing by the garbage collector, like soft and weak references.

      The current request proposes to change Reference::enqueue to have the same semantics as how the garbage collector enqueues the reference object, i.e., clear the reference.

      Specification

      one-line spec change of Reference::enqueue method:

               /**
          -     * Adds this reference object to the queue with which it is registered,
          -     * if any.
          +     * Clears this reference object and adds it to the queue with which
          +     * it is registered, if any.
                *
                * <p> This method is invoked only by Java code; when the garbage collector
                * enqueues references it does so directly, without invoking this method.
                *
                * @return   <code>true</code> if this reference object was successfully
                *           enqueued; <code>false</code> if it was already enqueued or if
                *           it was not registered with a queue when it was created
                */
               public boolean enqueue() {

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              poonam Poonam Bajaj Parhar
              Reporter:
              mchung Mandy Chung
              Reviewed By:
              Kim Barrett, Mandy Chung
              Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: