Provides reference-object classes, which support a limited degreeof interaction with the garbage collector. A program may use areference object to maintain a reference to some other object insuch a way that the latter object may still be reclaimed by thecollector. A program may also arrange to be notified some timeafter the collector has determined that the reachability of a givenobject has changed.

Reference Objects

Areference object encapsulates a reference to some otherobject so that the reference itself may be examined and manipulatedlike any other object. Three types of reference objects areprovided, each weaker than the last:soft,weak,andphantom. Each type corresponds to a different levelof reachability, as defined below. Soft references are forimplementing memory-sensitive caches, weak references are forimplementing canonicalizing mappings that do not prevent their keys(or values) from being reclaimed, and phantom references are forscheduling 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 theabstract baseReference class.An instance of one of these subclasses encapsulates a singlereference to a particular object, called thereferent.Every reference object provides methods for getting and clearingthe reference. Aside from the clearing operation reference objectsare otherwise immutable, so noset operation isprovided. A program may further subclass these subclasses, addingwhatever fields and methods are required for its purposes, or itmay use these subclasses without change.

Reachability

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

Going from strongest to weakest, the different levels ofreachability reflect the life cycle of an object. They areoperationally defined as follows:

• An object isstrongly reachable if it is reachable and if itcan be accessed without traversing the referent of a Reference object.
• An object issoftly reachable if it is not stronglyreachable but can be reached by traversing a soft reference.
• An object isweakly reachable if it is neitherstrongly nor softly reachable but can be reached by traversing aweak reference. When the weak references to a weakly-reachableobject are cleared, the object becomes eligible for finalization.
• An object isphantom reachable if it is neitherstrongly, softly, nor weakly reachable, it has been finalized, andsome phantom reference refers to it.
• Finally, an object isunreachable, and thereforeeligible for reclamation, when it is not reachable in any of theabove ways.

Notification

A program may request to be notified of changes in an object'sreachability byregistering an appropriate referenceobject with aReferenceQueue.This is done by providing the reference queue asa constructor argument when creating the reference object.Some time after the garbage collectordetermines that the reachability of the referent has changed to correspondwith the type of the reference, it will clear thereference and add it to the associated queue. At this point, thereference is considered to beenqueued. The program learns of thereferent's change in reachability when the associated reference becomesavailable 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 areferent's change in reachability can be stored in the fields of a customreference subclass, and accessed when the reference is returned from thequeue.

The relationship between a registered reference object and itsqueue is one-sided. That is, a queue does not keep track of thereferences that are registered with it. If a registered referencebecomes unreachable itself, then it will never be enqueued. It isthe responsibility of the program to ensurethat reference objects remain reachable for as long as the program isinterested in their referents.

While some programs will choose to dedicate a thread toremoving reference objects from one or more queues and processingthem, this is by no means necessary. A tactic that often workswell is to examine a reference queue in the course of performingsome other fairly-frequent action. For example, a hashtable thatuses weak references to implement weak keys could poll itsreference queue each time the table is accessed. This is how theWeakHashMap class works. BecausetheReferenceQueue.poll method simply checks an internal datastructure, this check will add little overhead to the hashtableaccess methods.

Memory Consistency Properties

Certain interactions between references, reference queues, and the garbagecollector formhappens-beforerelationships:

• 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-beforethe garbage collector enqueues the reference.
• The enqueueing of a reference (by the garbage collector, orby a successful call toReference.enqueue())happens-beforethe reference is removed from the queue (dequeued).
• The dequeuing of a reference to aregisteredobject, by the Cleaner thread,happens-before the Cleaner thread runsthe cleaning action for that object.

The above chain ofhappens-before edges ensures that actions in athread 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 ona Cleaner thread without additional synchronization.See JLS17.4.5.

The interaction between references, finalizers, and the garbage collectoralso 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 ona finalizer thread without additional synchronization.See JLS17.4.5.