java/lang/ref/package-info.java

/*
 * 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;