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