edu.stanford.nlp.util
Interface PriorityQueue<E>

All Superinterfaces:
java.util.Collection<E>, java.lang.Iterable<E>, java.util.Set<E>
All Known Implementing Classes:
BinaryHeapPriorityQueue

public interface PriorityQueue<E>
extends java.util.Set<E>

A Set that also represents an ordering of its elements, and responds quickly to add(), changePriority(), removeFirst(), and getFirst() method calls.

There are several important differences between this interface and PriorityQueue:

  • This interface uses explicitly-assigned double values as priorities for queue elements, while java.util.PriorityQueue uses either the elements' natural order (see Comparable) or a Comparator.
  • In this interface, larger doubles represent higher priorities; in java.util.PriorityQueue, lesser elements (with respect to the specified ordering) have higher priorities.
  • This interface enables you to change the priority of an element after it has entered the queue. With java.util.PriorityQueue, that's not possible.
  • However, there is a price to pay for this flexibility. The primary implementation of this interface, BinaryHeapPriorityQueue, is roughly 2x slower than java.util.PriorityQueue in informal benchmark testing.
  • So, there's another implementation of this interface, FixedPrioritiesPriorityQueue, which trades flexibility for speed: while it is up to 2x faster than BinaryHeapPriorityQueue and nearly as fast as PriorityQueue, it does not support removing or changing the priority of an element. On the other hand, this interface and PriorityQueue also have some characteristics in common:

  • Both make no guarantee about the order in which elements with equal priority are returned from the queue. This does not mean that equal elements are returned in random order. (In fact they are returned in an order which depends on the order of insertion — but the implementations reserve the right to return them in any order whatsoever.)


    Method Summary
     boolean add(E key, double priority)
              Convenience method for if you want to pretend relaxPriority doesn't exist, or if you really want add's return conditions.
     boolean changePriority(E key, double priority)
              Changes a priority, either up or down, adding the key it if it wasn't there already.
     E getFirst()
              Finds the object with the highest priority and returns it, without modifying the queue.
     double getPriority(java.lang.Object key)
              Get the priority of a key.
     boolean relaxPriority(E key, double priority)
              Increases the priority of the Object key to the new priority if the old priority was lower than the new priority.
     E removeFirst()
              Finds the object with the highest priority, removes it, and returns it.
     java.util.List<E> toSortedList()
               
     
    Methods inherited from interface java.util.Set
    add, addAll, clear, contains, containsAll, equals, hashCode, isEmpty, iterator, remove, removeAll, retainAll, size, toArray, toArray
     

    Method Detail

    removeFirst

    E removeFirst()
    Finds the object with the highest priority, removes it, and returns it.

    Returns:
    the object with highest priority

    getFirst

    E getFirst()
    Finds the object with the highest priority and returns it, without modifying the queue.

    Returns:
    the object with minimum key

    getPriority

    double getPriority(java.lang.Object key)
    Get the priority of a key.

    Parameters:
    key - The object to assess
    Returns:
    A key's priority. If the key is not in the queue, Double.NEGATIVE_INFINITY is returned.

    add

    boolean add(E key,
                double priority)
    Convenience method for if you want to pretend relaxPriority doesn't exist, or if you really want add's return conditions.

    Returns:
    true if this set did not already contain the specified element.

    changePriority

    boolean changePriority(E key,
                           double priority)
    Changes a priority, either up or down, adding the key it if it wasn't there already.

    Parameters:
    key - an Object value
    Returns:
    whether the priority actually changed.

    relaxPriority

    boolean relaxPriority(E key,
                          double priority)
    Increases the priority of the Object key to the new priority if the old priority was lower than the new priority. Otherwise, does nothing.

    Parameters:
    key -
    priority -
    Returns:

    toSortedList

    java.util.List<E> toSortedList()