jdk/src/share/classes/java/lang/ref/package.html - edge/openjdk - Git at Google


            
            <!--

            
             Copyright (c) 1998, 2003, Oracle and/or its affiliates. All rights reserved.

            
             DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.


             This code is free software; you can redistribute it and/or modify it

            
             under the terms of the GNU General Public License version 2 only, as

            
             published by the Free Software Foundation.  Oracle designates this

            
             particular file as subject to the "Classpath" exception as provided

            
             by Oracle in the LICENSE file that accompanied this code.


             This code is distributed in the hope that it will be useful, but WITHOUT

            
             ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

            
             FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

            
             version 2 for more details (a copy is included in the LICENSE file that

            
             accompanied this code).


             You should have received a copy of the GNU General Public License version

            
             2 along with this work; if not, write to the Free Software Foundation,

            
             Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.


             Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

            
             or visit www.oracle.com if you need additional information or have any

            
             questions.

            
            -->


            <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

            
            <html>

            
            <body bgcolor="white">


            Provides reference-object classes, which support a limited degree of

            
            interaction with the garbage collector.  A program may use a reference object

            
            to maintain a reference to some other object in such a way that the latter

            
            object may still be reclaimed by the collector.  A program may also arrange to

            
            be notified some time after the collector has determined that the reachability

            
            of a given object has changed.


            <h2>Package Specification</h2>


            A <em>reference object</em> encapsulates a reference to some other object so

            
            that the reference itself may be examined and manipulated like any other

            
            object.  Three types of reference objects are provided, each weaker than the

            
            last: <em>soft</em>, <em>weak</em>, and <em>phantom</em>.  Each type

            
            corresponds to a different level of reachability, as defined below.  Soft

            
            references are for implementing memory-sensitive caches, weak references are

            
            for implementing canonicalizing mappings that do not prevent their keys (or

            
            values) from being reclaimed, and phantom references are for scheduling

            
            pre-mortem cleanup actions in a more flexible way than is possible with the

            
            Java finalization mechanism.


            <p> Each reference-object type is implemented by a subclass of the abstract

            
            base <code>{@link java.lang.ref.Reference}</code> class.  An instance of one of

            
            these subclasses encapsulates a single reference to a particular object, called

            
            the <em>referent</em>.  Every reference object provides methods for getting and

            
            clearing the reference.  Aside from the clearing operation reference objects

            
            are otherwise immutable, so no <code>set</code> operation is provided.  A

            
            program may further subclass these subclasses, adding whatever fields and

            
            methods are required for its purposes, or it may use these subclasses without

            
            change.


            <h3>Notification</h3>


            A program may request to be notified of changes in an object's reachability by

            
            <em>registering</em> an appropriate reference object with a <em>reference

            
            queue</em> at the time the reference object is created.  Some time after the

            
            garbage collector determines that the reachability of the referent has changed

            
            to the value corresponding to the type of the reference, it will add the

            
            reference to the associated queue.  At this point, the reference is considered

            
            to be <em>enqueued</em>.  The program may remove references from a queue either

            
            by polling or by blocking until a reference becomes available.  Reference

            
            queues are implemented by the <code>{@link java.lang.ref.ReferenceQueue}</code>

            
            class.


            <p> The relationship between a registered reference object and its queue is

            
            one-sided.  That is, a queue does not keep track of the references that are

            
            registered with it.  If a registered reference becomes unreachable itself, then

            
            it will never be enqueued.  It is the responsibility of the program using

            
            reference objects to ensure that the objects remain reachable for as long as

            
            the program is interested in their referents.


            <p> While some programs will choose to dedicate a thread to removing reference

            
            objects from one or more queues and processing them, this is by no means

            
            necessary.  A tactic that often works well is to examine a reference queue in

            
            the course of performing some other fairly-frequent action.  For example, a

            
            hashtable that uses weak references to implement weak keys could poll its

            
            reference queue each time the table is accessed.  This is how the <code>{@link

            
            java.util.WeakHashMap}</code> class works.  Because the <code>{@link

            
            java.lang.ref.ReferenceQueue#poll ReferenceQueue.poll}</code> method simply

            
            checks an internal data structure, this check will add little overhead to the

            
            hashtable access methods.


            <h3>Automatically-cleared references</h3>


            Soft and weak references are automatically cleared by the collector before

            
            being added to the queues with which they are registered, if any.  Therefore

            
            soft and weak references need not be registered with a queue in order to be

            
            useful, while phantom references do.  An object that is reachable via phantom

            
            references will remain so until all such references are cleared or themselves

            
            become unreachable.


            <a name="reachability"></a>

            
            <h3>Reachability</h3>


            Going from strongest to weakest, the different levels of reachability reflect

            
            the life cycle of an object.  They are operationally defined as follows:


            <ul>


            <li> An object is <em>strongly reachable</em> if it can be reached by some

            
            thread without traversing any reference objects.  A newly-created object is

            
            strongly reachable by the thread that created it.


            <li> An object is <em>softly reachable</em> if it is not strongly reachable but

            
            can be reached by traversing a soft reference.


            <li> An object is <em>weakly reachable</em> if it is neither strongly nor

            
            softly reachable but can be reached by traversing a weak reference.  When the

            
            weak references to a weakly-reachable object are cleared, the object becomes

            
            eligible for finalization.


            <li> An object is <em>phantom reachable</em> if it is neither strongly, softly,

            
            nor weakly reachable, it has been finalized, and some phantom reference refers

            
            to it.


            <li> Finally, an object is <em>unreachable</em>, and therefore eligible for

            
            reclamation, when it is not reachable in any of the above ways.


            </ul>


            @author	  Mark Reinhold

            
            @since	  1.2


            <!--

            
            <h2>Related Documentation</h2>


            For overviews, tutorials, examples, guides, and tool documentation, please see:

            
            <ul>

            
              <li><a href="">##### REFER TO NON-SPEC DOCUMENTATION HERE #####</a>

            
            </ul>

            
            -->

            
            </body>

            
            </html>
	<!--
	Copyright (c) 1998, 2003, Oracle and/or its affiliates. All rights reserved.
	DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

	This code is free software; you can redistribute it and/or modify it
	under the terms of the GNU General Public License version 2 only, as
	published by the Free Software Foundation. Oracle designates this
	particular file as subject to the "Classpath" exception as provided
	by Oracle in the LICENSE file that accompanied this code.

	This code is distributed in the hope that it will be useful, but WITHOUT
	ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
	FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
	version 2 for more details (a copy is included in the LICENSE file that
	accompanied this code).

	You should have received a copy of the GNU General Public License version
	2 along with this work; if not, write to the Free Software Foundation,
	Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

	Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
	or visit www.oracle.com if you need additional information or have any
	questions.
	-->

	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
	<html>
	<body bgcolor="white">


	Provides reference-object classes, which support a limited degree of
	interaction with the garbage collector. A program may use a reference object
	to maintain a reference to some other object in such a way that the latter
	object may still be reclaimed by the collector. A program may also arrange to
	be notified some time after the collector has determined that the reachability
	of a given object has changed.


	<h2>Package Specification</h2>

	A <em>reference object</em> encapsulates a reference to some other object so
	that the reference itself may be examined and manipulated like any other
	object. Three types of reference objects are provided, each weaker than the
	last: <em>soft</em>, <em>weak</em>, and <em>phantom</em>. Each type
	corresponds to a different level of reachability, as defined below. Soft
	references are for implementing memory-sensitive caches, weak references are
	for implementing canonicalizing mappings that do not prevent their keys (or
	values) from being reclaimed, and phantom references are for scheduling
	pre-mortem cleanup actions in a more flexible way than is possible with the
	Java finalization mechanism.

	<p> Each reference-object type is implemented by a subclass of the abstract
	base <code>{@link java.lang.ref.Reference}</code> class. An instance of one of
	these subclasses encapsulates a single reference to a particular object, called
	the <em>referent</em>. Every reference object provides methods for getting and
	clearing the reference. Aside from the clearing operation reference objects
	are otherwise immutable, so no <code>set</code> operation is provided. A
	program may further subclass these subclasses, adding whatever fields and
	methods are required for its purposes, or it may use these subclasses without
	change.


	<h3>Notification</h3>

	A program may request to be notified of changes in an object's reachability by
	<em>registering</em> an appropriate reference object with a <em>reference
	queue</em> at the time the reference object is created. Some time after the
	garbage collector determines that the reachability of the referent has changed
	to the value corresponding to the type of the reference, it will add the
	reference to the associated queue. At this point, the reference is considered
	to be <em>enqueued</em>. The program may remove references from a queue either
	by polling or by blocking until a reference becomes available. Reference
	queues are implemented by the <code>{@link java.lang.ref.ReferenceQueue}</code>
	class.

	<p> The relationship between a registered reference object and its queue is
	one-sided. That is, a queue does not keep track of the references that are
	registered with it. If a registered reference becomes unreachable itself, then
	it will never be enqueued. It is the responsibility of the program using
	reference objects to ensure that the objects remain reachable for as long as
	the program is interested in their referents.

	<p> While some programs will choose to dedicate a thread to removing reference
	objects from one or more queues and processing them, this is by no means
	necessary. A tactic that often works well is to examine a reference queue in
	the course of performing some other fairly-frequent action. For example, a
	hashtable that uses weak references to implement weak keys could poll its
	reference queue each time the table is accessed. This is how the <code>{@link
	java.util.WeakHashMap}</code> class works. Because the <code>{@link
	java.lang.ref.ReferenceQueue#poll ReferenceQueue.poll}</code> method simply
	checks an internal data structure, this check will add little overhead to the
	hashtable access methods.


	<h3>Automatically-cleared references</h3>

	Soft and weak references are automatically cleared by the collector before
	being added to the queues with which they are registered, if any. Therefore
	soft and weak references need not be registered with a queue in order to be
	useful, while phantom references do. An object that is reachable via phantom
	references will remain so until all such references are cleared or themselves
	become unreachable.


	<a name="reachability"></a>
	<h3>Reachability</h3>

	Going from strongest to weakest, the different levels of reachability reflect
	the life cycle of an object. They are operationally defined as follows:

	<ul>

	<li> An object is <em>strongly reachable</em> if it can be reached by some
	thread without traversing any reference objects. A newly-created object is
	strongly reachable by the thread that created it.

	<li> An object is <em>softly reachable</em> if it is not strongly reachable but
	can be reached by traversing a soft reference.

	<li> An object is <em>weakly reachable</em> if it is neither strongly nor
	softly reachable but can be reached by traversing a weak reference. When the
	weak references to a weakly-reachable object are cleared, the object becomes
	eligible for finalization.

	<li> An object is <em>phantom reachable</em> if it is neither strongly, softly,
	nor weakly reachable, it has been finalized, and some phantom reference refers
	to it.

	<li> Finally, an object is <em>unreachable</em>, and therefore eligible for
	reclamation, when it is not reachable in any of the above ways.

	</ul>


	@author Mark Reinhold
	@since 1.2

	<!--
	<h2>Related Documentation</h2>

	For overviews, tutorials, examples, guides, and tool documentation, please see:
	<ul>
	<li><a href="">##### REFER TO NON-SPEC DOCUMENTATION HERE #####</a>
	</ul>
	-->
	</body>
	</html>