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 
27 /**
28  * Provides reference-object classes, which support a limited degree of
29  * interaction with the garbage collector.  A program may use a reference object
30  * to maintain a reference to some other object in such a way that the latter
31  * object may still be reclaimed by the collector.  A program may also arrange to
32  * be notified some time after the collector has determined that the reachability
33  * of a given object has changed.
34  *
35  *
36  * <h2>Package Specification</h2>
37  *
38  * A <em>reference object</em> encapsulates a reference to some other object so
39  * that the reference itself may be examined and manipulated like any other
40  * object.  Three types of reference objects are provided, each weaker than the
41  * last: <em>soft</em>, <em>weak</em>, and <em>phantom</em>.  Each type
42  * corresponds to a different level of reachability, as defined below.  Soft
43  * references are for implementing memory-sensitive caches, weak references are
44  * for implementing canonicalizing mappings that do not prevent their keys (or
45  * values) from being reclaimed, and phantom references are for scheduling
46  * pre-mortem cleanup actions in a more flexible way than is possible with the
47  * Java finalization mechanism.
48  *
49  * <p> Each reference-object type is implemented by a subclass of the abstract
50  * base <code>{@link java.lang.ref.Reference}</code> class.  An instance of one of
51  * these subclasses encapsulates a single reference to a particular object, called
52  * the <em>referent</em>.  Every reference object provides methods for getting and
53  * clearing the reference.  Aside from the clearing operation reference objects
54  * are otherwise immutable, so no <code>set</code> operation is provided.  A
55  * program may further subclass these subclasses, adding whatever fields and
56  * methods are required for its purposes, or it may use these subclasses without
57  * change.
58  *
59  *
60  * <h3>Notification</h3>
61  *
62  * A program may request to be notified of changes in an object's reachability by
63  * <em>registering</em> an appropriate reference object with a <em>reference
64  * queue</em> at the time the reference object is created.  Some time after the
65  * garbage collector determines that the reachability of the referent has changed
66  * to the value corresponding to the type of the reference, it will add the
67  * reference to the associated queue.  At this point, the reference is considered
68  * to be <em>enqueued</em>.  The program may remove references from a queue either
69  * by polling or by blocking until a reference becomes available.  Reference
70  * queues are implemented by the <code>{@link java.lang.ref.ReferenceQueue}</code>
71  * class.
72  *
73  * <p> The relationship between a registered reference object and its queue is
74  * one-sided.  That is, a queue does not keep track of the references that are
75  * registered with it.  If a registered reference becomes unreachable itself, then
76  * it will never be enqueued.  It is the responsibility of the program using
77  * reference objects to ensure that the objects remain reachable for as long as
78  * the program is interested in their referents.
79  *
80  * <p> While some programs will choose to dedicate a thread to removing reference
81  * objects from one or more queues and processing them, this is by no means
82  * necessary.  A tactic that often works well is to examine a reference queue in
83  * the course of performing some other fairly-frequent action.  For example, a
84  * hashtable that uses weak references to implement weak keys could poll its
85  * reference queue each time the table is accessed.  This is how the <code>{@link
86  * java.util.WeakHashMap}</code> class works.  Because the <code>{@link
87  * java.lang.ref.ReferenceQueue#poll ReferenceQueue.poll}</code> method simply
88  * checks an internal data structure, this check will add little overhead to the
89  * hashtable access methods.
90  *
91  *
92  * <h3>Automatically-cleared references</h3>
93  *
94  * Soft and weak references are automatically cleared by the collector before
95  * being added to the queues with which they are registered, if any.  Therefore
96  * soft and weak references need not be registered with a queue in order to be
97  * useful, while phantom references do.  An object that is reachable via phantom
98  * references will remain so until all such references are cleared or themselves
99  * become unreachable.
100  *
101  *
102  * <a name="reachability"></a>
103  * <h3>Reachability</h3>
104  *
105  * Going from strongest to weakest, the different levels of reachability reflect
106  * the life cycle of an object.  They are operationally defined as follows:
107  *
108  * <ul>
109  *
110  * <li> An object is <em>strongly reachable</em> if it can be reached by some
111  * thread without traversing any reference objects.  A newly-created object is
112  * strongly reachable by the thread that created it.
113  *
114  * <li> An object is <em>softly reachable</em> if it is not strongly reachable but
115  * can be reached by traversing a soft reference.
116  *
117  * <li> An object is <em>weakly reachable</em> if it is neither strongly nor
118  * softly reachable but can be reached by traversing a weak reference.  When the
119  * weak references to a weakly-reachable object are cleared, the object becomes
120  * eligible for finalization.
121  *
122  * <li> An object is <em>phantom reachable</em> if it is neither strongly, softly,
123  * nor weakly reachable, it has been finalized, and some phantom reference refers
124  * to it.
125  *
126  * <li> Finally, an object is <em>unreachable</em>, and therefore eligible for
127  * reclamation, when it is not reachable in any of the above ways.
128  *
129  * </ul>
130  *
131  *
132  * @author	  Mark Reinhold
133  * @since	  1.2
134  */
135 package java.lang.ref;
136