ReferenceQueue

ReferenceQueue is a class from the java.lang.ref package that facilitates the notification of garbage collector events for objects that are referenced by java.lang.ref objects such as SoftReference, WeakReference, and PhantomReference. An instance of ReferenceQueue can be associated with any of these reference objects. When the garbage collector determines that a referenced object is no longer strongly reachable, it will enqueue the corresponding reference object onto the ReferenceQueue. Applications can then poll or remove references from the queue to detect when the referent has become eligible for reclamation, allowing the program to perform cleanup actions, release native resources, or otherwise manage memory more efficiently.

The primary methods of ReferenceQueue are poll() and remove(). poll() returns the next reference in the queue or null if the queue is empty, while remove() blocks until a reference becomes available. Both methods can also be supplied with a timeout period. A reference object that has been cleared by the garbage collector will hold a null referent; attempting to call get() on such a reference will return null. Once a reference has been processed, it is customary to clear it explicitly by calling clear(), although the garbage collector will eventually reclaim the reference object itself.

ReferenceQueue is particularly useful for implementing caches that rely on soft references, or for detecting when a thread or other object has been garbage collected so that the program can release associated resources. It is also employed in the internal implementation of java.lang.ref's PhantomReference to support explicit cleanup before object finalization. The use of ReferenceQueue, however, requires careful management of threads that poll or remove from it, and it should not be confused with Java's java.util.concurrent.LinkedBlockingQueue, which serves a different, non-garbage–collection purpose.