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() {