ViewVC Help

View File | Revision Log | Show Annotations | Download File | Root Listing

root/jsr166/jsr166/src/main/java/util/PriorityQueue.java

Comparing jsr166/src/main/java/util/PriorityQueue.java (file contents):
Revision 1.30 by dl, Mon Aug 25 18:33:03 2003 UTC vs.
Revision 1.41 by dl, Sat Sep 13 18:51:06 2003 UTC

#	Line 1 | Line 1
1	<	package java.util;
1	>	/*
2	>	* %W% %E%
3	>	*
4	>	* Copyright 2003 Sun Microsystems, Inc. All rights reserved.
5	>	* SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6	>	*/
7	>
8	>	package java.util;
9
10		/**
11	<	* An unbounded priority {@linkplain Queue queue} based on a priority heap.
12	<	* This queue orders
13	<	* elements according to an order specified at construction time, which is
14	<	* specified in the same manner as {@link java.util.TreeSet} and
15	<	* {@link java.util.TreeMap}: elements are ordered
16	<	* either according to their <i>natural order</i> (see {@link Comparable}), or
10	<	* according to a {@link java.util.Comparator}, depending on which
11	<	* constructor is used.
12	<	* <p>The <em>head</em> of this queue is the <em>least</em> element with
13	<	* respect to the specified ordering.
14	<	* If multiple elements are tied for least value, the
15	<	* head is one of those elements. A priority queue does not permit
16	<	* <tt>null</tt> elements.
17	<	*
18	<	* <p>The {@link #remove()} and {@link #poll()} methods remove and
19	<	* return the head of the queue.
11	>	* An unbounded priority {@linkplain Queue queue} based on a priority
12	>	* heap.  This queue orders elements according to an order specified
13	>	* at construction time, which is specified either according to their
14	>	* <i>natural order</i> (see {@link Comparable}), or according to a
15	>	* {@link java.util.Comparator}, depending on which constructor is
16	>	* used. A priority queue does not permit <tt>null</tt> elements.
17		*
18	<	* <p>The {@link #element()} and {@link #peek()} methods return, but do
19	<	* not delete, the head of the queue.
18	>	* <p>The <em>head</em> of this queue is the <em>least</em> element
19	>	* with respect to the specified ordering.  If multiple elements are
20	>	* tied for least value, the head is one of those elements -- ties are
21	>	* broken arbitrarily.  The {@link #remove()} and {@link #poll()}
22	>	* methods remove and return the head of the queue, and the {@link
23	>	* #element()} and {@link #peek()} methods return, but do not delete,
24	>	* the head of the queue.
25		*
26	<	* <p>A priority queue has a <i>capacity</i>.  The capacity is the
27	<	* size of the array used internally to store the elements on the
28	<	* queue.
29	<	* It is always at least as large as the queue size.  As
30	<	* elements are added to a priority queue, its capacity grows
31	<	* automatically.  The details of the growth policy are not specified.
26	>	* <p>A priority queue is unbounded, but has an internal
27	>	* <i>capacity</i> governing the size of an array used to store the
28	>	* elements on the queue.  It is always at least as large as the queue
29	>	* size.  As elements are added to a priority queue, its capacity
30	>	* grows automatically.  The details of the growth policy are not
31	>	* specified.
32		*
33	<	* <p>The Iterator provided in method {@link #iterator()} is <em>not</em>
33	>	* <p>This class implements all of the <em>optional</em> methods of
34	>	* the {@link Collection} and {@link Iterator} interfaces.  The
35	>	* Iterator provided in method {@link #iterator()} is <em>not</em>
36		* guaranteed to traverse the elements of the PriorityQueue in any
37		* particular order. If you need ordered traversal, consider using
38		* <tt>Arrays.sort(pq.toArray())</tt>.
#	Line 37 | Line 41
41		* Multiple threads should not access a <tt>PriorityQueue</tt>
42		* instance concurrently if any of the threads modifies the list
43		* structurally. Instead, use the thread-safe {@link
44	<	* java.util.concurrent.BlockingPriorityQueue} class.
44	>	* java.util.concurrent.PriorityBlockingQueue} class.
45		*
46		*
47		* <p>Implementation note: this implementation provides O(log(n)) time
#	Line 51 | Line 55
55		* <a href="{@docRoot}/../guide/collections/index.html">
56		* Java Collections Framework</a>.
57		* @since 1.5
58	+	* @version %I%, %G%
59		* @author Josh Bloch
60		*/
61		public class PriorityQueue<E> extends AbstractQueue<E>
62		implements Queue<E>, java.io.Serializable {
63
64	<	static final long serialVersionUID = -7720805057305804111L;
64	>	private static final long serialVersionUID = -7720805057305804111L;
65
66		private static final int DEFAULT_INITIAL_CAPACITY = 11;
67
#	Line 150 | Line 155 | public class PriorityQueue<E> extends Ab
155		/**
156		* Initially fill elements of the queue array under the
157		* knowledge that it is sorted or is another PQ, in which
158	<	* case we can just place the elements without fixups.
158	>	* case we can just place the elements in the order presented.
159		*/
160		private void fillFromSorted(Collection<? extends E> c) {
161		for (Iterator<? extends E> i = c.iterator(); i.hasNext(); )
162		queue[++size] = i.next();
163		}
164
160	–
165		/**
166	<	* Initially fill elements of the queue array that is
167	<	* not to our knowledge sorted, so we must add them
168	<	* one by one.
166	>	* Initially fill elements of the queue array that is not to our knowledge
167	>	* sorted, so we must rearrange the elements to guarantee the heap
168	>	* invariant.
169		*/
170		private void fillFromUnsorted(Collection<? extends E> c) {
171		for (Iterator<? extends E> i = c.iterator(); i.hasNext(); )
172	<	add(i.next());
172	>	queue[++size] = i.next();
173	>	heapify();
174		}
175
176		/**
#	Line 271 | Line 276 | public class PriorityQueue<E> extends Ab
276		queue = newQueue;
277		}
278
274	–	// Queue Methods
275	–
276	–
279
280		/**
281	<	* Add the specified element to this priority queue.
281	>	* Inserts the specified element to this priority queue.
282		*
283		* @return <tt>true</tt>
284		* @throws ClassCastException if the specified element cannot be compared
#	Line 299 | Line 301 | public class PriorityQueue<E> extends Ab
301		return true;
302		}
303
304	<	public E poll() {
304	>	public E peek() {
305		if (size == 0)
306		return null;
305	–	return (E) remove(1);
306	–	}
307	–
308	–	public E peek() {
307		return (E) queue[1];
308		}
309
#	Line 316 | Line 314 | public class PriorityQueue<E> extends Ab
314		* @return <tt>true</tt> (as per the general contract of
315		* <tt>Collection.add</tt>).
316		*
317	<	* @throws NullPointerException {@inheritDoc}
317	>	* @throws NullPointerException if the specified element is <tt>null</tt>.
318		* @throws ClassCastException if the specified element cannot be compared
319		* with elements currently in the priority queue according
320		* to the priority queue's ordering.
321		*/
322		public boolean add(E o) {
323	<	return super.add(o);
323	>	return offer(o);
324		}
325
326
#	Line 335 | Line 333 | public class PriorityQueue<E> extends Ab
333		* <p>
334		* This implementation iterates over the specified collection, and adds
335		* each object returned by the iterator to this collection, in turn.
336	<	* @throws NullPointerException {@inheritDoc}
336	>	* @param c collection whose elements are to be added to this queue
337	>	* @return <tt>true</tt> if this queue changed as a result of the
338	>	*         call.
339	>	* @throws NullPointerException if <tt>c</tt> or any element in <tt>c</tt>
340	>	* is <tt>null</tt>
341		* @throws ClassCastException if any element cannot be compared
342		* with elements currently in the priority queue according
343		* to the priority queue's ordering.
#	Line 344 | Line 346 | public class PriorityQueue<E> extends Ab
346		return super.addAll(c);
347		}
348
347	–
348	–	/**
349	–	* Removes a single instance of the specified element from this
350	–	* queue, if it is present.  More formally,
351	–	* removes an element <tt>e</tt> such that <tt>(o==null ? e==null :
352	–	* o.equals(e))</tt>, if the queue contains one or more such
353	–	* elements.  Returns <tt>true</tt> if the queue contained the
354	–	* specified element (or equivalently, if the queue changed as a
355	–	* result of the call).
356	–	*
357	–	* <p>This implementation iterates over the queue looking for the
358	–	* specified element.  If it finds the element, it removes the element
359	–	* from the queue using the iterator's remove method.<p>
360	–	*
361	–	*/
349		public boolean remove(Object o) {
350		if (o == null)
351		return false;
#	Line 366 | Line 353 | public class PriorityQueue<E> extends Ab
353		if (comparator == null) {
354		for (int i = 1; i <= size; i++) {
355		if (((Comparable<E>)queue[i]).compareTo((E)o) == 0) {
356	<	remove(i);
356	>	removeAt(i);
357		return true;
358		}
359		}
360		} else {
361		for (int i = 1; i <= size; i++) {
362		if (comparator.compare((E)queue[i], (E)o) == 0) {
363	<	remove(i);
363	>	removeAt(i);
364		return true;
365		}
366		}
#	Line 392 | Line 379 | public class PriorityQueue<E> extends Ab
379		}
380
381		private class Itr implements Iterator<E> {
382	+
383		/**
384		* Index (into queue array) of element to be returned by
385		* subsequent call to next.
#	Line 399 | Line 387 | public class PriorityQueue<E> extends Ab
387		private int cursor = 1;
388
389		/**
390	<	* Index of element returned by most recent call to next or
391	<	* previous.  Reset to 0 if this element is deleted by a call
392	<	* to remove.
390	>	* Index of element returned by most recent call to next,
391	>	* unless that element came from the forgetMeNot list.
392	>	* Reset to 0 if element is deleted by a call to remove.
393		*/
394		private int lastRet = 0;
395
#	Line 412 | Line 400 | public class PriorityQueue<E> extends Ab
400		*/
401		private int expectedModCount = modCount;
402
403	+	/**
404	+	* A list of elements that were moved from the unvisited portion of
405	+	* the heap into the visited portion as a result of "unlucky" element
406	+	* removals during the iteration.  (Unlucky element removals are those
407	+	* that require a fixup instead of a fixdown.)  We must visit all of
408	+	* the elements in this list to complete the iteration.  We do this
409	+	* after we've completed the "normal" iteration.
410	+	*
411	+	* We expect that most iterations, even those involving removals,
412	+	* will not use need to store elements in this field.
413	+	*/
414	+	private ArrayList<E> forgetMeNot = null;
415	+
416	+	/**
417	+	* Element returned by the most recent call to next iff that
418	+	* element was drawn from the forgetMeNot list.
419	+	*/
420	+	private Object lastRetElt = null;
421	+
422		public boolean hasNext() {
423	<	return cursor <= size;
423	>	return cursor <= size || forgetMeNot != null;
424		}
425
426		public E next() {
427		checkForComodification();
428	<	if (cursor > size)
428	>	E result;
429	>	if (cursor <= size) {
430	>	result = (E) queue[cursor];
431	>	lastRet = cursor++;
432	>	}
433	>	else if (forgetMeNot == null)
434		throw new NoSuchElementException();
435	<	E result = (E) queue[cursor];
436	<	lastRet = cursor++;
435	>	else {
436	>	int remaining = forgetMeNot.size();
437	>	result = forgetMeNot.remove(remaining - 1);
438	>	if (remaining == 1)
439	>	forgetMeNot = null;
440	>	lastRet = 0;
441	>	lastRetElt = result;
442	>	}
443		return result;
444		}
445
446		public void remove() {
429	–	if (lastRet == 0)
430	–	throw new IllegalStateException();
447		checkForComodification();
448
449	<	PriorityQueue.this.remove(lastRet);
450	<	if (lastRet < cursor)
451	<	cursor--;
452	<	lastRet = 0;
449	>	if (lastRet != 0) {
450	>	E moved = PriorityQueue.this.removeAt(lastRet);
451	>	lastRet = 0;
452	>	if (moved == null) {
453	>	cursor--;
454	>	} else {
455	>	if (forgetMeNot == null)
456	>	forgetMeNot = new ArrayList<E>();
457	>	forgetMeNot.add(moved);
458	>	}
459	>	} else if (lastRetElt != null) {
460	>	PriorityQueue.this.remove(lastRetElt);
461	>	lastRetElt = null;
462	>	} else {
463	>	throw new IllegalStateException();
464	>	}
465	>
466		expectedModCount = modCount;
467		}
468
#	Line 460 | Line 489 | public class PriorityQueue<E> extends Ab
489		size = 0;
490		}
491
492	+	public E poll() {
493	+	if (size == 0)
494	+	return null;
495	+	modCount++;
496	+
497	+	E result = (E) queue[1];
498	+	queue[1] = queue[size];
499	+	queue[size--] = null;  // Drop extra ref to prevent memory leak
500	+	if (size > 1)
501	+	fixDown(1);
502	+
503	+	return result;
504	+	}
505	+
506		/**
507	<	* Removes and returns the ith element from queue.  Recall
508	<	* that queue is one-based, so 1 <= i <= size.
507	>	* Removes and returns the ith element from queue.  (Recall that queue
508	>	* is one-based, so 1 <= i <= size.)
509		*
510	<	* XXX: Could further special-case i==size, but is it worth it?
511	<	* XXX: Could special-case i==0, but is it worth it?
510	>	* Normally this method leaves the elements at positions from 1 up to i-1,
511	>	* inclusive, untouched.  Under these circumstances, it returns null.
512	>	* Occasionally, in order to maintain the heap invariant, it must move
513	>	* the last element of the list to some index in the range [2, i-1],
514	>	* and move the element previously at position (i/2) to position i.
515	>	* Under these circumstances, this method returns the element that was
516	>	* previously at the end of the list and is now at some position between
517	>	* 2 and i-1 inclusive.
518		*/
519	<	private E remove(int i) {
520	<	assert i <= size;
519	>	private E removeAt(int i) {
520	>	assert i > 0 && i <= size;
521		modCount++;
522
523	<	E result = (E) queue[i];
524	<	queue[i] = queue[size];
523	>	E moved = (E) queue[size];
524	>	queue[i] = moved;
525		queue[size--] = null;  // Drop extra ref to prevent memory leak
526	<	if (i <= size)
526	>	if (i <= size) {
527		fixDown(i);
528	<	return result;
528	>	if (queue[i] == moved) {
529	>	fixUp(i);
530	>	if (queue[i] != moved)
531	>	return moved;
532	>	}
533	>	}
534	>	return null;
535		}
536
537		/**
#	Line 499 | Line 554 | public class PriorityQueue<E> extends Ab
554		}
555		} else {
556		while (k > 1) {
557	<	int j = k >> 1;
557	>	int j = k >>> 1;
558		if (comparator.compare((E)queue[j], (E)queue[k]) <= 0)
559		break;
560		Object tmp = queue[j];  queue[j] = queue[k]; queue[k] = tmp;
#	Line 520 | Line 575 | public class PriorityQueue<E> extends Ab
575		private void fixDown(int k) {
576		int j;
577		if (comparator == null) {
578	<	while ((j = k << 1) <= size) {
579	<	if (j<size && ((Comparable<E>)queue[j]).compareTo((E)queue[j+1]) > 0)
578	>	while ((j = k << 1) <= size && (j > 0)) {
579	>	if (j<size &&
580	>	((Comparable<E>)queue[j]).compareTo((E)queue[j+1]) > 0)
581		j++; // j indexes smallest kid
582	+
583		if (((Comparable<E>)queue[k]).compareTo((E)queue[j]) <= 0)
584		break;
585		Object tmp = queue[j];  queue[j] = queue[k]; queue[k] = tmp;
586		k = j;
587		}
588		} else {
589	<	while ((j = k << 1) <= size) {
590	<	if (j < size && comparator.compare((E)queue[j], (E)queue[j+1]) > 0)
589	>	while ((j = k << 1) <= size && (j > 0)) {
590	>	if (j<size &&
591	>	comparator.compare((E)queue[j], (E)queue[j+1]) > 0)
592		j++; // j indexes smallest kid
593		if (comparator.compare((E)queue[k], (E)queue[j]) <= 0)
594		break;
#	Line 540 | Line 598 | public class PriorityQueue<E> extends Ab
598		}
599		}
600
601	+	/**
602	+	* Establishes the heap invariant (described above) in the entire tree,
603	+	* assuming nothing about the order of the elements prior to the call.
604	+	*/
605	+	private void heapify() {
606	+	for (int i = size/2; i >= 1; i--)
607	+	fixDown(i);
608	+	}
609
610		/**
611		* Returns the comparator used to order this collection, or <tt>null</tt>
#	Line 571 | Line 637 | public class PriorityQueue<E> extends Ab
637		s.writeInt(queue.length);
638
639		// Write out all elements in the proper order.
640	<	for (int i=0; i<size; i++)
640	>	for (int i=1; i<=size; i++)
641		s.writeObject(queue[i]);
642		}
643
#	Line 590 | Line 656 | public class PriorityQueue<E> extends Ab
656		queue = new Object[arrayLength];
657
658		// Read in all elements in the proper order.
659	<	for (int i=0; i<size; i++)
660	<	queue[i] = s.readObject();
659	>	for (int i=1; i<=size; i++)
660	>	queue[i] = (E) s.readObject();
661		}
662
663		}
598	–

Diff Legend

–	Removed lines
+	Added lines
<	Changed lines
>	Changed lines