Package SpecificationA 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 post-mortem cleanup actions. Post-mortem cleanup actions can be registered and managed by a
Each reference-object type is implemented by a subclass of the
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.
NotificationA 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 clear the reference and add it 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
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
WeakHashMap class works. Because
ReferenceQueue.poll method simply checks an internal data
structure, this check will add little overhead to the hashtable
ReachabilityGoing 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.
Cleanablerepresents an object and a cleaning action registered in a
Cleanermanages a set of object references and corresponding cleaning actions.Phantom reference objects, which are enqueued after the collector determines that their referents may otherwise be reclaimed.Reference<T>Abstract base class for reference objects.Reference queues, to which registered reference objects are appended by the garbage collector after the appropriate reachability changes are detected.Soft reference objects, which are cleared at the discretion of the garbage collector in response to memory demand.Weak reference objects, which do not prevent their referents from being made finalizable, finalized, and then reclaimed.