< prev index next >
src/java.base/share/classes/java/lang/ref/package-info.java
Print this page
@@ -1,147 +1,140 @@
-<!--
- 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.
+ */
+
+/**
+ * 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 {@link java.lang.ref.Reference} 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} 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 {@link java.lang.ref.ReferenceQueue} 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
+ * {@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.
+ *
+ * <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;
\ No newline at end of file
< prev index next >