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

(ref) Clear phantom reference as soft and weak references do

    XMLWordPrintable

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P3
    • Resolution: Approved
    • Fix Version/s: 8u42
    • Component/s: core-libs
    • Labels:
    • Subcomponent:
    • Compatibility Kind:
      behavioral
    • Compatibility Risk:
      minimal
    • Compatibility Risk Description:
      Hide
       This change has minimal compatibility risk.

      1) `PhantomReference::get` always returns null to ensure that the referent
         of a phantom reference cannot be retrieved.

      2) An object becomes phantom reachable after it has been finalized. Although
         this change may cause the phantom-reachable objects to be GC'ed earlier --
         previously the referent is kept alive until PhantomReference objects
         are GC'ed or cleared by the application -- existing code would only depend
         on the PhantomReference being enqueued rather than when the referent is
         freed from the heap.
      Show
       This change has minimal compatibility risk. 1) `PhantomReference::get` always returns null to ensure that the referent    of a phantom reference cannot be retrieved. 2) An object becomes phantom reachable after it has been finalized. Although    this change may cause the phantom-reachable objects to be GC'ed earlier --    previously the referent is kept alive until PhantomReference objects    are GC'ed or cleared by the application -- existing code would only depend    on the PhantomReference being enqueued rather than when the referent is    freed from the heap.
    • Interface Kind:
      Java API
    • Scope:
      SE

      Description

      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:
      

        Attachments

          Issue Links

            Activity

              People

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

                Dates

                Created:
                Updated:
                Resolved: