org.agrona

Class References

java.lang.Object

org.agrona.References

public final class References
extends Object

References provides two key helper methods for commonly used idioms on ref types: isCleared(Reference), and isReferringTo(Reference, Object).

Both of these idioms are obviously trivially implementable using Reference.get(). However, such explicit implementations produce a temporary strong reference to the referent, forcing a "strengthening" of the referent when performed during concurrent marking phases on most concurrent collectors (such as G1, C4, ZGC, Shenandoah, etc.). By capturing the non-reference-escaping semantic definitions of these idioms, JDKs may validly intrisify their implementations to perform the required logic without strengthening the referent.

Various uses of Reference subclasses can use these method idioms when performing the common operations needed to maintain various data structures such and weakly keyed maps, lists, etc., without those operations explicitly force-strengthening referents. When run on JDKs that intrisify these implementations, or on future JDKs that would provide similar functionality (and to which this class will adapt in a portable way), such strengthening will be avoided.

For example, the JDK's own internal WeakIdentityHashMap implementation could, when using these two methods, have its get() and set() methods work without requiring the force-strengthening of unrelated keys and without forcing unrelated entries and values to stay alive.

Since JDKs may choose to "intrinsify" the implementation of the methods in this class, no assumptions, beyond those provided in the documentation below, should be made about their actual implementation.

Method Summary

Modifier and Type	Method and Description
static boolean	isCleared(Reference<?> ref) Indicate whether a Reference has been cleared.
static <T> boolean	isReferringTo(Reference<T> ref, T obj) Indicate whether a Reference refers to a given object.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

isCleared

public static boolean isCleared(Reference<?> ref)

Indicate whether a Reference has been cleared.

Parameters:

ref - The Reference to be tested.

Returns:

true if Reference is cleared, otherwise false.

isReferringTo

public static <T> boolean isReferringTo(Reference<T> ref,
                                        T obj)

Indicate whether a Reference refers to a given object.

Type Parameters:

T - the class of the referent.

Parameters:

ref - The Reference to be tested.

obj - The object to which the Reference may, or may not, be referring.

Returns:

true if the Reference's referent is obj, otherwise false.