Package org.apache.lucene.search
Class ReferenceManager<G>
- java.lang.Object
-
- org.apache.lucene.search.ReferenceManager<G>
-
- 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 ofReferenceManager
implementations for theirmaybeRefresh()
semantics.- WARNING: This API is experimental and might change in incompatible ways in the next release.
-
-
Constructor Summary
Constructors Constructor Description ReferenceManager()
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description G
acquire()
Obtain the current reference.protected void
afterClose()
Called after close(), so subclass can free any resources.protected void
afterRefresh()
Called after swapReference has installed a new instance.void
close()
Close this ReferenceManager to futureacquiring
.protected abstract void
decRef(G reference)
Decrement reference counting on the given reference.boolean
maybeRefresh()
You must call this, periodically, if you want thatacquire()
will return refreshed instances.protected abstract G
refreshIfNeeded(G referenceToRefresh)
Refresh the given reference if needed.void
release(G reference)
Release the refernce previously obtained viaacquire()
.protected abstract boolean
tryIncRef(G reference)
Try to increment reference counting on the given reference.
-
-
-
Field Detail
-
current
protected volatile G current
-
-
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. Returnsnull
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 torelease(G)
; it's best to do so in a finally clause, and set the reference tonull
to prevent accidental usage after it has been released.
-
close
public final void close() throws IOException
Close this ReferenceManager to futureacquiring
. Any references that were previouslyacquired
won't be affected, and they should still bereleased
when they are not needed anymore.- Specified by:
close
in interfaceAutoCloseable
- Specified by:
close
in interfaceCloseable
- Throws:
IOException
-
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 thatacquire()
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
-
release
public final void release(G reference) throws IOException
- Throws:
IOException
-
-