jdk-sandbox: jdk/src/java.base/share/classes/java/lang/ref/package-info.java@87b434f45259 (annotated)

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

author	kbarrett
	Mon, 28 Dec 2015 14:03:39 -0500
changeset 35265	87b434f45259
parent 30788	ea573d35531a
child 35270	bcafb17da919
permissions	-rw-r--r--