| /* |
| * Copyright (c) 1998, 2016, 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 |
| * particular file as subject to the "Classpath" exception as provided |
| * by Oracle in the LICENSE file that accompanied this code. |
| * |
| * This code is distributed in the hope that it will be useful, but WITHOUT |
| * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| * version 2 for more details (a copy is included in the LICENSE file that |
| * accompanied this code). |
| * |
| * You should have received a copy of the GNU General Public License version |
| * 2 along with this work; if not, write to the Free Software Foundation, |
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| * |
| * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
| * or visit www.oracle.com if you need additional information or have any |
| * questions. |
| */ |
| |
| /** |
| * Provides reference-object classes, which support a limited degree |
| * of interaction with the garbage collector. A program may use a |
| * reference object to maintain a reference to some other object in |
| * such a way that the latter object may still be reclaimed by the |
| * collector. A program may also arrange to be notified some time |
| * after the collector has determined that the reachability of a given |
| * object has changed. |
| * |
| *<h2>Package Specification</h2> |
| * |
| * A <em>reference object</em> encapsulates a reference to some other |
| * object so that the reference itself may be examined and manipulated |
| * like any other object. Three types of reference objects are |
| * provided, each weaker than the 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 post-mortem cleanup actions. |
| * Post-mortem cleanup actions can be registered and managed by a |
| * {@link java.lang.ref.Cleaner}. |
| * |
| * <p> Each reference-object type is implemented by a subclass of the |
| * abstract base {@link java.lang.ref.Reference} 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 clearing |
| * the reference. Aside from the clearing operation reference objects |
| * are otherwise immutable, so no {@code set} operation is |
| * provided. A program may further subclass these subclasses, adding |
| * whatever fields and methods are required for its purposes, or it |
| * may use these subclasses without change. |
| * |
| * <h3>Notification</h3> |
| * |
| * 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 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 {@link java.lang.ref.ReferenceQueue} class. |
| * |
| * <p> The relationship between a registered reference object and its |
| * queue is one-sided. That is, a queue does not keep track of the |
| * references that are registered with it. If a registered reference |
| * becomes unreachable itself, then it will never be enqueued. It is |
| * the responsibility of the program using reference objects to ensure |
| * that the objects remain reachable for as long as the program is |
| * interested in their referents. |
| * |
| * <p> While some programs will choose to dedicate a thread to |
| * removing reference objects from one or more queues and processing |
| * them, this is by no means necessary. A tactic that often works |
| * well is to examine a reference queue in the course of performing |
| * some other fairly-frequent action. For example, a hashtable that |
| * uses weak references to implement weak keys could poll its |
| * reference queue each time the table is accessed. This is how the |
| * {@link java.util.WeakHashMap} class works. Because |
| * the {@link java.lang.ref.ReferenceQueue#poll |
| * ReferenceQueue.poll} method simply checks an internal data |
| * structure, this check will add little overhead to the hashtable |
| * access methods. |
| * |
| * <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: |
| * |
| * <ul> |
| * |
| * <li> An object is <em>strongly reachable</em> if it can be reached |
| * by some thread without traversing any reference objects. A |
| * newly-created object is strongly reachable by the thread that |
| * created it. |
| * |
| * <li> An object is <em>softly reachable</em> if it is not strongly |
| * reachable but can be reached by traversing a soft reference. |
| * |
| * <li> An object is <em>weakly reachable</em> if it is neither |
| * strongly nor softly reachable but can be reached by traversing a |
| * weak reference. When the weak references to a weakly-reachable |
| * object are cleared, the object becomes eligible for finalization. |
| * |
| * <li> An object is <em>phantom reachable</em> if it is neither |
| * strongly, softly, nor weakly reachable, it has been finalized, and |
| * some phantom reference refers to it. |
| * |
| * <li> Finally, an object is <em>unreachable</em>, and therefore |
| * eligible for reclamation, when it is not reachable in any of the |
| * above ways. |
| * |
| * </ul> |
| * |
| * @author Mark Reinhold |
| * @since 1.2 |
| */ |
| package java.lang.ref; |
