1 /* 2 * Copyright (c) 1998, 2003, 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 23 * questions. 24 */ 25 26 27 /** 28 * Provides reference-object classes, which support a limited degree of 29 * interaction with the garbage collector. A program may use a reference object 30 * to maintain a reference to some other object in such a way that the latter 31 * object may still be reclaimed by the collector. A program may also arrange to 32 * be notified some time after the collector has determined that the reachability 33 * of a given object has changed. 34 * 35 * 36 * <h2>Package Specification</h2> 37 * 38 * A <em>reference object</em> encapsulates a reference to some other object so 39 * that the reference itself may be examined and manipulated like any other 40 * object. Three types of reference objects are provided, each weaker than the 41 * last: <em>soft</em>, <em>weak</em>, and <em>phantom</em>. Each type 42 * corresponds to a different level of reachability, as defined below. Soft 43 * references are for implementing memory-sensitive caches, weak references are 44 * for implementing canonicalizing mappings that do not prevent their keys (or 45 * values) from being reclaimed, and phantom references are for scheduling 46 * pre-mortem cleanup actions in a more flexible way than is possible with the 47 * Java finalization mechanism. 48 * 49 * <p> Each reference-object type is implemented by a subclass of the abstract 50 * base <code>{@link java.lang.ref.Reference}</code> class. An instance of one of 51 * these subclasses encapsulates a single reference to a particular object, called 52 * the <em>referent</em>. Every reference object provides methods for getting and 53 * clearing the reference. Aside from the clearing operation reference objects 54 * are otherwise immutable, so no <code>set</code> operation is provided. A 55 * program may further subclass these subclasses, adding whatever fields and 56 * methods are required for its purposes, or it may use these subclasses without 57 * change. 58 * 59 * 60 * <h3>Notification</h3> 61 * 62 * A program may request to be notified of changes in an object's reachability by 63 * <em>registering</em> an appropriate reference object with a <em>reference 64 * queue</em> at the time the reference object is created. Some time after the 65 * garbage collector determines that the reachability of the referent has changed 66 * to the value corresponding to the type of the reference, it will add the 67 * reference to the associated queue. At this point, the reference is considered 68 * to be <em>enqueued</em>. The program may remove references from a queue either 69 * by polling or by blocking until a reference becomes available. Reference 70 * queues are implemented by the <code>{@link java.lang.ref.ReferenceQueue}</code> 71 * class. 72 * 73 * <p> The relationship between a registered reference object and its queue is 74 * one-sided. That is, a queue does not keep track of the references that are 75 * registered with it. If a registered reference becomes unreachable itself, then 76 * it will never be enqueued. It is the responsibility of the program using 77 * reference objects to ensure that the objects remain reachable for as long as 78 * the program is interested in their referents. 79 * 80 * <p> While some programs will choose to dedicate a thread to removing reference 81 * objects from one or more queues and processing them, this is by no means 82 * necessary. A tactic that often works well is to examine a reference queue in 83 * the course of performing some other fairly-frequent action. For example, a 84 * hashtable that uses weak references to implement weak keys could poll its 85 * reference queue each time the table is accessed. This is how the <code>{@link 86 * java.util.WeakHashMap}</code> class works. Because the <code>{@link 87 * java.lang.ref.ReferenceQueue#poll ReferenceQueue.poll}</code> method simply 88 * checks an internal data structure, this check will add little overhead to the 89 * hashtable access methods. 90 * 91 * 92 * <h3>Automatically-cleared references</h3> 93 * 94 * Soft and weak references are automatically cleared by the collector before 95 * being added to the queues with which they are registered, if any. Therefore 96 * soft and weak references need not be registered with a queue in order to be 97 * useful, while phantom references do. An object that is reachable via phantom 98 * references will remain so until all such references are cleared or themselves 99 * become unreachable. 100 * 101 * 102 * <a name="reachability"></a> 103 * <h3>Reachability</h3> 104 * 105 * Going from strongest to weakest, the different levels of reachability reflect 106 * the life cycle of an object. They are operationally defined as follows: 107 * 108 * <ul> 109 * 110 * <li> An object is <em>strongly reachable</em> if it can be reached by some 111 * thread without traversing any reference objects. A newly-created object is 112 * strongly reachable by the thread that created it. 113 * 114 * <li> An object is <em>softly reachable</em> if it is not strongly reachable but 115 * can be reached by traversing a soft reference. 116 * 117 * <li> An object is <em>weakly reachable</em> if it is neither strongly nor 118 * softly reachable but can be reached by traversing a weak reference. When the 119 * weak references to a weakly-reachable object are cleared, the object becomes 120 * eligible for finalization. 121 * 122 * <li> An object is <em>phantom reachable</em> if it is neither strongly, softly, 123 * nor weakly reachable, it has been finalized, and some phantom reference refers 124 * to it. 125 * 126 * <li> Finally, an object is <em>unreachable</em>, and therefore eligible for 127 * reclamation, when it is not reachable in any of the above ways. 128 * 129 * </ul> 130 * 131 * 132 * @author Mark Reinhold 133 * @since 1.2 134 */ 135 package java.lang.ref; 136
