# Reference Leak

Find infomration about and possible incorrect uses of soft, weak or phantom references.

## Motivation

Soft references `java.lang.ref.SoftReference`, weak references `java.lang.ref.WeakReference` and Phantom references `java.lang.ref.PhantomReference` are used to keep references to objects which can be cleared by garbage collection if there are no other strong references.

Soft references can be used for object caching, so that an object can usually be retained for fast access, but if memory is tight then garbage collection can break the link and free the object. Next time it is needed then the application program can regenerate the object.

Weak references can be used in a weak hash map `java.util.WeakHashMap` to hold information associated with another object, but if that object is no longer available then the associated information can be freed too.

Sometimes an error in the application program can mean that the object which is supposed to be softly or weakly referenced is also strongly retained by the reference object. For example the key of a weak hash map is weakly retained, but if there is a strong reference to it from the value of the weak hash map entry then the object will never be freed.

Phantom references are used to trigger an event when an object is garbage collected. The object itself cannot be obtained from the PhantomReference.

## Operation

This query performs the following steps:

1. For each reference object supplied to the query, find the object referred to by the reference object via the reference field, and return those objects as a histogram.
2. For each reference object supplied to the query, find all the objects only retained by those reference objects via the reference field, and return those objects as a histogram.
3. Find all the objects strongly retained by these reference objects, and then find all the referenced objects in the first step which are in this set, and returned those objects as a histogram. This might indicate a possible reference leak, as for example normally a Weak Hash Map should not have a reference from the value to the key as that would stop the entry from being freed when the reference was no longer accessible.

## Arguments

Argument | Description
--- | ---
objects | Reference objects for which the reference statistics query should be run.
-referent_attribute | The referent field name for the reference objects. The default is `referent`

## Result