1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/emul/compact/src/main/java/java/lang/ref/package.html Tue Feb 26 14:55:55 2013 +0100
1.3 @@ -0,0 +1,147 @@
1.4 +<!--
1.5 + Copyright (c) 1998, 2003, Oracle and/or its affiliates. All rights reserved.
1.6 + DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.7 +
1.8 + This code is free software; you can redistribute it and/or modify it
1.9 + under the terms of the GNU General Public License version 2 only, as
1.10 + published by the Free Software Foundation. Oracle designates this
1.11 + particular file as subject to the "Classpath" exception as provided
1.12 + by Oracle in the LICENSE file that accompanied this code.
1.13 +
1.14 + This code is distributed in the hope that it will be useful, but WITHOUT
1.15 + ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.16 + FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.17 + version 2 for more details (a copy is included in the LICENSE file that
1.18 + accompanied this code).
1.19 +
1.20 + You should have received a copy of the GNU General Public License version
1.21 + 2 along with this work; if not, write to the Free Software Foundation,
1.22 + Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.23 +
1.24 + Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
1.25 + or visit www.oracle.com if you need additional information or have any
1.26 + questions.
1.27 +-->
1.28 +
1.29 +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
1.30 +<html>
1.31 +<body bgcolor="white">
1.32 +
1.33 +
1.34 +Provides reference-object classes, which support a limited degree of
1.35 +interaction with the garbage collector. A program may use a reference object
1.36 +to maintain a reference to some other object in such a way that the latter
1.37 +object may still be reclaimed by the collector. A program may also arrange to
1.38 +be notified some time after the collector has determined that the reachability
1.39 +of a given object has changed.
1.40 +
1.41 +
1.42 +<h2>Package Specification</h2>
1.43 +
1.44 +A <em>reference object</em> encapsulates a reference to some other object so
1.45 +that the reference itself may be examined and manipulated like any other
1.46 +object. Three types of reference objects are provided, each weaker than the
1.47 +last: <em>soft</em>, <em>weak</em>, and <em>phantom</em>. Each type
1.48 +corresponds to a different level of reachability, as defined below. Soft
1.49 +references are for implementing memory-sensitive caches, weak references are
1.50 +for implementing canonicalizing mappings that do not prevent their keys (or
1.51 +values) from being reclaimed, and phantom references are for scheduling
1.52 +pre-mortem cleanup actions in a more flexible way than is possible with the
1.53 +Java finalization mechanism.
1.54 +
1.55 +<p> Each reference-object type is implemented by a subclass of the abstract
1.56 +base <code>{@link java.lang.ref.Reference}</code> class. An instance of one of
1.57 +these subclasses encapsulates a single reference to a particular object, called
1.58 +the <em>referent</em>. Every reference object provides methods for getting and
1.59 +clearing the reference. Aside from the clearing operation reference objects
1.60 +are otherwise immutable, so no <code>set</code> operation is provided. A
1.61 +program may further subclass these subclasses, adding whatever fields and
1.62 +methods are required for its purposes, or it may use these subclasses without
1.63 +change.
1.64 +
1.65 +
1.66 +<h3>Notification</h3>
1.67 +
1.68 +A program may request to be notified of changes in an object's reachability by
1.69 +<em>registering</em> an appropriate reference object with a <em>reference
1.70 +queue</em> at the time the reference object is created. Some time after the
1.71 +garbage collector determines that the reachability of the referent has changed
1.72 +to the value corresponding to the type of the reference, it will add the
1.73 +reference to the associated queue. At this point, the reference is considered
1.74 +to be <em>enqueued</em>. The program may remove references from a queue either
1.75 +by polling or by blocking until a reference becomes available. Reference
1.76 +queues are implemented by the <code>{@link java.lang.ref.ReferenceQueue}</code>
1.77 +class.
1.78 +
1.79 +<p> The relationship between a registered reference object and its queue is
1.80 +one-sided. That is, a queue does not keep track of the references that are
1.81 +registered with it. If a registered reference becomes unreachable itself, then
1.82 +it will never be enqueued. It is the responsibility of the program using
1.83 +reference objects to ensure that the objects remain reachable for as long as
1.84 +the program is interested in their referents.
1.85 +
1.86 +<p> While some programs will choose to dedicate a thread to removing reference
1.87 +objects from one or more queues and processing them, this is by no means
1.88 +necessary. A tactic that often works well is to examine a reference queue in
1.89 +the course of performing some other fairly-frequent action. For example, a
1.90 +hashtable that uses weak references to implement weak keys could poll its
1.91 +reference queue each time the table is accessed. This is how the <code>{@link
1.92 +java.util.WeakHashMap}</code> class works. Because the <code>{@link
1.93 +java.lang.ref.ReferenceQueue#poll ReferenceQueue.poll}</code> method simply
1.94 +checks an internal data structure, this check will add little overhead to the
1.95 +hashtable access methods.
1.96 +
1.97 +
1.98 +<h3>Automatically-cleared references</h3>
1.99 +
1.100 +Soft and weak references are automatically cleared by the collector before
1.101 +being added to the queues with which they are registered, if any. Therefore
1.102 +soft and weak references need not be registered with a queue in order to be
1.103 +useful, while phantom references do. An object that is reachable via phantom
1.104 +references will remain so until all such references are cleared or themselves
1.105 +become unreachable.
1.106 +
1.107 +
1.108 +<a name="reachability"></a>
1.109 +<h3>Reachability</h3>
1.110 +
1.111 +Going from strongest to weakest, the different levels of reachability reflect
1.112 +the life cycle of an object. They are operationally defined as follows:
1.113 +
1.114 +<ul>
1.115 +
1.116 +<li> An object is <em>strongly reachable</em> if it can be reached by some
1.117 +thread without traversing any reference objects. A newly-created object is
1.118 +strongly reachable by the thread that created it.
1.119 +
1.120 +<li> An object is <em>softly reachable</em> if it is not strongly reachable but
1.121 +can be reached by traversing a soft reference.
1.122 +
1.123 +<li> An object is <em>weakly reachable</em> if it is neither strongly nor
1.124 +softly reachable but can be reached by traversing a weak reference. When the
1.125 +weak references to a weakly-reachable object are cleared, the object becomes
1.126 +eligible for finalization.
1.127 +
1.128 +<li> An object is <em>phantom reachable</em> if it is neither strongly, softly,
1.129 +nor weakly reachable, it has been finalized, and some phantom reference refers
1.130 +to it.
1.131 +
1.132 +<li> Finally, an object is <em>unreachable</em>, and therefore eligible for
1.133 +reclamation, when it is not reachable in any of the above ways.
1.134 +
1.135 +</ul>
1.136 +
1.137 +
1.138 +@author Mark Reinhold
1.139 +@since 1.2
1.140 +
1.141 +<!--
1.142 +<h2>Related Documentation</h2>
1.143 +
1.144 +For overviews, tutorials, examples, guides, and tool documentation, please see:
1.145 +<ul>
1.146 + <li><a href="">##### REFER TO NON-SPEC DOCUMENTATION HERE #####</a>
1.147 +</ul>
1.148 +-->
1.149 +</body>
1.150 +</html>