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> |
|