/*
* 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.
*/
/**
* 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
*/
package java.lang.ref;