PriorityQueue (Lucene 10.5.0 core API)
Description: declaration: package: org.apache.lucene.util, class: PriorityQueue

Package org.apache.lucene.util

# Class PriorityQueue<T>

java.lang.Object
org.apache.lucene.util.PriorityQueue<T>

All Implemented Interfaces:
  `Iterable<T>`

Direct Known Subclasses:
  `FieldValueHitQueue`, `HitQueue`

public abstract class PriorityQueue<T> extends Object implements Iterable<T>
A priority queue maintains a partial ordering of its elements such that the least element can always be found in constant time. Put()'s and pop()'s require log(size) time but the remove() cost implemented here is linear.

NOTE: This class pre-allocates an array of length `maxSize+1` and pre-fills it with elements if instantiated via the `PriorityQueue(int,Supplier)` constructor.

NOTE: Iteration order is not specified.

NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `PriorityQueue(int maxSize)`
  Create an empty priority queue of the configured size.
  `PriorityQueue(int maxSize, Supplier<T> sentinelObjectSupplier)`
  Create a priority queue that is pre-filled with sentinel objects, so that the code which uses that queue can always assume it's full and only change the top without attempting to insert any new object.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `final T`
  `add(T element)`
  Adds an Object to a PriorityQueue in log(size) time.
  `void`
  `addAll(Collection<T> elements)`
  Adds all elements of the collection into the queue.
  `void`
  `addAll(Stream<T> elements)`
  Adds all elements of the stream into the queue.
  `final void`
  `clear()`
  Removes all entries from the PriorityQueue.
  `protected final Object[]`
  `getHeapArray()`
  This method returns the internal heap array as Object[].
  `T`
  `insertWithOverflow(T element)`
  Adds an Object to a PriorityQueue in log(size) time.
  `Iterator<T>`
  `iterator()`
  `protected abstract boolean`
  `lessThan(T a, T b)`
  Determines the ordering of objects in this priority queue.
  `final T`
  `pop()`
  Removes and returns the least element of the PriorityQueue in log(size) time.
  `final boolean`
  `remove(T element)`
  Removes an existing element currently stored in the PriorityQueue.
  `final int`
  `size()`
  Returns the number of elements currently stored in the PriorityQueue.
  `final T`
  `top()`
  Returns the least element of the PriorityQueue in constant time.
  `final T`
  `updateTop()`
  Should be called when the Object at top changes values.
  `final T`
  `updateTop(T newTop)`
  Replace the top of the pq with `newTop` and run `updateTop()`.

  ### Methods inherited from class java.lang.Object

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

  ### Methods inherited from interface java.lang.Iterable

  `forEach, spliterator`

- ## Constructor Details

  - ### PriorityQueue

    public PriorityQueue(int maxSize)
    Create an empty priority queue of the configured size.

  - ### PriorityQueue

    public PriorityQueue(int maxSize, Supplier<T> sentinelObjectSupplier)
    Create a priority queue that is pre-filled with sentinel objects, so that the code which uses that queue can always assume it's full and only change the top without attempting to insert any new object.

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

    By default, the supplier returns null, which means the queue will not be filled with sentinel values. Otherwise, the value returned will be used to pre-populate the queue.

    If this method is extended to return a non-null value, then the following usage pattern is recommended:

         PriorityQueue<MyObject> pq = new MyQueue<MyObject>(numHits);
         // save the 'top' element, which is guaranteed to not be null.
         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: the given supplier will be called `maxSize` times, relying on a new object to be returned and will not check if it's null again. Therefore you should ensure any call to this method creates a new instance and behaves consistently, e.g., it cannot return null if it previously returned non-null and all returned instances must `compare equal`.

- ## Method Details

  - ### addAll

    public void addAll(Collection<T> elements)
    Adds all elements of the collection into the queue. This method should be preferred over calling `add(Object)` in loop if all elements are known in advance as it builds queue faster.

    If one tries to add more objects than the maxSize passed in the constructor, an `ArrayIndexOutOfBoundsException` is thrown. Which may result in parts of elements added into the queue, but the heap is still stay in correct state. In this case, if caller wants to readd or `updateTop(Object)` with remaining elements, it should skip(continue) consumed elements with the delta size of queue.

  - ### addAll

    public void addAll(Stream<T> elements)
    Adds all elements of the stream into the queue. This method should be preferred over calling `add(Object)` in loop if all elements are known in advance as it builds queue faster.

    If one needs to map or filter element in the iteration of elements in this method, call this method with elements wrapped by `Stream.map(Function)` or `Stream.filter(Predicate)`, etc. In these cases, this method should be preferred over calling `addAll(Collection)`.

    If one tries to add more objects than the maxSize passed in the constructor, an `ArrayIndexOutOfBoundsException` is thrown. Which may result in parts of elements added into the queue, but the heap is still stay in correct state. In this case, if caller wants to readd or `updateTop(Object)` with remaining elements, it should use a new stream, and use `Stream.skip(long)` to skip consumed elements with the delta size of queue.

  - ### lessThan

    protected abstract boolean lessThan(T a, T b)
    Determines the ordering of objects in this priority queue. Subclasses must define this one method.
    Returns:
      `true` iff parameter `a` is less than parameter `b`.

  - ### add

    public final T add(T element)
    Adds an Object to a PriorityQueue in log(size) time. If one tries to add more objects than maxSize from initialize an `ArrayIndexOutOfBoundsException` is thrown.
    Returns:
      the new 'top' element in the queue.

  - ### insertWithOverflow

    public T insertWithOverflow(T element)
    Adds an Object to a PriorityQueue in log(size) time. It returns the object (if any) that was dropped off the heap because it was full. This can be the given parameter (in case it is smaller than the full heap's minimum, and couldn't be added), or another object that was previously the smallest value in the heap and now has been replaced by a larger one, or null if the queue wasn't yet full with maxSize elements.

  - ### top

    public final T top()
    Returns the least element of the PriorityQueue in constant time.

  - ### pop

    public final T pop()
    Removes and returns the least element of the PriorityQueue in log(size) time.

  - ### updateTop

    public final T updateTop()
    Should be called when the Object at top changes values. Still log(n) worst case, but it's at least twice as fast to

         pq.top().change();
         pq.updateTop();

    instead of

         o = pq.pop();
         o.change();
         pq.push(o);

    Returns:
      the new 'top' element.

  - ### updateTop

    public final T updateTop(T newTop)
    Replace the top of the pq with `newTop` and run `updateTop()`.

  - ### size

    public final int size()
    Returns the number of elements currently stored in the PriorityQueue.

  - ### clear

    public final void clear()
    Removes all entries from the PriorityQueue.

  - ### remove

    public final boolean remove(T element)
    Removes an existing element currently stored in the PriorityQueue. Cost is linear with the size of the queue. (A specialization of PriorityQueue which tracks element positions would provide a constant remove time but the trade-off would be extra cost to all additions/insertions)

  - ### getHeapArray

    protected final Object[] getHeapArray()
    This method returns the internal heap array as Object[].
    NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

  - ### iterator

    public Iterator<T> iterator()
    Specified by:
      `iterator` in interface `Iterable<T>`