| /* |
| * Copyright (c) 1998, 2003, 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 |
| * pre-mortem cleanup actions in a more flexible way than is possible with the |
| * Java finalization mechanism. |
| * |
| * <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 |
| * clearing the reference. Aside from the clearing operation reference objects |
| * are otherwise immutable, so no <code>set</code> 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 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 |
| * 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 |
| * 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 <code>{@link |
| * 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. |
| * |
| * |
| * <h3>Automatically-cleared references</h3> |
| * |
| * 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 |
| * become unreachable. |
| * |
| * |
| * <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; |