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