org.apache.lucene.search

Class ReferenceManager<G>

java.lang.Object

org.apache.lucene.search.ReferenceManager<G>

Type Parameters:

G - the concrete type that will be acquired and released.

All Implemented Interfaces:

Closeable

Direct Known Subclasses:

NRTManager, ReaderManager, 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 Summary

Fields

Modifier and Type	Field and Description
protected G	current

Constructor Summary

Constructors

Constructor and Description
ReferenceManager()

Method Summary

Methods

Modifier and Type	Method and 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 future acquiring.
protected abstract void	decRef(G reference) Decrement reference counting on the given reference.
boolean	maybeRefresh() You must call this (or maybeRefreshBlocking()), periodically, if you want that acquire() will return refreshed instances.
void	maybeRefreshBlocking() You must call this (or maybeRefresh()), periodically, if you want that acquire() 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 via acquire().
protected abstract boolean	tryIncRef(G reference) Try to increment reference counting on the given reference.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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.

close

public final void close()
                 throws IOException

Close this ReferenceManager to future acquiring. Any references that were previously acquired won't be affected, and they should still be released when they are not needed anymore.

Specified by:

close in interface Closeable

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 (or maybeRefreshBlocking()), 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

maybeRefreshBlocking

public final void maybeRefreshBlocking()
                                throws IOException

You must call this (or maybeRefresh()), periodically, if you want that acquire() will return refreshed instances.

Threads: unlike maybeRefresh(), if another thread is currently refreshing, this method blocks until that thread completes. It is useful if you want to guarantee that the next call to acquire() will return a refreshed instance. Otherwise, consider using the non-blocking maybeRefresh().

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

Release the refernce previously obtained via acquire().

NOTE: it's safe to call this after close().

Throws:

IOException