Interface ISentinelFactory<T>

Provides the sentinel instances of T to a PriorityQueue<T>.

Namespace: Lucene.Net.Util

Assembly: Lucene.Net.dll

Syntax

public interface ISentinelFactory<T>

Type Parameters

Name	Description
T	The type of sentinel instance to create.

Remarks

This interface can be implemented to provide sentinel instances. The implementation of this interface can be passed to a constructor of PriorityQueue<T> or ValuePriorityQueue<T>. If an instance is provided, the either constructor will use the Create() method to fill the queue, so that code which uses the queue can always assume it is full and only change the top without attempting to insert any new items.

Those sentinel values should always compare worse than any non-sentinel value (i.e., LessThan(T, T), LessThan(T, T), or Compare(T, T) should always favor the non-sentinel values).

When using a ISentinelFactory<T>, the following usage pattern is recommended:

// Implements ISentinelFactory<T>.Create(PriorityQueue<T>)
var sentinelFactory = new MySentinelFactory<MyObject>();
PriorityQueue<MyObject> pq = new MyQueue<MyObject>(sentinelFactory);
// save the 'top' element, which is guaranteed to not be default.
MyObject pqTop = pq.Top;
<...>
// now in order to add a new element, which is 'better' than top (after
// you've verified it is better), it is as simple as:
pqTop.Change();
pqTop = pq.UpdateTop();

NOTE:Create() will be called by the PriorityQueue<T> or ValuePriorityQueue<T> constructor Count or Count times, relying on a new instance to be returned. Therefore you should ensure any call to this Create() creates a new instance and behaves consistently, e.g., it cannot return null if it previously returned non-null.

Methods

Create()

Creates a sentinel instance of T to fill an element of a PriorityQueue<T>.

Declaration

T Create()

Returns

Type	Description
T	A newly created sentinel instance for use in a single element of PriorityQueue<T>.

Remarks

This interface can be implemented to provide sentinel instances. The implementation of this interface can be passed to a constructor of PriorityQueue<T> or ValuePriorityQueue<T>. If an instance is provided, the either constructor will use the Create() method to fill the queue, so that code which uses the queue can always assume it is full and only change the top without attempting to insert any new items.

Those sentinel values should always compare worse than any non-sentinel value (i.e., LessThan(T, T), LessThan(T, T), or Compare(T, T) should always favor the non-sentinel values).

When using a ISentinelFactory<T>, the following usage pattern is recommended:

// Implements ISentinelFactory<T>.Create(PriorityQueue<T>)
var sentinelFactory = new MySentinelFactory<MyObject>();
PriorityQueue<MyObject> pq = new MyQueue<MyObject>(sentinelFactory);
// save the 'top' element, which is guaranteed to not be default.
MyObject pqTop = pq.Top;
<...>
// now in order to add a new element, which is 'better' than top (after
// you've verified it is better), it is as simple as:
pqTop.Change();
pqTop = pq.UpdateTop();

NOTE:Create() will be called by the PriorityQueue<T> or ValuePriorityQueue<T> constructor Count or Count times, relying on a new instance to be returned. Therefore you should ensure any call to this Create() creates a new instance and behaves consistently, e.g., it cannot return null if it previously returned non-null.