BREAKING: Introducing ValuePriorityQueue<T>

[NightOwl888]

This adds a new ref struct to the project, Lucene.Net.Util.ValuePriorityQueue<T>. This struct contains the most of the same API and business logic as PriorityQueue<T>, but allows the memory used to be allocated elsewhere as Span<T> and passed in.

The amount to allocate can be calculated by calling PriorityQueue.GetArrayHeapSize(maxSize), where maxSize is the external size of the PriorityQueue (representing the same value that is passed into the constructor of the current PriorityQueue<T>). The actual allocation amount is 1 greater than the priority queue size because it is 1-based rather than 0-based.

We get around the issue with structs not being inheritable by introducing a new PriorityComparer<T> abstract class with a single bool LessThan(T a, T b) method. This signature makes converting existing subclasses of PriorityQueue<T> to PriorityComparer<T> straightforward, as there are no business logic changes to make. This IComparer<T> is a required constructor argument of ValuePriorityQueue<T>. It can be either a PriorityComparer<T> or IComparer<T>, although if it returns a 0 (equal), that value is considered the same as 1 (greater than) by the priority queue.

This also modifies SingleTaxonomyFacets, Int32TaxonomyFacets, TopDocs merge and FST pack to use ValuePriorityQueue<T> and converts the item types they deal with from class to struct so they can be stack allocated if the size is below Constants.MaxStackByteLimit, which is set using the system property maxStackByteLimit.

Closes #774. Thanks @eladmarg for the suggestion.

There are a few more places in the codebase where this type can be useful, but unfortunately the types they use don't convert easily into structs so although we can eliminate the heap allocation of the priority queue itself, we will need some configuration and/or logic to decide whether to allocate the array directly or use an array pool.

Breaking Changes

1. Changed OrdAndValue<T> from class to struct.
2. Added generic constraint to OrdAndValue<T> where T : struct.

[laimis]

This looks like a great change! Nicely done!

[eladmarg]

fantastic!
sometimes the priority queue size is so small, no need even to rent and allocate on the stack is much faster.

by the way, net 7 finally introduce PriorityQueue implementation, however this one seems to be more specific and faster.