An unbounded {@linkplain Queue queue} that supports element retrievalin the order of relative priority. The ordering can be defined via an explicit comparator; otherwise, the natural ordering of elements is used. Element at the head of the queue is always the
smallest one according to the given ordering.
While this queue is logically unbounded, attempted additions may fail due to resource exhaustion (causing OutOfMemoryError). This class does not permit null elements. A priority queue relying on {@linkplain Comparable natural ordering} also does not permit insertion ofnon-comparable objects (doing so results in ClassCastException).
This class and its iterator implement all of the optional methods of the {@link Collection} and {@link Iterator} interfaces. The Iterator provided in method {@link #iterator()} is not guaranteed to traverse the elements ofthe PriorityQueue in any particular order. If you need ordered traversal, consider using Arrays.sort(pq.toArray()).
Operations on this class make no guarantees about the ordering of elements with equal priority. If you need to enforce an ordering, you can define custom classes or comparators that use a secondary key to break ties in primary priority values. See {@link edu.emory.mathcs.backport.java.util.concurrent.PriorityBlockingQueue}for an example.
Implementation note: basic mutative methods (insert, offer, remove, poll etc) have complexity O(log(n)). Parameterless inspection methods (peek, element,isEmpty) have complexity O(1). Methods contains(Object) and remove(Object) have complexity O(n).
@since 1.5
@author Dawid Kurzyniec