## 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, 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
`protected G` `current`

Constructor Summary
`ReferenceManager()`

Method Summary
`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, 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, 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`

### 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`