1 /*
   2  * Copyright (c) 1998, 2015, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any

  26 /**
  27  * Provides reference-object classes, which support a limited degree
  28  * of interaction with the garbage collector.  A program may use a
  29  * reference object to maintain a reference to some other object in
  30  * such a way that the latter object may still be reclaimed by the
  31  * collector.  A program may also arrange to be notified some time
  32  * after the collector has determined that the reachability of a given
  33  * object has changed.
  34  *
  35  *<h2>Package Specification</h2>
  36  *
  37  * A <em>reference object</em> encapsulates a reference to some other
  38  * object so that the reference itself may be examined and manipulated
  39  * like any other object.  Three types of reference objects are
  40  * provided, each weaker than the last: <em>soft</em>, <em>weak</em>,
  41  * and <em>phantom</em>.  Each type corresponds to a different level
  42  * of reachability, as defined below.  Soft references are for
  43  * implementing memory-sensitive caches, weak references are for
  44  * implementing canonicalizing mappings that do not prevent their keys
  45  * (or values) from being reclaimed, and phantom references are for
  46  * scheduling pre-mortem cleanup actions in a more flexible way than
  47  * is possible with the Java finalization mechanism.
  48  * Post-mortem cleanup actions can be registered and managed by a
  49  * {@link java.lang.ref.Cleaner}.
  50  *
  51  * <p> Each reference-object type is implemented by a subclass of the
  52  * abstract base {@link java.lang.ref.Reference} class.
  53  * An instance of one of these subclasses encapsulates a single
  54  * reference to a particular object, called the <em>referent</em>.
  55  * Every reference object provides methods for getting and clearing
  56  * the reference.  Aside from the clearing operation reference objects
  57  * are otherwise immutable, so no {@code set} operation is
  58  * provided.  A program may further subclass these subclasses, adding
  59  * whatever fields and methods are required for its purposes, or it
  60  * may use these subclasses without change.
  61  *
  62  * <h3>Notification</h3>
  63  *
  64  * A program may request to be notified of changes in an object's
  65  * reachability by <em>registering</em> an appropriate reference
  66  * object with a <em>reference queue</em> at the time the reference
  67  * object is created.  Some time after the garbage collector

   1 /*
   2  * Copyright (c) 1998, 2016, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any

  26 /**
  27  * Provides reference-object classes, which support a limited degree
  28  * of interaction with the garbage collector.  A program may use a
  29  * reference object to maintain a reference to some other object in
  30  * such a way that the latter object may still be reclaimed by the
  31  * collector.  A program may also arrange to be notified some time
  32  * after the collector has determined that the reachability of a given
  33  * object has changed.
  34  *
  35  *<h2>Package Specification</h2>
  36  *
  37  * A <em>reference object</em> encapsulates a reference to some other
  38  * object so that the reference itself may be examined and manipulated
  39  * like any other object.  Three types of reference objects are
  40  * provided, each weaker than the last: <em>soft</em>, <em>weak</em>,
  41  * and <em>phantom</em>.  Each type corresponds to a different level
  42  * of reachability, as defined below.  Soft references are for
  43  * implementing memory-sensitive caches, weak references are for
  44  * implementing canonicalizing mappings that do not prevent their keys
  45  * (or values) from being reclaimed, and phantom references are for
  46  * scheduling post-mortem cleanup actions.

  47  * Post-mortem cleanup actions can be registered and managed by a
  48  * {@link java.lang.ref.Cleaner}.
  49  *
  50  * <p> Each reference-object type is implemented by a subclass of the
  51  * abstract base {@link java.lang.ref.Reference} class.
  52  * An instance of one of these subclasses encapsulates a single
  53  * reference to a particular object, called the <em>referent</em>.
  54  * Every reference object provides methods for getting and clearing
  55  * the reference.  Aside from the clearing operation reference objects
  56  * are otherwise immutable, so no {@code set} operation is
  57  * provided.  A program may further subclass these subclasses, adding
  58  * whatever fields and methods are required for its purposes, or it
  59  * may use these subclasses without change.
  60  *
  61  * <h3>Notification</h3>
  62  *
  63  * A program may request to be notified of changes in an object's
  64  * reachability by <em>registering</em> an appropriate reference
  65  * object with a <em>reference queue</em> at the time the reference
  66  * object is created.  Some time after the garbage collector