diff -r 4252bfc396fc -r d382dacfd73f emul/compact/src/main/java/java/lang/ref/package.html
--- a/emul/compact/src/main/java/java/lang/ref/package.html Tue Feb 26 14:55:55 2013 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,147 +0,0 @@
-
-
-
-
-
-
-
-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
-
-
-
-