Package org.apache.lucene.search

Class ReferenceManager<G>

  • Type Parameters:
    G - the concrete type that will be acquired and released.
    All Implemented Interfaces:
    Closeable, AutoCloseable
    Direct Known Subclasses:
    NRTManager, SearcherManager
    public abstract class ReferenceManager<G>
extends Object
implements Closeable
    Utility class to safely share instances of a certain type across multiple threads, while periodically refreshing them. This class ensures each reference is closed only once all threads have finished using it. It is recommended to consult the documentation of ReferenceManager implementations for their maybeRefresh() semantics.
    WARNING: This API is experimental and might change in incompatible ways in the next release.

    • Field Detail

      • current

        protected volatile G current

    • Constructor Detail

      • ReferenceManager

        public ReferenceManager()

    • Method Detail

      • decRef

        protected abstract void decRef​(G reference)
                        throws IOException
        Decrement reference counting on the given reference.
        Throws:
        IOException

      • refreshIfNeeded

        protected abstract G refreshIfNeeded​(G referenceToRefresh)
                              throws IOException
        Refresh the given reference if needed. Returns null if no refresh was needed, otherwise a new refreshed reference.
        Throws:
        IOException

      • tryIncRef

        protected abstract boolean tryIncRef​(G reference)
        Try to increment reference counting on the given reference. Return true if the operation was successful.

      • acquire

        public final G acquire()
        Obtain the current reference. You must match every call to acquire with one call to release(G); it's best to do so in a finally clause, and set the reference to null to prevent accidental usage after it has been released.

      • afterClose

        protected void afterClose()
                   throws IOException
        Called after close(), so subclass can free any resources.
        Throws:
        IOException

      • maybeRefresh

        public final boolean maybeRefresh()
                           throws IOException
        You must call this, periodically, if you want that acquire() will return refreshed instances.

        Threads: it's fine for more than one thread to call this at once. Only the first thread will attempt the refresh; subsequent threads will see that another thread is already handling refresh and will return immediately. Note that this means if another thread is already refreshing then subsequent threads will return right away without waiting for the refresh to complete.

        If this method returns true it means the calling thread either refreshed or that there were no changes to refresh. If it returns false it means another thread is currently refreshing.

        Throws:
        IOException

      • afterRefresh

        protected void afterRefresh()
                     throws IOException
        Called after swapReference has installed a new instance.
        Throws:
        IOException