Package org.aksw.commons.util.ref

Interface Ref<T>

  • Type Parameters:
    T -
    All Superinterfaces:
    AutoCloseable
    All Known Subinterfaces:
    RefDelegate<T,​R>, RefFuture<T>
    All Known Implementing Classes:
    RefDelegateBase, RefFutureImpl, RefImpl
    public interface Ref<T>
extends AutoCloseable
    Interface for nested references. References allow for sharing an entity across several clients and deferring the release of that entity's resources immediately to the point in time when the last reference is released. The main use case is for memory paging such that if several threads request the same page only one physical buffer is handed out from a cache - conversely, as long as a page is still in used by a client, cache eviction and synchronization may be suppressed. Terminology: A reference is closed when close() was called; open otherwise. A reference is alive when it is open and/or any of the child refs acquired from it are still alive. A reference is released (dead) as soon it is no longer alive. This immediately triggers its release action. Implementation note: At present the alive-check and release action are assumed to run synchronously. As such there is no transition phase ('dying' or 'releasing'). This could be added in the future.
    Author:
    raven

    • Method Detail

      • getRootRef

        Ref<T> getRootRef()
        Get the root reference

      • get

        T get()
        Get the referent only iff this ref instance has not yet been closed. This method fails for closed alive refs. A closed reference is alive if it has unclosed child references. For most use cases the referent should be accessed using this method.
        Returns:
        The referent

      • getSynchronizer

        Object getSynchronizer()
        Return the object on which reference acquisition, release and the close action are synchronized on.

      • acquire

        Ref<T> acquire​(Object purpose)
        Acquire a new reference with a given comment object Acquiration fails if isAlive() returns false
        Returns:

      • acquire

        default Ref<T> acquire()

      • isAlive

        boolean isAlive()
        A reference may itself be closed, but references to it may keep it alive
        Returns:
        true iff either this reference is not closed or there exists any acquired reference.

      • isClosed

        boolean isClosed()
        Check whether this reference is closed

      • getAcquisitionStackTrace

        StackTraceElement[] getAcquisitionStackTrace()
        Optional operation. References may expose where they were acquired
        Returns:

      • acquireMapped

        default <X> Ref<X> acquireMapped​(java.util.function.Function<? super T,​? extends X> mapper)
        Return a ref with a new referent obtained by mapping this ref's value with mapper. Closing the returned ref closes the original one. Synchronizes on the same object as this ref.