|
jaroslav@601
|
1 |
<!--
|
|
jaroslav@601
|
2 |
Copyright (c) 1998, 2003, Oracle and/or its affiliates. All rights reserved.
|
|
jaroslav@601
|
3 |
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
|
|
jaroslav@601
|
4 |
|
|
jaroslav@601
|
5 |
This code is free software; you can redistribute it and/or modify it
|
|
jaroslav@601
|
6 |
under the terms of the GNU General Public License version 2 only, as
|
|
jaroslav@601
|
7 |
published by the Free Software Foundation. Oracle designates this
|
|
jaroslav@601
|
8 |
particular file as subject to the "Classpath" exception as provided
|
|
jaroslav@601
|
9 |
by Oracle in the LICENSE file that accompanied this code.
|
|
jaroslav@601
|
10 |
|
|
jaroslav@601
|
11 |
This code is distributed in the hope that it will be useful, but WITHOUT
|
|
jaroslav@601
|
12 |
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
|
|
jaroslav@601
|
13 |
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
|
|
jaroslav@601
|
14 |
version 2 for more details (a copy is included in the LICENSE file that
|
|
jaroslav@601
|
15 |
accompanied this code).
|
|
jaroslav@601
|
16 |
|
|
jaroslav@601
|
17 |
You should have received a copy of the GNU General Public License version
|
|
jaroslav@601
|
18 |
2 along with this work; if not, write to the Free Software Foundation,
|
|
jaroslav@601
|
19 |
Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
|
|
jaroslav@601
|
20 |
|
|
jaroslav@601
|
21 |
Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
|
|
jaroslav@601
|
22 |
or visit www.oracle.com if you need additional information or have any
|
|
jaroslav@601
|
23 |
questions.
|
|
jaroslav@601
|
24 |
-->
|
|
jaroslav@601
|
25 |
|
|
jaroslav@601
|
26 |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
|
|
jaroslav@601
|
27 |
<html>
|
|
jaroslav@601
|
28 |
<body bgcolor="white">
|
|
jaroslav@601
|
29 |
|
|
jaroslav@601
|
30 |
|
|
jaroslav@601
|
31 |
Provides reference-object classes, which support a limited degree of
|
|
jaroslav@601
|
32 |
interaction with the garbage collector. A program may use a reference object
|
|
jaroslav@601
|
33 |
to maintain a reference to some other object in such a way that the latter
|
|
jaroslav@601
|
34 |
object may still be reclaimed by the collector. A program may also arrange to
|
|
jaroslav@601
|
35 |
be notified some time after the collector has determined that the reachability
|
|
jaroslav@601
|
36 |
of a given object has changed.
|
|
jaroslav@601
|
37 |
|
|
jaroslav@601
|
38 |
|
|
jaroslav@601
|
39 |
<h2>Package Specification</h2>
|
|
jaroslav@601
|
40 |
|
|
jaroslav@601
|
41 |
A <em>reference object</em> encapsulates a reference to some other object so
|
|
jaroslav@601
|
42 |
that the reference itself may be examined and manipulated like any other
|
|
jaroslav@601
|
43 |
object. Three types of reference objects are provided, each weaker than the
|
|
jaroslav@601
|
44 |
last: <em>soft</em>, <em>weak</em>, and <em>phantom</em>. Each type
|
|
jaroslav@601
|
45 |
corresponds to a different level of reachability, as defined below. Soft
|
|
jaroslav@601
|
46 |
references are for implementing memory-sensitive caches, weak references are
|
|
jaroslav@601
|
47 |
for implementing canonicalizing mappings that do not prevent their keys (or
|
|
jaroslav@601
|
48 |
values) from being reclaimed, and phantom references are for scheduling
|
|
jaroslav@601
|
49 |
pre-mortem cleanup actions in a more flexible way than is possible with the
|
|
jaroslav@601
|
50 |
Java finalization mechanism.
|
|
jaroslav@601
|
51 |
|
|
jaroslav@601
|
52 |
<p> Each reference-object type is implemented by a subclass of the abstract
|
|
jaroslav@601
|
53 |
base <code>{@link java.lang.ref.Reference}</code> class. An instance of one of
|
|
jaroslav@601
|
54 |
these subclasses encapsulates a single reference to a particular object, called
|
|
jaroslav@601
|
55 |
the <em>referent</em>. Every reference object provides methods for getting and
|
|
jaroslav@601
|
56 |
clearing the reference. Aside from the clearing operation reference objects
|
|
jaroslav@601
|
57 |
are otherwise immutable, so no <code>set</code> operation is provided. A
|
|
jaroslav@601
|
58 |
program may further subclass these subclasses, adding whatever fields and
|
|
jaroslav@601
|
59 |
methods are required for its purposes, or it may use these subclasses without
|
|
jaroslav@601
|
60 |
change.
|
|
jaroslav@601
|
61 |
|
|
jaroslav@601
|
62 |
|
|
jaroslav@601
|
63 |
<h3>Notification</h3>
|
|
jaroslav@601
|
64 |
|
|
jaroslav@601
|
65 |
A program may request to be notified of changes in an object's reachability by
|
|
jaroslav@601
|
66 |
<em>registering</em> an appropriate reference object with a <em>reference
|
|
jaroslav@601
|
67 |
queue</em> at the time the reference object is created. Some time after the
|
|
jaroslav@601
|
68 |
garbage collector determines that the reachability of the referent has changed
|
|
jaroslav@601
|
69 |
to the value corresponding to the type of the reference, it will add the
|
|
jaroslav@601
|
70 |
reference to the associated queue. At this point, the reference is considered
|
|
jaroslav@601
|
71 |
to be <em>enqueued</em>. The program may remove references from a queue either
|
|
jaroslav@601
|
72 |
by polling or by blocking until a reference becomes available. Reference
|
|
jaroslav@601
|
73 |
queues are implemented by the <code>{@link java.lang.ref.ReferenceQueue}</code>
|
|
jaroslav@601
|
74 |
class.
|
|
jaroslav@601
|
75 |
|
|
jaroslav@601
|
76 |
<p> The relationship between a registered reference object and its queue is
|
|
jaroslav@601
|
77 |
one-sided. That is, a queue does not keep track of the references that are
|
|
jaroslav@601
|
78 |
registered with it. If a registered reference becomes unreachable itself, then
|
|
jaroslav@601
|
79 |
it will never be enqueued. It is the responsibility of the program using
|
|
jaroslav@601
|
80 |
reference objects to ensure that the objects remain reachable for as long as
|
|
jaroslav@601
|
81 |
the program is interested in their referents.
|
|
jaroslav@601
|
82 |
|
|
jaroslav@601
|
83 |
<p> While some programs will choose to dedicate a thread to removing reference
|
|
jaroslav@601
|
84 |
objects from one or more queues and processing them, this is by no means
|
|
jaroslav@601
|
85 |
necessary. A tactic that often works well is to examine a reference queue in
|
|
jaroslav@601
|
86 |
the course of performing some other fairly-frequent action. For example, a
|
|
jaroslav@601
|
87 |
hashtable that uses weak references to implement weak keys could poll its
|
|
jaroslav@601
|
88 |
reference queue each time the table is accessed. This is how the <code>{@link
|
|
jaroslav@601
|
89 |
java.util.WeakHashMap}</code> class works. Because the <code>{@link
|
|
jaroslav@601
|
90 |
java.lang.ref.ReferenceQueue#poll ReferenceQueue.poll}</code> method simply
|
|
jaroslav@601
|
91 |
checks an internal data structure, this check will add little overhead to the
|
|
jaroslav@601
|
92 |
hashtable access methods.
|
|
jaroslav@601
|
93 |
|
|
jaroslav@601
|
94 |
|
|
jaroslav@601
|
95 |
<h3>Automatically-cleared references</h3>
|
|
jaroslav@601
|
96 |
|
|
jaroslav@601
|
97 |
Soft and weak references are automatically cleared by the collector before
|
|
jaroslav@601
|
98 |
being added to the queues with which they are registered, if any. Therefore
|
|
jaroslav@601
|
99 |
soft and weak references need not be registered with a queue in order to be
|
|
jaroslav@601
|
100 |
useful, while phantom references do. An object that is reachable via phantom
|
|
jaroslav@601
|
101 |
references will remain so until all such references are cleared or themselves
|
|
jaroslav@601
|
102 |
become unreachable.
|
|
jaroslav@601
|
103 |
|
|
jaroslav@601
|
104 |
|
|
jaroslav@601
|
105 |
<a name="reachability"></a>
|
|
jaroslav@601
|
106 |
<h3>Reachability</h3>
|
|
jaroslav@601
|
107 |
|
|
jaroslav@601
|
108 |
Going from strongest to weakest, the different levels of reachability reflect
|
|
jaroslav@601
|
109 |
the life cycle of an object. They are operationally defined as follows:
|
|
jaroslav@601
|
110 |
|
|
jaroslav@601
|
111 |
<ul>
|
|
jaroslav@601
|
112 |
|
|
jaroslav@601
|
113 |
<li> An object is <em>strongly reachable</em> if it can be reached by some
|
|
jaroslav@601
|
114 |
thread without traversing any reference objects. A newly-created object is
|
|
jaroslav@601
|
115 |
strongly reachable by the thread that created it.
|
|
jaroslav@601
|
116 |
|
|
jaroslav@601
|
117 |
<li> An object is <em>softly reachable</em> if it is not strongly reachable but
|
|
jaroslav@601
|
118 |
can be reached by traversing a soft reference.
|
|
jaroslav@601
|
119 |
|
|
jaroslav@601
|
120 |
<li> An object is <em>weakly reachable</em> if it is neither strongly nor
|
|
jaroslav@601
|
121 |
softly reachable but can be reached by traversing a weak reference. When the
|
|
jaroslav@601
|
122 |
weak references to a weakly-reachable object are cleared, the object becomes
|
|
jaroslav@601
|
123 |
eligible for finalization.
|
|
jaroslav@601
|
124 |
|
|
jaroslav@601
|
125 |
<li> An object is <em>phantom reachable</em> if it is neither strongly, softly,
|
|
jaroslav@601
|
126 |
nor weakly reachable, it has been finalized, and some phantom reference refers
|
|
jaroslav@601
|
127 |
to it.
|
|
jaroslav@601
|
128 |
|
|
jaroslav@601
|
129 |
<li> Finally, an object is <em>unreachable</em>, and therefore eligible for
|
|
jaroslav@601
|
130 |
reclamation, when it is not reachable in any of the above ways.
|
|
jaroslav@601
|
131 |
|
|
jaroslav@601
|
132 |
</ul>
|
|
jaroslav@601
|
133 |
|
|
jaroslav@601
|
134 |
|
|
jaroslav@601
|
135 |
@author Mark Reinhold
|
|
jaroslav@601
|
136 |
@since 1.2
|
|
jaroslav@601
|
137 |
|
|
jaroslav@601
|
138 |
<!--
|
|
jaroslav@601
|
139 |
<h2>Related Documentation</h2>
|
|
jaroslav@601
|
140 |
|
|
jaroslav@601
|
141 |
For overviews, tutorials, examples, guides, and tool documentation, please see:
|
|
jaroslav@601
|
142 |
<ul>
|
|
jaroslav@601
|
143 |
<li><a href="">##### REFER TO NON-SPEC DOCUMENTATION HERE #####</a>
|
|
jaroslav@601
|
144 |
</ul>
|
|
jaroslav@601
|
145 |
-->
|
|
jaroslav@601
|
146 |
</body>
|
|
jaroslav@601
|
147 |
</html>
|