[This has been updated to propose refersTo rather than isCleared or isReferenceTo, per discussion in the comments.]

There is a frequently occurring need to determine whether a Reference (still) refers to a given object, or whether it has been (possibly automatically) cleared. Sometimes automatic clearing detection is accomplished via the use of a ReferenceQueue, and noticing when the Reference shows up there. However, that's not always convenient. It also doesn't support testing whether some non-null object is the referent.

An oft-used alternative is to use Reference.get and compare the result with the value of interest. For example, a simple grep of the jdk forest found around 25 non-test comparisons of get() with null; not all of them are Reference.get, but many of them are.

However, such use of Reference.get interacts poorly with some GCs. For example, SATB collectors (such as G1 and Shenandoah) need to mark the referent of weak references when they are accessed, in order to maintain their invariants. When using such a collector, repeated checks using Reference::get could prevent a reference from *ever* being cleared, even though its referent object is only (weakly) reachable from the reference and occasionally, briefly, while performing those repeated checks.

Also, such use of Reference.get only works for SoftReference and WeakReference; it does not work for PhantomReference, since the referent is inaccessible for those. And for SoftReferences it has the problem of introducing a recent access, potentially extending the lifetime of the referent for all collectors.

This suggests we need a new operation for use in such situations. We propose the addition of the predicate Reference::refersTo for this purpose.