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: - An object is strongly reachable if it can be reached by some
jaroslav@601: thread without traversing any reference objects. A newly-created object is
jaroslav@601: strongly reachable by the thread that created it.
jaroslav@601:
jaroslav@601:
- An object is softly reachable if it is not strongly reachable but
jaroslav@601: can be reached by traversing a soft reference.
jaroslav@601:
jaroslav@601:
- An object is weakly reachable if it is neither strongly nor
jaroslav@601: softly reachable but can be reached by traversing a weak reference. When the
jaroslav@601: weak references to a weakly-reachable object are cleared, the object becomes
jaroslav@601: eligible for finalization.
jaroslav@601:
jaroslav@601:
- An object is phantom reachable if it is neither strongly, softly,
jaroslav@601: nor weakly reachable, it has been finalized, and some phantom reference refers
jaroslav@601: to it.
jaroslav@601:
jaroslav@601:
- Finally, an object is unreachable, and therefore eligible for
jaroslav@601: reclamation, when it is not reachable in any of the above ways.
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: