ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/main/java/util/concurrent/PriorityBlockingQueue.java
(Generate patch)

Comparing jsr166/src/main/java/util/concurrent/PriorityBlockingQueue.java (file contents):
Revision 1.41 by dl, Sun May 8 21:49:27 2005 UTC vs.
Revision 1.42 by jsr166, Tue May 17 17:56:25 2005 UTC

# Line 15 | Line 15 | import java.util.*;
15   * blocking retrieval operations.  While this queue is logically
16   * unbounded, attempted additions may fail due to resource exhaustion
17   * (causing <tt>OutOfMemoryError</tt>). This class does not permit
18 < * <tt>null</tt> elements.  A priority queue relying on natural
19 < * ordering also does not permit insertion of non-comparable objects
20 < * (doing so results in <tt>ClassCastException</tt>).
18 > * <tt>null</tt> elements.  A priority queue relying on {@linkplain
19 > * Comparable natural ordering} also does not permit insertion of
20 > * non-comparable objects (doing so results in
21 > * <tt>ClassCastException</tt>).
22   *
23   * <p>This class and its iterator implement all of the
24   * <em>optional</em> methods of the {@link Collection} and {@link
# Line 50 | Line 51 | import java.util.*;
51   *   public E getEntry() { return entry; }
52   *   public int compareTo(FIFOEntry&lt;E&gt; other) {
53   *     int res = entry.compareTo(other.entry);
54 < *     if (res == 0 && other.entry != this.entry)
54 > *     if (res == 0 &amp;&amp; other.entry != this.entry)
55   *       res = (seqNum &lt; other.seqNum ? -1 : 1);
56   *     return res;
57   *   }
58 < * }
58 < * </pre>
58 > * }</pre>
59   *
60   * <p>This class is a member of the
61   * <a href="{@docRoot}/../guide/collections/index.html">
# Line 74 | Line 74 | public class PriorityBlockingQueue<E> ex
74      private final Condition notEmpty = lock.newCondition();
75  
76      /**
77 <     * Creates a <tt>PriorityBlockingQueue</tt> with the default initial
78 <     * capacity
79 <     * (11) that orders its elements according to their natural
80 <     * ordering (using <tt>Comparable</tt>).
77 >     * Creates a <tt>PriorityBlockingQueue</tt> with the default
78 >     * initial capacity (11) that orders its elements according to
79 >     * their {@linkplain Comparable natural ordering}.
80       */
81      public PriorityBlockingQueue() {
82          q = new PriorityQueue<E>();
83      }
84  
85      /**
86 <     * Creates a <tt>PriorityBlockingQueue</tt> with the specified initial
87 <     * capacity that orders its elements according to their {@linkplain
88 <     * Comparable natural ordering}.
86 >     * Creates a <tt>PriorityBlockingQueue</tt> with the specified
87 >     * initial capacity that orders its elements according to their
88 >     * {@linkplain Comparable natural ordering}.
89       *
90 <     * @param initialCapacity the initial capacity for this priority queue.
90 >     * @param initialCapacity the initial capacity for this priority queue
91       * @throws IllegalArgumentException if <tt>initialCapacity</tt> is less
92       * than 1
93       */
# Line 101 | Line 100 | public class PriorityBlockingQueue<E> ex
100       * capacity that orders its elements according to the specified
101       * comparator.
102       *
103 <     * @param initialCapacity the initial capacity for this priority queue.
103 >     * @param initialCapacity the initial capacity for this priority queue
104       * @param comparator the comparator used to order this priority queue.
105       * If <tt>null</tt> then the order depends on the elements' natural
106       * ordering.
# Line 129 | Line 128 | public class PriorityBlockingQueue<E> ex
128       * @throws ClassCastException if elements of the specified collection
129       *         cannot be compared to one another according to the priority
130       *         queue's ordering.
131 <     * @throws NullPointerException if <tt>c</tt> or any element within it
132 <     * is <tt>null</tt>
131 >     * @throws NullPointerException if the specified collection or any
132 >     *         of its elements are null
133       */
134      public PriorityBlockingQueue(Collection<? extends E> c) {
135          q = new PriorityQueue<E>(c);
136      }
137  
139 –
140 –    // these first few override just to update doc comments
141 –
138      /**
139 <     * Adds the specified element to this queue.
144 <     * @param e the element to add
145 <     * @return <tt>true</tt> (as per the general contract of
146 <     * <tt>Collection.add</tt>).
139 >     * Inserts the specified element into this priority queue.
140       *
141 <     * @throws NullPointerException if the specified element is <tt>null</tt>.
141 >     * @param e the element to add
142 >     * @return <tt>true</tt> (as per the spec for {@link Collection#add})
143       * @throws ClassCastException if the specified element cannot be compared
144 <     * with elements currently in the priority queue according
145 <     * to the priority queue's ordering.
144 >     *         with elements currently in the priority queue according to the
145 >     *         priority queue's ordering
146 >     * @throws NullPointerException if the specified element is null
147       */
148      public boolean add(E e) {
149 <        return super.add(e);
155 <    }
156 <
157 <    /**
158 <     * Returns the comparator used to order the elements in this queue,
159 <     * or <tt>null</tt> if this queue uses the {@linkplain Comparable
160 <     * natural ordering} of its elements.
161 <     *
162 <     * @return the comparator used to order the elements in this queue,
163 <     *         or <tt>null</tt> if this queue uses the natural
164 <     *         ordering of its elements.
165 <     */
166 <    public Comparator<? super E> comparator() {
167 <        return q.comparator();
149 >        return offer(e);
150      }
151  
152      /**
# Line 173 | Line 155 | public class PriorityBlockingQueue<E> ex
155       * @param e the element to add
156       * @return <tt>true</tt>
157       * @throws ClassCastException if the specified element cannot be compared
158 <     * with elements currently in the priority queue according
159 <     * to the priority queue's ordering.
160 <     * @throws NullPointerException if the specified element is <tt>null</tt>.
158 >     *         with elements currently in the priority queue according to the
159 >     *         priority queue's ordering
160 >     * @throws NullPointerException if the specified element is null
161       */
162      public boolean offer(E e) {
163          if (e == null) throw new NullPointerException();
# Line 192 | Line 174 | public class PriorityBlockingQueue<E> ex
174      }
175  
176      /**
177 <     * Adds the specified element to this priority queue. As the queue is
177 >     * Inserts the specified element into this priority queue. As the queue is
178       * unbounded this method will never block.
179 +     *
180       * @param e the element to add
181 <     * @throws ClassCastException if the element cannot be compared
182 <     * with elements currently in the priority queue according
183 <     * to the priority queue's ordering.
184 <     * @throws NullPointerException if the specified element is <tt>null</tt>.
181 >     * @throws ClassCastException if the specified element cannot be compared
182 >     *         with elements currently in the priority queue according to the
183 >     *         priority queue's ordering
184 >     * @throws NullPointerException if the specified element is null
185       */
186      public void put(E e) {
187          offer(e); // never need to block
# Line 207 | Line 190 | public class PriorityBlockingQueue<E> ex
190      /**
191       * Inserts the specified element into this priority queue. As the queue is
192       * unbounded this method will never block.
193 +     *
194       * @param e the element to add
195       * @param timeout This parameter is ignored as the method never blocks
196       * @param unit This parameter is ignored as the method never blocks
197       * @return <tt>true</tt>
198 <     * @throws ClassCastException if the element cannot be compared
199 <     * with elements currently in the priority queue according
200 <     * to the priority queue's ordering.
201 <     * @throws NullPointerException if the specified element is <tt>null</tt>.
198 >     * @throws ClassCastException if the specified element cannot be compared
199 >     *         with elements currently in the priority queue according to the
200 >     *         priority queue's ordering
201 >     * @throws NullPointerException if the specified element is null
202       */
203      public boolean offer(E e, long timeout, TimeUnit unit) {
204          return offer(e); // never need to block
205      }
206  
207 +    public E poll() {
208 +        final ReentrantLock lock = this.lock;
209 +        lock.lock();
210 +        try {
211 +            return q.poll();
212 +        } finally {
213 +            lock.unlock();
214 +        }
215 +    }
216 +
217      public E take() throws InterruptedException {
218          final ReentrantLock lock = this.lock;
219          lock.lockInterruptibly();
# Line 239 | Line 233 | public class PriorityBlockingQueue<E> ex
233          }
234      }
235  
242 –
243 –    public E poll() {
244 –        final ReentrantLock lock = this.lock;
245 –        lock.lock();
246 –        try {
247 –            return q.poll();
248 –        } finally {
249 –            lock.unlock();
250 –        }
251 –    }
252 –
236      public E poll(long timeout, TimeUnit unit) throws InterruptedException {
237          long nanos = unit.toNanos(timeout);
238          final ReentrantLock lock = this.lock;
# Line 283 | Line 266 | public class PriorityBlockingQueue<E> ex
266          }
267      }
268  
269 +    /**
270 +     * Returns the comparator used to order the elements in this queue,
271 +     * or <tt>null</tt> if this queue uses the {@linkplain Comparable
272 +     * natural ordering} of its elements.
273 +     *
274 +     * @return the comparator used to order the elements in this queue,
275 +     *         or <tt>null</tt> if this queue uses the natural
276 +     *         ordering of its elements.
277 +     */
278 +    public Comparator<? super E> comparator() {
279 +        return q.comparator();
280 +    }
281 +
282      public int size() {
283          final ReentrantLock lock = this.lock;
284          lock.lock();
# Line 303 | Line 299 | public class PriorityBlockingQueue<E> ex
299      }
300  
301      /**
302 <     * Removes a single instance of the specified element from this
303 <     * queue, if it is present.
302 >     * Removes a single instance of the specified element from this queue,
303 >     * if it is present.  More formally, removes an element <tt>e</tt> such
304 >     * that <tt>o.equals(e)</tt>, if this queue contains one or more such
305 >     * elements.
306 >     * Returns <tt>true</tt> if this queue contained the specified element
307 >     * (or equivalently, if this queue changed as a result of the call).
308 >     *
309 >     * @param o element to be removed from this queue, if present
310 >     * @return <tt>true</tt> if this queue changed as a result of the call
311       */
312      public boolean remove(Object o) {
313          final ReentrantLock lock = this.lock;
# Line 316 | Line 319 | public class PriorityBlockingQueue<E> ex
319          }
320      }
321  
322 +    /**
323 +     * Returns <tt>true</tt> if this queue contains the specified element.
324 +     * More formally, returns <tt>true</tt> if and only if this queue contains
325 +     * at least one element <tt>e</tt> such that <tt>o.equals(e)</tt>.
326 +     *
327 +     * @param o object to be checked for containment in this queue
328 +     * @return <tt>true</tt> if this queue contains the specified element
329 +     */
330      public boolean contains(Object o) {
331          final ReentrantLock lock = this.lock;
332          lock.lock();
# Line 326 | Line 337 | public class PriorityBlockingQueue<E> ex
337          }
338      }
339  
340 +    /**
341 +     * Returns an array containing all of the elements in this queue.
342 +     * The returned array elements are in no particular order.
343 +     *
344 +     * <p>The returned array will be "safe" in that no references to it are
345 +     * maintained by this queue.  (In other words, this method must allocate
346 +     * a new array).  The caller is thus free to modify the returned array.
347 +     *
348 +     * <p>This method acts as bridge between array-based and collection-based
349 +     * APIs.
350 +     *
351 +     * @return an array containing all of the elements in this queue
352 +     */
353      public Object[] toArray() {
354          final ReentrantLock lock = this.lock;
355          lock.lock();
# Line 347 | Line 371 | public class PriorityBlockingQueue<E> ex
371          }
372      }
373  
374 +    /**
375 +     * @throws UnsupportedOperationException {@inheritDoc}
376 +     * @throws ClassCastException            {@inheritDoc}
377 +     * @throws NullPointerException          {@inheritDoc}
378 +     * @throws IllegalArgumentException      {@inheritDoc}
379 +     */
380      public int drainTo(Collection<? super E> c) {
381          if (c == null)
382              throw new NullPointerException();
# Line 367 | Line 397 | public class PriorityBlockingQueue<E> ex
397          }
398      }
399  
400 +    /**
401 +     * @throws UnsupportedOperationException {@inheritDoc}
402 +     * @throws ClassCastException            {@inheritDoc}
403 +     * @throws NullPointerException          {@inheritDoc}
404 +     * @throws IllegalArgumentException      {@inheritDoc}
405 +     */
406      public int drainTo(Collection<? super E> c, int maxElements) {
407          if (c == null)
408              throw new NullPointerException();
# Line 403 | Line 439 | public class PriorityBlockingQueue<E> ex
439          }
440      }
441  
442 +    /**
443 +     * Returns an array containing all of the elements in this queue; the
444 +     * runtime type of the returned array is that of the specified array.
445 +     * The returned array elements are in no particular order.
446 +     * If the queue fits in the specified array, it is returned therein.
447 +     * Otherwise, a new array is allocated with the runtime type of the
448 +     * specified array and the size of this queue.
449 +     *
450 +     * <p>If this queue fits in the specified array with room to spare
451 +     * (i.e., the array has more elements than this queue), the element in
452 +     * the array immediately following the end of the queue is set to
453 +     * <tt>null</tt>.
454 +     *
455 +     * <p>Like the {@link #toArray()} method, this method acts as bridge between
456 +     * array-based and collection-based APIs.  Further, this method allows
457 +     * precise control over the runtime type of the output array, and may,
458 +     * under certain circumstances, be used to save allocation costs.
459 +     *
460 +     * <p>Suppose <tt>x</tt> is a queue known to contain only strings.
461 +     * The following code can be used to dump the queue into a newly
462 +     * allocated array of <tt>String</tt>:
463 +     *
464 +     * <pre>
465 +     *     String[] y = x.toArray(new String[0]);</pre>
466 +     *
467 +     * Note that <tt>toArray(new Object[0])</tt> is identical in function to
468 +     * <tt>toArray()</tt>.
469 +     *
470 +     * @param a the array into which the elements of the queue are to
471 +     *          be stored, if it is big enough; otherwise, a new array of the
472 +     *          same runtime type is allocated for this purpose
473 +     * @return an array containing all of the elements in this queue
474 +     * @throws ArrayStoreException if the runtime type of the specified array
475 +     *         is not a supertype of the runtime type of every element in
476 +     *         this queue
477 +     * @throws NullPointerException if the specified array is null
478 +     */
479      public <T> T[] toArray(T[] a) {
480          final ReentrantLock lock = this.lock;
481          lock.lock();
# Line 420 | Line 493 | public class PriorityBlockingQueue<E> ex
493       * that will throw {@link ConcurrentModificationException} upon
494       * detected interference.
495       *
496 <     * @return an iterator over the elements in this queue.
496 >     * @return an iterator over the elements in this queue
497       */
498      public Iterator<E> iterator() {
499          final ReentrantLock lock = this.lock;

Diff Legend

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