Class ReferenceManager<G>

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<G> implementations for their MaybeRefresh() semantics.

This is a Lucene.NET EXPERIMENTAL API, use at your own risk

Inheritance

System.Object

ReferenceManager<G>

ReaderManager

SearcherManager

Implements

System.IDisposable

Inherited Members

System.Object.Equals(System.Object)

System.Object.Equals(System.Object, System.Object)

System.Object.GetHashCode()

System.Object.GetType()

System.Object.MemberwiseClone()

System.Object.ReferenceEquals(System.Object, System.Object)

System.Object.ToString()

Namespace: Lucene.Net.Search

Assembly: Lucene.Net.dll

Syntax

public abstract class ReferenceManager<G> : IDisposable where G : class

Type Parameters

Name	Description
G	The concrete type that will be Acquire()d and Release(G)d.

Properties

| Improve this Doc View Source

Current

The current reference

Declaration

protected G Current { get; set; }

Property Value

Type	Description
G

Methods

| Improve this Doc View Source

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.

Declaration

public G Acquire()

Returns

Type	Description
G

Exceptions

Type	Condition
System.ObjectDisposedException	If the reference manager has been Dispose()d.

| Improve this Doc View Source

AddListener(ReferenceManager.IRefreshListener)

Adds a listener, to be notified when a reference is refreshed/swapped.

Declaration

public virtual void AddListener(ReferenceManager.IRefreshListener listener)

Parameters

Type	Name	Description
ReferenceManager.IRefreshListener	listener

| Improve this Doc View Source

AfterMaybeRefresh()

Called after a refresh was attempted, regardless of whether a new reference was in fact created.

Declaration

protected virtual void AfterMaybeRefresh()

Exceptions

Type	Condition
System.IO.IOException	if a low level I/O exception occurs

| Improve this Doc View Source

DecRef(G)

Decrement reference counting on the given reference.

Declaration

protected abstract void DecRef(G reference)

Parameters

Type	Name	Description
G	reference

Exceptions

Type	Condition
System.IO.IOException	If reference decrement on the given resource failed.

| Improve this Doc View Source

Dispose()

Closes this ReferenceManager to prevent future Acquire()ing. A reference manager should be disposed if the reference to the managed resource should be disposed or the application using the ReferenceManager<G> is shutting down. The managed resource might not be released immediately, if the ReferenceManager<G> user is holding on to a previously Acquire()d reference. The resource will be released once when the last reference is Release(G)d. Those references can still be used as if the manager was still active.

Applications should not Acquire() new references from this manager once this method has been called. Acquire()ing a resource on a disposed ReferenceManager<G> will throw an System.ObjectDisposedException.

Declaration

public void Dispose()

Exceptions

Type	Condition
System.IO.IOException	If the underlying reader of the current reference could not be disposed

| Improve this Doc View Source

Dispose(Boolean)

Called after Dispose(), so subclass can free any resources.

When overriding, be sure to include a call to base.Dispose(disposing) in your implementation.

Declaration

protected virtual void Dispose(bool disposing)

Parameters

Type	Name	Description
System.Boolean	disposing

Exceptions

Type	Condition
System.IO.IOException	if the after dispose operation in a sub-class throws an System.IO.IOException

| Improve this Doc View Source

GetRefCount(G)

Returns the current reference count of the given reference.

Declaration

protected abstract int GetRefCount(G reference)

Parameters

Type	Name	Description
G	reference

Returns

Type	Description
System.Int32

| Improve this Doc View Source

MaybeRefresh()

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.

Declaration

public bool MaybeRefresh()

Returns

Type	Description
System.Boolean

Exceptions

Type	Condition
System.IO.IOException	If refreshing the resource causes an System.IO.IOException
System.ObjectDisposedException	If the reference manager has been Dispose()d.

| Improve this Doc View Source

MaybeRefreshBlocking()

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().

Declaration

public void MaybeRefreshBlocking()

Exceptions

Type	Condition
System.IO.IOException	If refreshing the resource causes an System.IO.IOException
System.ObjectDisposedException	If the reference manager has been Dispose()d.

| Improve this Doc View Source

RefreshIfNeeded(G)

Refresh the given reference if needed. Returns null if no refresh was needed, otherwise a new refreshed reference.

Declaration

protected abstract G RefreshIfNeeded(G referenceToRefresh)

Parameters

Type	Name	Description
G	referenceToRefresh

Returns

Type	Description
G

Exceptions

Type	Condition
System.ObjectDisposedException	If the reference manager has been Dispose()d.
System.IO.IOException	If the refresh operation failed

| Improve this Doc View Source

Release(G)

Release the reference previously obtained via Acquire().

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

Declaration

public void Release(G reference)

Parameters

Type	Name	Description
G	reference

Exceptions

Type	Condition
System.IO.IOException	If the release operation on the given resource throws an System.IO.IOException

| Improve this Doc View Source

RemoveListener(ReferenceManager.IRefreshListener)

Remove a listener added with AddListener(ReferenceManager.IRefreshListener).

Declaration

public virtual void RemoveListener(ReferenceManager.IRefreshListener listener)

Parameters

Type	Name	Description
ReferenceManager.IRefreshListener	listener

| Improve this Doc View Source

TryIncRef(G)

Try to increment reference counting on the given reference. Returns true if the operation was successful.

Declaration

protected abstract bool TryIncRef(G reference)

Parameters

Type	Name	Description
G	reference

Returns

Type	Description
System.Boolean

Exceptions

Type	Condition
System.ObjectDisposedException	if the reference manager has been Dispose()d.

Implements

System.IDisposable

Extension Methods

ReferenceManagerExtensions.GetContext<T>(ReferenceManager<T>)