2362N/A Copyright (c) 1998, 2003, Oracle and/or its affiliates. All rights reserved. 0N/A DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A This code is free software; you can redistribute it and/or modify it 0N/A under the terms of the GNU General Public License version 2 only, as 2362N/A published by the Free Software Foundation. Oracle designates this 0N/A particular file as subject to the "Classpath" exception as provided 2362N/A by Oracle in the LICENSE file that accompanied this code. 0N/A This code is distributed in the hope that it will be useful, but WITHOUT 0N/A ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A version 2 for more details (a copy is included in the LICENSE file that 0N/A accompanied this code). 0N/A You should have received a copy of the GNU General Public License version 0N/A 2 along with this work; if not, write to the Free Software Foundation, 0N/A Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 0N/A<!
DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
0N/A<
body bgcolor="white">
0N/AProvides reference-object classes, which support a limited degree of
0N/Ainteraction with the garbage collector. A program may use a reference object
0N/Ato maintain a reference to some other object in such a way that the latter
0N/Aobject may still be reclaimed by the collector. A program may also arrange to
0N/Abe notified some time after the collector has determined that the reachability
0N/Aof a given object has changed.
0N/A<
h2>Package Specification</
h2>
0N/AA <
em>reference object</
em> encapsulates a reference to some other object so
0N/Athat the reference itself may be examined and manipulated like any other
0N/Aobject. Three types of reference objects are provided, each weaker than the
0N/Alast: <
em>soft</
em>, <
em>weak</
em>, and <
em>phantom</
em>. Each type
0N/Acorresponds to a different level of reachability, as defined below. Soft
0N/Areferences are for implementing memory-sensitive caches, weak references are
0N/Afor implementing canonicalizing mappings that do not prevent their keys (or
0N/Avalues) from being reclaimed, and phantom references are for scheduling
0N/Apre-mortem cleanup actions in a more flexible way than is possible with the
0N/AJava finalization mechanism.
0N/A<
p> Each reference-object type is implemented by a subclass of the abstract
0N/Athese subclasses encapsulates a single reference to a particular object, called
0N/Athe <
em>referent</
em>. Every reference object provides methods for getting and
0N/Aclearing the reference. Aside from the clearing operation reference objects
0N/Aare otherwise immutable, so no <
code>set</
code> operation is provided. A
0N/Aprogram may further subclass these subclasses, adding whatever fields and
0N/Amethods are required for its purposes, or it may use these subclasses without
0N/A<
h3>Notification</
h3>
0N/AA program may request to be notified of changes in an object's reachability by
0N/A<
em>registering</
em> an appropriate reference object with a <
em>reference
0N/Aqueue</
em> at the time the reference object is created. Some time after the
0N/Agarbage collector determines that the reachability of the referent has changed
0N/Ato the value corresponding to the type of the reference, it will add the
0N/Areference to the associated queue. At this point, the reference is considered
0N/Ato be <
em>enqueued</
em>. The program may remove references from a queue either
0N/Aby polling or by blocking until a reference becomes available. Reference
0N/A<
p> The relationship between a registered reference object and its queue is
0N/Aone-sided. That is, a queue does not keep track of the references that are
0N/Aregistered with it. If a registered reference becomes unreachable itself, then
0N/Ait will never be enqueued. It is the responsibility of the program using
0N/Areference objects to ensure that the objects remain reachable for as long as
0N/Athe program is interested in their referents.
0N/A<
p> While some programs will choose to dedicate a thread to removing reference
0N/Aobjects from one or more queues and processing them, this is by no means
0N/Anecessary. A tactic that often works well is to examine a reference queue in
0N/Athe course of performing some other fairly-frequent action. For example, a
0N/Ahashtable that uses weak references to implement weak keys could poll its
0N/Areference queue each time the table is accessed. This is how the <
code>{@link
0N/Achecks an internal data structure, this check will add little overhead to the
0N/Ahashtable access methods.
0N/A<
h3>Automatically-cleared references</
h3>
0N/ASoft and weak references are automatically cleared by the collector before
0N/Abeing added to the queues with which they are registered, if any. Therefore
0N/Asoft and weak references need not be registered with a queue in order to be
0N/Auseful, while phantom references do. An object that is reachable via phantom
0N/Areferences will remain so until all such references are cleared or themselves
0N/A<
a name="reachability"></
a>
0N/A<
h3>Reachability</
h3>
0N/AGoing from strongest to weakest, the different levels of reachability reflect
0N/Athe life cycle of an object. They are operationally defined as follows:
0N/A<
li> An object is <
em>strongly reachable</
em> if it can be reached by some
0N/Athread without traversing any reference objects. A newly-created object is
0N/Astrongly reachable by the thread that created it.
0N/A<
li> An object is <
em>softly reachable</
em> if it is not strongly reachable but
0N/Acan be reached by traversing a soft reference.
0N/A<
li> An object is <
em>weakly reachable</
em> if it is neither strongly nor
0N/Asoftly reachable but can be reached by traversing a weak reference. When the
0N/Aweak references to a weakly-reachable object are cleared, the object becomes
0N/Aeligible for finalization.
0N/A<
li> An object is <
em>phantom reachable</
em> if it is neither strongly, softly,
0N/Anor weakly reachable, it has been finalized, and some phantom reference refers
0N/A<
li> Finally, an object is <
em>unreachable</
em>, and therefore eligible for
0N/Areclamation, when it is not reachable in any of the above ways.
0N/A@author Mark Reinhold
0N/A<h2>Related Documentation</h2> 0N/AFor overviews, tutorials, examples, guides, and tool documentation, please see: 0N/A <li><a href="">##### REFER TO NON-SPEC DOCUMENTATION HERE #####</a>