src.java.lang.ref.package-info Maven / Gradle / Ivy
Show all versions of android-all Show documentation
/*
* 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.
*
*
* Package Specification
*
* A reference object 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: soft, weak, and phantom. 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.
*
* Each reference-object type is implemented by a subclass of the abstract
* base {@link java.lang.ref.Reference} class. An instance of one of
* these subclasses encapsulates a single reference to a particular object, called
* the referent. Every reference object provides methods for getting and
* clearing the reference. Aside from the clearing operation reference objects
* are otherwise immutable, so no set 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.
*
*
*
Notification
*
* A program may request to be notified of changes in an object's reachability by
* registering an appropriate reference object with a reference
* queue 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 enqueued. 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 {@link java.lang.ref.ReferenceQueue}
* class.
*
* 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.
*
*
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 {@link
* java.util.WeakHashMap} class works. Because the {@link
* java.lang.ref.ReferenceQueue#poll ReferenceQueue.poll} method simply
* checks an internal data structure, this check will add little overhead to the
* hashtable access methods.
*
*
*
Automatically-cleared references
*
* 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.
*
*
*
* Reachability
*
* Going from strongest to weakest, the different levels of reachability reflect
* the life cycle of an object. They are operationally defined as follows:
*
*
*
* - An object is strongly reachable 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.
*
*
- An object is softly reachable if it is not strongly reachable but
* can be reached by traversing a soft reference.
*
*
- An object is weakly reachable 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.
*
*
- An object is phantom reachable if it is neither strongly, softly,
* nor weakly reachable, it has been finalized, and some phantom reference refers
* to it.
*
*
- Finally, an object is unreachable, and therefore eligible for
* reclamation, when it is not reachable in any of the above ways.
*
*
*
*
* @author Mark Reinhold
* @since 1.2
*/
package java.lang.ref;