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>