jaroslav@601: jaroslav@601: jaroslav@601: jaroslav@601: jaroslav@601: jaroslav@601: jaroslav@601: jaroslav@601: Provides reference-object classes, which support a limited degree of jaroslav@601: interaction with the garbage collector. A program may use a reference object jaroslav@601: to maintain a reference to some other object in such a way that the latter jaroslav@601: object may still be reclaimed by the collector. A program may also arrange to jaroslav@601: be notified some time after the collector has determined that the reachability jaroslav@601: of a given object has changed. jaroslav@601: jaroslav@601: jaroslav@601:

Package Specification

jaroslav@601: jaroslav@601: A reference object encapsulates a reference to some other object so jaroslav@601: that the reference itself may be examined and manipulated like any other jaroslav@601: object. Three types of reference objects are provided, each weaker than the jaroslav@601: last: soft, weak, and phantom. Each type jaroslav@601: corresponds to a different level of reachability, as defined below. Soft jaroslav@601: references are for implementing memory-sensitive caches, weak references are jaroslav@601: for implementing canonicalizing mappings that do not prevent their keys (or jaroslav@601: values) from being reclaimed, and phantom references are for scheduling jaroslav@601: pre-mortem cleanup actions in a more flexible way than is possible with the jaroslav@601: Java finalization mechanism. jaroslav@601: jaroslav@601:

Each reference-object type is implemented by a subclass of the abstract jaroslav@601: base {@link java.lang.ref.Reference} class. An instance of one of jaroslav@601: these subclasses encapsulates a single reference to a particular object, called jaroslav@601: the referent. Every reference object provides methods for getting and jaroslav@601: clearing the reference. Aside from the clearing operation reference objects jaroslav@601: are otherwise immutable, so no set operation is provided. A jaroslav@601: program may further subclass these subclasses, adding whatever fields and jaroslav@601: methods are required for its purposes, or it may use these subclasses without jaroslav@601: change. jaroslav@601: jaroslav@601: jaroslav@601:

Notification

jaroslav@601: jaroslav@601: A program may request to be notified of changes in an object's reachability by jaroslav@601: registering an appropriate reference object with a reference jaroslav@601: queue at the time the reference object is created. Some time after the jaroslav@601: garbage collector determines that the reachability of the referent has changed jaroslav@601: to the value corresponding to the type of the reference, it will add the jaroslav@601: reference to the associated queue. At this point, the reference is considered jaroslav@601: to be enqueued. The program may remove references from a queue either jaroslav@601: by polling or by blocking until a reference becomes available. Reference jaroslav@601: queues are implemented by the {@link java.lang.ref.ReferenceQueue} jaroslav@601: class. jaroslav@601: jaroslav@601:

The relationship between a registered reference object and its queue is jaroslav@601: one-sided. That is, a queue does not keep track of the references that are jaroslav@601: registered with it. If a registered reference becomes unreachable itself, then jaroslav@601: it will never be enqueued. It is the responsibility of the program using jaroslav@601: reference objects to ensure that the objects remain reachable for as long as jaroslav@601: the program is interested in their referents. jaroslav@601: jaroslav@601:

While some programs will choose to dedicate a thread to removing reference jaroslav@601: objects from one or more queues and processing them, this is by no means jaroslav@601: necessary. A tactic that often works well is to examine a reference queue in jaroslav@601: the course of performing some other fairly-frequent action. For example, a jaroslav@601: hashtable that uses weak references to implement weak keys could poll its jaroslav@601: reference queue each time the table is accessed. This is how the {@link jaroslav@601: java.util.WeakHashMap} class works. Because the {@link jaroslav@601: java.lang.ref.ReferenceQueue#poll ReferenceQueue.poll} method simply jaroslav@601: checks an internal data structure, this check will add little overhead to the jaroslav@601: hashtable access methods. jaroslav@601: jaroslav@601: jaroslav@601:

Automatically-cleared references

jaroslav@601: jaroslav@601: Soft and weak references are automatically cleared by the collector before jaroslav@601: being added to the queues with which they are registered, if any. Therefore jaroslav@601: soft and weak references need not be registered with a queue in order to be jaroslav@601: useful, while phantom references do. An object that is reachable via phantom jaroslav@601: references will remain so until all such references are cleared or themselves jaroslav@601: become unreachable. jaroslav@601: jaroslav@601: jaroslav@601: jaroslav@601:

Reachability

jaroslav@601: jaroslav@601: Going from strongest to weakest, the different levels of reachability reflect jaroslav@601: the life cycle of an object. They are operationally defined as follows: jaroslav@601: jaroslav@601: jaroslav@601: jaroslav@601: jaroslav@601: @author Mark Reinhold jaroslav@601: @since 1.2 jaroslav@601: jaroslav@601: jaroslav@601: jaroslav@601: