--- jsr166/src/main/java/util/PriorityQueue.java 2003/07/01 16:29:45 1.8 +++ jsr166/src/main/java/util/PriorityQueue.java 2003/09/01 12:23:28 1.38 @@ -1,38 +1,68 @@ - package java.util; +/* + * %W% %E% + * + * Copyright 2003 Sun Microsystems, Inc. All rights reserved. + * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms. + */ + +package java.util; /** - * An unbounded priority queue based on a priority heap. This queue orders - * elements according to an order specified at construction time, which is - * specified in the same manner as {@link TreeSet} and {@link TreeMap}: elements are ordered - * either according to their natural order (see {@link Comparable}), or - * according to a {@link Comparator}, depending on which constructor is used. - * The {@link #peek}, {@link #poll}, and {@link #remove} methods return the - * minimal element with respect to the specified ordering. If multiple - * elements are tied for least value, no guarantees are made as to - * which of these elements is returned. + * An unbounded priority {@linkplain Queue queue} based on a priority heap. + * This queue orders elements according to an order specified at construction + * time, which is specified in the same manner as {@link java.util.TreeSet} + * and {@link java.util.TreeMap}: elements are ordered either according to + * their natural order (see {@link Comparable}), or according to a + * {@link java.util.Comparator}, depending on which constructor is used. + *

The head of this queue is the least element with + * respect to the specified ordering. If multiple elements are tied for least + * value, the head is one of those elements. A priority queue does not permit + * null elements. + * + *

The {@link #remove()} and {@link #poll()} methods remove and + * return the head of the queue. + * + *

The {@link #element()} and {@link #peek()} methods return, but do + * not delete, the head of the queue. * *

A priority queue has a capacity. The capacity is the * size of the array used internally to store the elements on the - * queue. It is always at least as large as the queue size. As + * queue. + * It is always at least as large as the queue size. As * elements are added to a priority queue, its capacity grows * automatically. The details of the growth policy are not specified. * - *

Implementation note: this implementation provides O(log(n)) time - *for the insertion methods (offer, poll, - *remove() and add) methods; linear time for the - *remove(Object) and contains(Object) methods; and - *constant time for the retrieval methods (peek, - *element, and size). + *

The Iterator provided in method {@link #iterator()} is not + * guaranteed to traverse the elements of the PriorityQueue in any + * particular order. If you need ordered traversal, consider using + * Arrays.sort(pq.toArray()). + * + *

Note that this implementation is not synchronized. + * Multiple threads should not access a PriorityQueue + * instance concurrently if any of the threads modifies the list + * structurally. Instead, use the thread-safe {@link + * java.util.concurrent.PriorityBlockingQueue} class. + * + * + *

Implementation note: this implementation provides O(log(n)) time + * for the insertion methods (offer, poll, + * remove() and add) methods; linear time for the + * remove(Object) and contains(Object) methods; and + * constant time for the retrieval methods (peek, + * element, and size). * *

This class is a member of the * * Java Collections Framework. * @since 1.5 + * @version %I%, %G% * @author Josh Bloch */ public class PriorityQueue extends AbstractQueue - implements Queue, - java.io.Serializable { + implements Queue, java.io.Serializable { + + private static final long serialVersionUID = -7720805057305804111L; + private static final int DEFAULT_INITIAL_CAPACITY = 11; /** @@ -48,7 +78,7 @@ public class PriorityQueue extends Ab * * queue.length must be >= 2, even if size == 0. */ - private transient E[] queue; + private transient Object[] queue; /** * The number of elements in the priority queue. @@ -59,7 +89,7 @@ public class PriorityQueue extends Ab * The comparator, or null if priority queue uses elements' * natural ordering. */ - private final Comparator comparator; + private final Comparator comparator; /** * The number of times this priority queue has been @@ -68,143 +98,286 @@ public class PriorityQueue extends Ab private transient int modCount = 0; /** - * Create a new priority queue with the default initial capacity + * Creates a PriorityQueue with the default initial capacity * (11) that orders its elements according to their natural - * ordering (using Comparable.) + * ordering (using Comparable). */ public PriorityQueue() { - this(DEFAULT_INITIAL_CAPACITY); + this(DEFAULT_INITIAL_CAPACITY, null); } /** - * Create a new priority queue with the specified initial capacity + * Creates a PriorityQueue with the specified initial capacity * that orders its elements according to their natural ordering - * (using Comparable.) + * (using Comparable). * * @param initialCapacity the initial capacity for this priority queue. + * @throws IllegalArgumentException if initialCapacity is less + * than 1 */ public PriorityQueue(int initialCapacity) { this(initialCapacity, null); } /** - * Create a new priority queue with the specified initial capacity (11) + * Creates a PriorityQueue with the specified initial capacity * that orders its elements according to the specified comparator. * * @param initialCapacity the initial capacity for this priority queue. * @param comparator the comparator used to order this priority queue. + * If null then the order depends on the elements' natural + * ordering. + * @throws IllegalArgumentException if initialCapacity is less + * than 1 */ - public PriorityQueue(int initialCapacity, Comparator comparator) { + public PriorityQueue(int initialCapacity, + Comparator comparator) { if (initialCapacity < 1) - initialCapacity = 1; - queue = new E[initialCapacity + 1]; + throw new IllegalArgumentException(); + this.queue = new Object[initialCapacity + 1]; this.comparator = comparator; } /** - * Create a new priority queue containing the elements in the specified - * collection. The priority queue has an initial capacity of 110% of the - * size of the specified collection. If the specified collection - * implements the {@link Sorted} interface, the priority queue will be - * sorted according to the same comparator, or according to its elements' - * natural order if the collection is sorted according to its elements' - * natural order. If the specified collection does not implement - * Sorted, the priority queue is ordered according to - * its elements' natural order. - * - * @param initialElements the collection whose elements are to be placed - * into this priority queue. - * @throws ClassCastException if elements of the specified collection - * cannot be compared to one another according to the priority - * queue's ordering. - * @throws NullPointerException if the specified collection or an - * element of the specified collection is null. + * Common code to initialize underlying queue array across + * constructors below. */ - public PriorityQueue(Collection initialElements) { - int sz = initialElements.size(); + private void initializeArray(Collection c) { + int sz = c.size(); int initialCapacity = (int)Math.min((sz * 110L) / 100, Integer.MAX_VALUE - 1); if (initialCapacity < 1) initialCapacity = 1; - queue = new E[initialCapacity + 1]; + this.queue = new Object[initialCapacity + 1]; + } + + /** + * Initially fill elements of the queue array under the + * knowledge that it is sorted or is another PQ, in which + * case we can just place the elements in the order presented. + */ + private void fillFromSorted(Collection c) { + for (Iterator i = c.iterator(); i.hasNext(); ) + queue[++size] = i.next(); + } + + /** + * Initially fill elements of the queue array that is not to our knowledge + * sorted, so we must rearrange the elements to guarantee the heap + * invariant. + */ + private void fillFromUnsorted(Collection c) { + for (Iterator i = c.iterator(); i.hasNext(); ) + queue[++size] = i.next(); + heapify(); + } - if (initialElements instanceof Sorted) { - comparator = ((Sorted)initialElements).comparator(); - for (Iterator i = initialElements.iterator(); i.hasNext(); ) - queue[++size] = i.next(); + /** + * Creates a PriorityQueue containing the elements in the + * specified collection. The priority queue has an initial + * capacity of 110% of the size of the specified collection or 1 + * if the collection is empty. If the specified collection is an + * instance of a {@link java.util.SortedSet} or is another + * PriorityQueue, the priority queue will be sorted + * according to the same comparator, or according to its elements' + * natural order if the collection is sorted according to its + * elements' natural order. Otherwise, the priority queue is + * ordered according to its elements' natural order. + * + * @param c the collection whose elements are to be placed + * into this priority queue. + * @throws ClassCastException if elements of the specified collection + * cannot be compared to one another according to the priority + * queue's ordering. + * @throws NullPointerException if c or any element within it + * is null + */ + public PriorityQueue(Collection c) { + initializeArray(c); + if (c instanceof SortedSet) { + // @fixme double-cast workaround for compiler + SortedSet s = (SortedSet) (SortedSet)c; + comparator = (Comparator)s.comparator(); + fillFromSorted(s); + } else if (c instanceof PriorityQueue) { + PriorityQueue s = (PriorityQueue) c; + comparator = (Comparator)s.comparator(); + fillFromSorted(s); } else { comparator = null; - for (Iterator i = initialElements.iterator(); i.hasNext(); ) - add(i.next()); + fillFromUnsorted(c); + } + } + + /** + * Creates a PriorityQueue containing the elements in the + * specified collection. The priority queue has an initial + * capacity of 110% of the size of the specified collection or 1 + * if the collection is empty. This priority queue will be sorted + * according to the same comparator as the given collection, or + * according to its elements' natural order if the collection is + * sorted according to its elements' natural order. + * + * @param c the collection whose elements are to be placed + * into this priority queue. + * @throws ClassCastException if elements of the specified collection + * cannot be compared to one another according to the priority + * queue's ordering. + * @throws NullPointerException if c or any element within it + * is null + */ + public PriorityQueue(PriorityQueue c) { + initializeArray(c); + comparator = (Comparator)c.comparator(); + fillFromSorted(c); + } + + /** + * Creates a PriorityQueue containing the elements in the + * specified collection. The priority queue has an initial + * capacity of 110% of the size of the specified collection or 1 + * if the collection is empty. This priority queue will be sorted + * according to the same comparator as the given collection, or + * according to its elements' natural order if the collection is + * sorted according to its elements' natural order. + * + * @param c the collection whose elements are to be placed + * into this priority queue. + * @throws ClassCastException if elements of the specified collection + * cannot be compared to one another according to the priority + * queue's ordering. + * @throws NullPointerException if c or any element within it + * is null + */ + public PriorityQueue(SortedSet c) { + initializeArray(c); + comparator = (Comparator)c.comparator(); + fillFromSorted(c); + } + + /** + * Resize array, if necessary, to be able to hold given index + */ + private void grow(int index) { + int newlen = queue.length; + if (index < newlen) // don't need to grow + return; + if (index == Integer.MAX_VALUE) + throw new OutOfMemoryError(); + while (newlen <= index) { + if (newlen >= Integer.MAX_VALUE / 2) // avoid overflow + newlen = Integer.MAX_VALUE; + else + newlen <<= 2; } + Object[] newQueue = new Object[newlen]; + System.arraycopy(queue, 0, newQueue, 0, queue.length); + queue = newQueue; } + // Queue Methods /** - * Remove and return the minimal element from this priority queue - * if it contains one or more elements, otherwise return - * null. The term minimal is defined according to - * this priority queue's order. + * Add the specified element to this priority queue. * - * @return the minimal element from this priority queue if it contains - * one or more elements, otherwise null. + * @return true + * @throws ClassCastException if the specified element cannot be compared + * with elements currently in the priority queue according + * to the priority queue's ordering. + * @throws NullPointerException if the specified element is null. */ + public boolean offer(E o) { + if (o == null) + throw new NullPointerException(); + modCount++; + ++size; + + // Grow backing store if necessary + if (size >= queue.length) + grow(size); + + queue[size] = o; + fixUp(size); + return true; + } + public E poll() { if (size == 0) return null; - return remove(1); + return remove(); } + public E peek() { + return (E) queue[1]; + } + + // Collection Methods - the first two override to update docs + /** - * Return, but do not remove, the minimal element from the - * priority queue, or return null if the queue is empty. - * The term minimal is defined according to this priority - * queue's order. This method returns the same object reference - * that would be returned by by the poll method. The two - * methods differ in that this method does not remove the element - * from the priority queue. + * Adds the specified element to this queue. + * @return true (as per the general contract of + * Collection.add). * - * @return the minimal element from this priority queue if it contains - * one or more elements, otherwise null. + * @throws NullPointerException {@inheritDoc} + * @throws ClassCastException if the specified element cannot be compared + * with elements currently in the priority queue according + * to the priority queue's ordering. */ - public E peek() { - return queue[1]; + public boolean add(E o) { + return super.add(o); + } + + + /** + * Adds all of the elements in the specified collection to this queue. + * The behavior of this operation is undefined if + * the specified collection is modified while the operation is in + * progress. (This implies that the behavior of this call is undefined if + * the specified collection is this queue, and this queue is nonempty.) + *

+ * This implementation iterates over the specified collection, and adds + * each object returned by the iterator to this collection, in turn. + * @throws NullPointerException {@inheritDoc} + * @throws ClassCastException if any element cannot be compared + * with elements currently in the priority queue according + * to the priority queue's ordering. + */ + public boolean addAll(Collection c) { + return super.addAll(c); } - // Collection Methods /** - * Removes a single instance of the specified element from this priority - * queue, if it is present. Returns true if this collection contained the - * specified element (or equivalently, if this collection changed as a + * Removes a single instance of the specified element from this + * queue, if it is present. More formally, + * removes an element e such that (o==null ? e==null : + * o.equals(e)), if the queue contains one or more such + * elements. Returns true if the queue contained the + * specified element (or equivalently, if the queue changed as a * result of the call). * - * @param element the element to be removed from this collection, - * if present. - * @return true if this collection changed as a result of the - * call - * @throws ClassCastException if the specified element cannot be compared - * with elements currently in the priority queue according - * to the priority queue's ordering. - * @throws NullPointerException if the specified element is null. + *

This implementation iterates over the queue looking for the + * specified element. If it finds the element, it removes the element + * from the queue using the iterator's remove method.

+ * */ - public boolean remove(Object element) { - if (element == null) - throw new NullPointerException(); + public boolean remove(Object o) { + if (o == null) + return false; if (comparator == null) { for (int i = 1; i <= size; i++) { - if (((Comparable)queue[i]).compareTo(element) == 0) { - remove(i); + if (((Comparable)queue[i]).compareTo((E)o) == 0) { + removeAt(i); return true; } } } else { for (int i = 1; i <= size; i++) { - if (comparator.compare(queue[i], (E) element) == 0) { - remove(i); + if (comparator.compare((E)queue[i], (E)o) == 0) { + removeAt(i); return true; } } @@ -213,18 +386,17 @@ public class PriorityQueue extends Ab } /** - * Returns an iterator over the elements in this priority queue. The - * elements of the priority queue will be returned by this iterator in the - * order specified by the queue, which is to say the order they would be - * returned by repeated calls to poll. - * - * @return an Iterator over the elements in this priority queue. + * Returns an iterator over the elements in this queue. The iterator + * does not return the elements in any particular order. + * + * @return an iterator over the elements in this queue. */ public Iterator iterator() { return new Itr(); } private class Itr implements Iterator { + /** * Index (into queue array) of element to be returned by * subsequent call to next. @@ -232,9 +404,9 @@ public class PriorityQueue extends Ab private int cursor = 1; /** - * Index of element returned by most recent call to next or - * previous. Reset to 0 if this element is deleted by a call - * to remove. + * Index of element returned by most recent call to next, + * unless that element came from the forgetMeNot list. + * Reset to 0 if element is deleted by a call to remove. */ private int lastRet = 0; @@ -245,28 +417,69 @@ public class PriorityQueue extends Ab */ private int expectedModCount = modCount; + /** + * A list of elements that were moved from the unvisited portion of + * the heap into the visited portion as a result of "unlucky" element + * removals during the iteration. (Unlucky element removals are those + * that require a fixup instead of a fixdown.) We must visit all of + * the elements in this list to complete the iteration. We do this + * after we've completed the "normal" iteration. + * + * We expect that most iterations, even those involving removals, + * will not use need to store elements in this field. + */ + private ArrayList forgetMeNot = null; + + /** + * Element returned by the most recent call to next iff that + * element was drawn from the forgetMeNot list. + */ + private Object lastRetElt = null; + public boolean hasNext() { - return cursor <= size; + return cursor <= size || forgetMeNot != null; } public E next() { checkForComodification(); - if (cursor > size) + E result; + if (cursor <= size) { + result = (E) queue[cursor]; + lastRet = cursor++; + } + else if (forgetMeNot == null) throw new NoSuchElementException(); - E result = queue[cursor]; - lastRet = cursor++; + else { + int remaining = forgetMeNot.size(); + result = forgetMeNot.remove(remaining - 1); + if (remaining == 1) + forgetMeNot = null; + lastRet = 0; + lastRetElt = result; + } return result; } public void remove() { - if (lastRet == 0) - throw new IllegalStateException(); checkForComodification(); - PriorityQueue.this.remove(lastRet); - if (lastRet < cursor) - cursor--; - lastRet = 0; + if (lastRet != 0) { + E moved = PriorityQueue.this.removeAt(lastRet); + lastRet = 0; + if (moved == null) { + cursor--; + } else { + if (forgetMeNot == null) + forgetMeNot = new ArrayList(); + forgetMeNot.add(moved); + } + } else if (lastRetElt != null) { + PriorityQueue.this.remove(lastRetElt); + lastRetElt = null; + } else { + throw new IllegalStateException(); + } + expectedModCount = modCount; } @@ -276,72 +489,69 @@ public class PriorityQueue extends Ab } } - /** - * Returns the number of elements in this priority queue. - * - * @return the number of elements in this priority queue. - */ public int size() { return size; } /** - * Add the specified element to this priority queue. - * - * @param element the element to add. - * @return true - * @throws ClassCastException if the specified element cannot be compared - * with elements currently in the priority queue according - * to the priority queue's ordering. - * @throws NullPointerException if the specified element is null. + * Remove all elements from the priority queue. */ - public boolean offer(E element) { - if (element == null) - throw new NullPointerException(); + public void clear() { modCount++; - // Grow backing store if necessary - if (++size == queue.length) { - E[] newQueue = new E[2 * queue.length]; - System.arraycopy(queue, 0, newQueue, 0, size); - queue = newQueue; - } + // Null out element references to prevent memory leak + for (int i=1; i<=size; i++) + queue[i] = null; - queue[size] = element; - fixUp(size); - return true; + size = 0; } /** - * Remove all elements from the priority queue. + * Removes and returns the first element from queue. */ - public void clear() { + public E remove() { + if (size == 0) + throw new NoSuchElementException(); modCount++; - // Null out element references to prevent memory leak - for (int i=1; i<=size; i++) - queue[i] = null; + E result = (E) queue[1]; + queue[1] = queue[size]; + queue[size--] = null; // Drop extra ref to prevent memory leak + if (size > 1) + fixDown(1); - size = 0; + return result; } /** - * Removes and returns the ith element from queue. Recall - * that queue is one-based, so 1 <= i <= size. + * Removes and returns the ith element from queue. (Recall that queue + * is one-based, so 1 <= i <= size.) * - * XXX: Could further special-case i==size, but is it worth it? - * XXX: Could special-case i==0, but is it worth it? + * Normally this method leaves the elements at positions from 1 up to i-1, + * inclusive, untouched. Under these circumstances, it returns null. + * Occasionally, in order to maintain the heap invariant, it must move + * the last element of the list to some index in the range [2, i-1], + * and move the element previously at position (i/2) to position i. + * Under these circumstances, this method returns the element that was + * previously at the end of the list and is now at some position between + * 2 and i-1 inclusive. */ - private E remove(int i) { - assert i <= size; + private E removeAt(int i) { + assert i > 0 && i <= size; modCount++; - E result = queue[i]; - queue[i] = queue[size]; + E moved = (E) queue[size]; + queue[i] = moved; queue[size--] = null; // Drop extra ref to prevent memory leak - if (i <= size) + if (i <= size) { fixDown(i); - return result; + if (queue[i] == moved) { + fixUp(i); + if (queue[i] != moved) + return moved; + } + } + return null; } /** @@ -357,17 +567,17 @@ public class PriorityQueue extends Ab if (comparator == null) { while (k > 1) { int j = k >> 1; - if (((Comparable)queue[j]).compareTo(queue[k]) <= 0) + if (((Comparable)queue[j]).compareTo((E)queue[k]) <= 0) break; - E tmp = queue[j]; queue[j] = queue[k]; queue[k] = tmp; + Object tmp = queue[j]; queue[j] = queue[k]; queue[k] = tmp; k = j; } } else { while (k > 1) { - int j = k >> 1; - if (comparator.compare(queue[j], queue[k]) <= 0) + int j = k >>> 1; + if (comparator.compare((E)queue[j], (E)queue[k]) <= 0) break; - E tmp = queue[j]; queue[j] = queue[k]; queue[k] = tmp; + Object tmp = queue[j]; queue[j] = queue[k]; queue[k] = tmp; k = j; } } @@ -385,34 +595,47 @@ public class PriorityQueue extends Ab private void fixDown(int k) { int j; if (comparator == null) { - while ((j = k << 1) <= size) { - if (j 0) + while ((j = k << 1) <= size && (j > 0)) { + if (j)queue[j]).compareTo((E)queue[j+1]) > 0) j++; // j indexes smallest kid - if (((Comparable)queue[k]).compareTo(queue[j]) <= 0) + + if (((Comparable)queue[k]).compareTo((E)queue[j]) <= 0) break; - E tmp = queue[j]; queue[j] = queue[k]; queue[k] = tmp; + Object tmp = queue[j]; queue[j] = queue[k]; queue[k] = tmp; k = j; } } else { - while ((j = k << 1) <= size) { - if (j < size && comparator.compare(queue[j], queue[j+1]) > 0) + while ((j = k << 1) <= size && (j > 0)) { + if (j 0) j++; // j indexes smallest kid - if (comparator.compare(queue[k], queue[j]) <= 0) + if (comparator.compare((E)queue[k], (E)queue[j]) <= 0) break; - E tmp = queue[j]; queue[j] = queue[k]; queue[k] = tmp; + Object tmp = queue[j]; queue[j] = queue[k]; queue[k] = tmp; k = j; } } } /** - * Returns the comparator associated with this priority queue, or - * null if it uses its elements' natural ordering. + * Establishes the heap invariant (described above) in the entire tree, + * assuming nothing about the order of the elements prior to the call. + */ + private void heapify() { + for (int i = size/2; i >= 1; i--) + fixDown(i); + } + + /** + * Returns the comparator used to order this collection, or null + * if this collection is sorted according to its elements natural ordering + * (using Comparable). * - * @return the comparator associated with this priority queue, or - * null if it uses its elements' natural ordering. + * @return the comparator used to order this collection, or null + * if this collection is sorted according to its elements natural ordering. */ - public Comparator comparator() { + public Comparator comparator() { return comparator; } @@ -425,7 +648,7 @@ public class PriorityQueue extends Ab * Object) in the proper order. * @param s the stream */ - private synchronized void writeObject(java.io.ObjectOutputStream s) + private void writeObject(java.io.ObjectOutputStream s) throws java.io.IOException{ // Write out element count, and any hidden stuff s.defaultWriteObject(); @@ -443,18 +666,18 @@ public class PriorityQueue extends Ab * deserialize it). * @param s the stream */ - private synchronized void readObject(java.io.ObjectInputStream s) + private void readObject(java.io.ObjectInputStream s) throws java.io.IOException, ClassNotFoundException { // Read in size, and any hidden stuff s.defaultReadObject(); // Read in array length and allocate array int arrayLength = s.readInt(); - queue = new E[arrayLength]; + queue = new Object[arrayLength]; // Read in all elements in the proper order. for (int i=0; i