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