Summary

Make phantom references be automatically cleared by the garbage collector, like soft and weak references.

Problem

Phantom references are not automatically cleared by the garbage collector when they are enqueued, unlike soft and weak references. When an object R (the "referent") becomes phantom reachable, the phantom reference that refers to R is not cleared, although it does not provide any way to access to the referent because PhantomReference::get always returns null. Clearing phantom references like soft and weak references would provide a strong guarantee that it is impossible to access the referent when a phantom reference is enqueued.

Solution

Make phantom references be automatically cleared by the garbage collector, like soft and weak references, such that it is impossible to access the referent when its phantom reference is enqueued (since the phantom reference has been cleared).

Specification

--- a/src/share/classes/java/lang/ref/PhantomReference.java
+++ b/src/share/classes/java/lang/ref/PhantomReference.java
    @@ -1,7 +1,7 @@
 /*
- * Copyright (c) 1997, 2003, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2015, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
  * under the terms of the GNU General Public License version 2 only, as
  * published by the Free Software Foundation.  Oracle designates this
@@ -27,27 +27,24 @@


 /**
  * Phantom reference objects, which are enqueued after the collector
  * determines that their referents may otherwise be reclaimed.  Phantom
- * references are most often used for scheduling pre-mortem cleanup actions in
- * a more flexible way than is possible with the Java finalization mechanism.
+ * references are most often used to schedule post-mortem cleanup actions.
  *
- * <p> If the garbage collector determines at a certain point in time that the
- * referent of a phantom reference is <a
- * href="package-summary.html#reachability">phantom reachable</a>, then at that
- * time or at some later time it will enqueue the reference.
+ * <p> Suppose the garbage collector determines at a certain point in time
+ * that an object is <a href="package-summary.html#reachability">
+ * phantom reachable</a>.  At that time it will atomically clear
+ * all phantom references to that object and all phantom references to
+ * any other phantom-reachable objects from which that object is reachable.
+ * At the same time or at some later time it will enqueue those newly-cleared
+ * phantom references that are registered with reference queues.
  *
  * <p> In order to ensure that a reclaimable object remains so, the referent of
  * a phantom reference may not be retrieved: The <code>get</code> method of a
  * phantom reference always returns <code>null</code>.
  *
- * <p> Unlike soft and weak references, phantom references are not
- * automatically cleared by the garbage collector as they are enqueued.  An
- * object that is reachable via phantom references will remain so until all
- * such references are cleared or themselves become unreachable.
- *
  * @author   Mark Reinhold
  * @since    1.2
  */

 public class PhantomReference<T> extends Reference<T> {
@@ -67,12 +64,12 @@
      * Creates a new phantom reference that refers to the given object and
      * is registered with the given queue.
      *
      * <p> It is possible to create a phantom reference with a <tt>null</tt>
      * queue, but such a reference is completely useless: Its <tt>get</tt>
-     * method will always return null and, since it does not have a queue, it
-     * will never be enqueued.
+     * method will always return {@code null} and, since it does not have a queue,
+     * it 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,
      *          or <tt>null</tt> if registration is not required
      */

--- a/src/share/classes/java/lang/ref/package.html
+++ b/src/share/classes/java/lang/ref/package.html

@@ -44,12 +44,11 @@
 last: <em>soft</em>, <em>weak</em>, and <em>phantom</em>.  Each type
 corresponds to a different level of reachability, as defined below.  Soft
 references are for implementing memory-sensitive caches, weak references are
 for implementing canonicalizing mappings that do not prevent their keys (or
 values) from being reclaimed, and phantom references are for scheduling
-pre-mortem cleanup actions in a more flexible way than is possible with the
-Java finalization mechanism.
+post-mortem cleanup actions.

 <p> Each reference-object type is implemented by a subclass of the abstract
 base <code>{@link java.lang.ref.Reference}</code> class.  An instance of one of
 these subclasses encapsulates a single reference to a particular object, called
 the <em>referent</em>.  Every reference object provides methods for getting and
@@ -64,13 +63,14 @@

 A program may request to be notified of changes in an object's reachability by
 <em>registering</em> an appropriate reference object with a <em>reference
 queue</em> at the time the reference object is created.  Some time after the
 garbage collector determines that the reachability of the referent has changed
-to the value corresponding to the type of the reference, it will add the
-reference to the associated queue.  At this point, the reference is considered
-to be <em>enqueued</em>.  The program may remove references from a queue either
+to the value corresponding to the type of the reference, it will clear the
+reference and add it to the associated queue.  At this point, the
+reference is considered to be <em>enqueued</em>.  The program may remove
+references from a queue either
 by polling or by blocking until a reference becomes available.  Reference
 queues are implemented by the <code>{@link java.lang.ref.ReferenceQueue}</code>
 class.

 <p> The relationship between a registered reference object and its queue is
@@ -89,21 +89,10 @@
 java.util.WeakHashMap}</code> class works.  Because the <code>{@link
 java.lang.ref.ReferenceQueue#poll ReferenceQueue.poll}</code> method simply
 checks an internal data structure, this check will add little overhead to the
 hashtable access methods.

-
<h2>-<h3>Automatically-cleared references</h3></h2>

-Soft and weak references are automatically cleared by the collector before
-being added to the queues with which they are registered, if any.  Therefore
-soft and weak references need not be registered with a queue in order to be
-useful, while phantom references do.  An object that is reachable via phantom
-references will remain so until all such references are cleared or themselves
<h2>-become unreachable.</h2>

-
 <a name="reachability"></a>
 <h3>Reachability</h3>

 Going from strongest to weakest, the different levels of reachability reflect
 the life cycle of an object.  They are operationally defined as follows: