Reachability State Changes

As mentioned previously, the purpose of reference objects is to enable you to hold references to objects that the garbage collector is free to collect. Put another way, the garbage collector is allowed to change the reachability state of any object that is not strongly reachable. Because it is often important to keep track of reachability state changes brought about by the garbage collector when you hold soft, weak, or phantom references, you can arrange to be notified when such changes occur. To register interest in reachability state changes, you associate reference objects with reference queues. A reference queue is an instance of class java.lang.ref.ReferenceQueue to which the garbage collector will append (or "enqueue") reference objects involved in reachability state changes. By setting up and monitoring reference queues, you can stay apprised of interesting reachability state changes performed asynchronously by the garbage collector.

To associate a reference object with a reference queue, you simply pass a reference to the reference queue as a constructor parameter when you create the reference object. A reference object so created, in addition to holding a reference to the referent, will hold a reference to the reference queue. When the garbage collector makes a relevant change to the reachability state of the referent, it will append the reference object to its associated reference queue. For example, when the WeakReference object shown in Figure 9-5 was created, two references were passed to the constructor: a reference to a Fox object and a reference to a ReferenceQueue object. When the garbage collector decides to collect the weakly reachable Fox object, it will clear the WeakReference object and either at that or some later time append the WeakReference object to its reference queue.

Figure 9-5. A reference object associated with a reference queue.

To append a reference object to the end of its associated queue, the garbage collector invokes enqueue() on the reference object. The enqueue() method, which is defined in superclass Reference, appends the reference object to a reference queue only if the object was associated with a queue when it was created, and only the first time enqueue() is invoked on the object. Programs can monitor a reference queue in two ways, either by polling with the poll() method or by blocking with the remove() method. If a reference object is waiting in the queue when either poll() or remove() is invoked on the queue object, the method will remove that object from the reference queue and return it. If no reference object is waiting in the queue, however, poll() will immediately return null, but remove() will block until the next reference object gets enqueued. Once a reference objects arrives in the queue, remove() will remove and return it.

The garbage collector enqueues soft, weak, and phantom reference objects in different situations to indicate three different kinds of reachability state changes. The meanings of the six reachability states and the circumstances under which state changes occur are as follow:

• strongly reachable - An object can be reached from the roots without traversing any reference objects. An object begins its lifetime in the strongly reachable state and remains strongly reachable so long as it is reachable via a root node or another strongly reachable object. The garbage collector will not attempt to reclaim the memory occupied by a strongly reachable object.
• softly reachable - An object is not strongly reachable, but can be reached from the roots via one or more (uncleared) soft reference objects. The garbage collector may reclaim the memory occupied by a softly reachable object. If it does so, it clears all soft references to that softly reachable object. When the garbage collector clears a soft reference object that is associated with a reference queue, it enqueues that soft reference object.
• weakly reachable - An object is neither strongly nor softly reachable, but can be reached from the roots via one or more (uncleared) weak reference objects. The garbage collector must reclaim the memory occupied by a weakly reachable object. When it does so, it clears all the weak references to that weakly reachable object. When the garbage collector clears a weak reference object that is associated with a reference queue, it enqueues that weak reference object.
• resurrectable - An object is neither strongly, softly, or weakly reachable, but may still be resurrected back into one of those states by the execution of some finalizer.
• phantom reachable - An object is not strongly, softly, nor weakly reachable, has been determined to not be resurrectable by any finalizer (if it declares a finalize() method itself, then its finalizer will have been run), and is reachable from the roots via one or more (uncleared) phantom reference objects. As soon as an object referenced by a phantom reference object becomes phantom reachable, the garbage collector will enqueue it. The garbage collector will never clear a phantom reference. All phantom references must be explicitly cleared by the program.
• unreachable - An object is neither strongly, softly, weakly, nor phantom reachable, and is not resurrectable. Unreachable objects are ready for reclamation.

Note that whereas the garbage collector enqueues soft and weak reference objects when their referents are leaving the relevant reachability state, it enqueues phantom references when the referents are entering the relevant state. You can also see this difference in that the garbage collector clears soft and weak reference objects before enqueueing them, but not phantom reference objects. Thus, the garbage collector enqueues soft reference objects to indicate their referents have just left the softly reachable state. Likewise, the garbage collector enqueues weak reference objects to indicate their referents have just left the weakly reachable state. But the garbage collector enqueues phantom reference objects to indicate their referents have entered the phantom reachable state. Phantom reachable objects will remain phantom reachable until their reference objects are explicitly cleared by the program.