Class References
- java.lang.Object
-
- org.agrona.References
-
public final class References extends java.lang.Object
References provides two key helper methods for commonly used idioms on ref types:isCleared(Reference)
, andisReferringTo(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.
-
-
Constructor Summary
Constructors Modifier Constructor Description private
References()
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static boolean
isCleared(java.lang.ref.Reference<?> ref)
Indicate whether aReference
has been cleared.static <T> boolean
isReferringTo(java.lang.ref.Reference<T> ref, T obj)
Indicate whether a Reference refers to a given object.
-
-
-
Method Detail
-
isCleared
public static boolean isCleared(java.lang.ref.Reference<?> ref)
Indicate whether aReference
has been cleared.- Parameters:
ref
- TheReference
to be tested.- Returns:
- true if
Reference
is cleared, otherwise false.
-
isReferringTo
public static <T> boolean isReferringTo(java.lang.ref.Reference<T> ref, T obj)
Indicate whether a Reference refers to a given object.- Type Parameters:
T
- the class of the referent.- Parameters:
ref
- TheReference
to be tested.obj
- The object to which theReference
may, or may not, be referring.- Returns:
- true if the
Reference
's referent is obj, otherwise false.
-
-