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.

Reference Objects

Areference 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, andphantom. 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 also be registered and managed by aCleaner.

Each reference-object type is implemented by a subclass of the abstract baseReference class. An instance of one of these subclasses encapsulates a single reference to a particular object, called thereferent. Every reference object provides methods for getting and clearing the reference. Aside from the clearing operation reference objects are otherwise immutable, so noset 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.

Reachability

Areachable object is any object that can be accessed in any potential continuing computation from anylive thread (as stated in JLS12.6.1).

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 isstrongly reachable if it is reachable and if it can be accessed without traversing the referent of a Reference object.
• An object issoftly reachable if it is not strongly reachable but can be reached by traversing a soft reference.
• An object isweakly 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 isphantom reachable if it is neither strongly, softly, nor weakly reachable, it has been finalized, and some phantom reference refers to it.
• Finally, an object isunreachable, and therefore eligible for reclamation, when it is not reachable in any of the above ways.

Notification

A program may request to be notified of changes in an object's reachability byregistering an appropriate reference object with aReferenceQueue. This is done by providing the reference queue as a constructor argument when creating the reference object. Some time after the garbage collector determines that the reachability of the referent has changed to correspond with 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 beenqueued. The program learns of the referent's change in reachability when the associated reference becomes available on the queue. The program may remove references from a queue (that is,dequeue them) using theReferenceQueue.poll() orReferenceQueue.remove() methods. Additional state needed to respond to a referent's change in reachability can be stored in the fields of a custom reference subclass, and accessed when the reference is returned from the queue.

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 to ensure that reference 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 theWeakHashMap class works. Because theReferenceQueue.poll method simply checks an internal data structure, this check will add little overhead to the hashtable access methods.

Memory Consistency Properties

Certain interactions between references, reference queues, and the garbage collector formhappens-before relationships:

• Actions in a thread prior to callingReference.reachabilityFence(x)happen-before the garbage collector clears any reference tox.
• The clearing of a reference by the garbage collectorhappens-before the garbage collector enqueues the reference.
• The enqueueing of a reference (by the garbage collector, or by a successful call toReference.enqueue())happens-before the reference is removed from the queue (dequeued).
• The dequeuing of a reference to aregistered object, by the Cleaner thread,happens-before the Cleaner thread runs the cleaning action for that object.

The above chain ofhappens-before edges ensures that actions in a thread prior to aReference.reachabilityFence(x)happen-before cleanup code forx runs on a Cleaner thread. In particular, changes to the state ofx made beforereachabilityFence(x) will be visible to the cleanup code running on a Cleaner thread without additional synchronization. See JLS17.4.5.

The interaction between references, finalizers, and the garbage collector also forms ahappens-before relationship:

• Actions in a thread prior to callingReference.reachabilityFence(x)happen-before the finalizer forx is run by a finalizer thread.

This ensures that actions in a thread prior to aReference.reachabilityFence(x)happen-before cleanup code forx runs on a finalizer thread. In particular, changes to the state ofx made beforereachabilityFence(x) will be visible to the cleanup code running on a finalizer thread without additional synchronization. See JLS17.4.5.