Package org.agrona

Class References


  • public final class References
    extends java.lang.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.

    • 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 a Reference has been cleared.
      static <T> boolean isReferringTo​(java.lang.ref.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
    • Constructor Detail

      • References

        private References()
    • Method Detail

      • isCleared

        public static boolean isCleared​(java.lang.ref.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​(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 - 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.