ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/main/java/util/concurrent/DelayQueue.java
Revision: 1.37
Committed: Mon Jul 18 00:25:25 2005 UTC (18 years, 10 months ago) by jsr166
Branch: MAIN
Changes since 1.36: +4 -4 lines
Log Message:
doc fixes

File Contents

# User Rev Content
1 dl 1.2 /*
2     * Written by Doug Lea with assistance from members of JCP JSR-166
3 dl 1.23 * Expert Group and released to the public domain, as explained at
4     * http://creativecommons.org/licenses/publicdomain
5 dl 1.2 */
6    
7    
8 tim 1.1 package java.util.concurrent;
9 jsr166 1.37 import java.util.concurrent.*; // for javadoc (till 6280605 is fixed)
10 dl 1.5 import java.util.concurrent.locks.*;
11 tim 1.1 import java.util.*;
12    
13     /**
14 dl 1.27 * An unbounded {@linkplain BlockingQueue blocking queue} of
15     * <tt>Delayed</tt> elements, in which an element can only be taken
16     * when its delay has expired. The <em>head</em> of the queue is that
17     * <tt>Delayed</tt> element whose delay expired furthest in the
18 jsr166 1.32 * past. If no delay has expired there is no head and <tt>poll</tt>
19 dl 1.27 * will return <tt>null</tt>. Expiration occurs when an element's
20     * <tt>getDelay(TimeUnit.NANOSECONDS)</tt> method returns a value less
21 dl 1.36 * than or equal to zero. Even though unexpired elements cannot be
22     * removed using <tt>take</tt> or <tt>poll</tt>, they are otherwise
23     * treated as normal elements. For example, the <tt>size</tt> method
24     * returns the count of both expired and unexpired elements.
25     * This queue does not permit <tt>null</tt>
26 dl 1.27 * elements.
27 dl 1.25 *
28 dl 1.26 * <p>This class and its iterator implement all of the
29     * <em>optional</em> methods of the {@link Collection} and {@link
30 jsr166 1.29 * Iterator} interfaces.
31 dl 1.26 *
32 dl 1.25 * <p>This class is a member of the
33     * <a href="{@docRoot}/../guide/collections/index.html">
34     * Java Collections Framework</a>.
35     *
36 dl 1.4 * @since 1.5
37     * @author Doug Lea
38 dl 1.20 * @param <E> the type of elements held in this collection
39 dl 1.19 */
40 tim 1.1
41 dl 1.3 public class DelayQueue<E extends Delayed> extends AbstractQueue<E>
42     implements BlockingQueue<E> {
43 tim 1.6
44 dl 1.2 private transient final ReentrantLock lock = new ReentrantLock();
45 dl 1.22 private transient final Condition available = lock.newCondition();
46 dl 1.3 private final PriorityQueue<E> q = new PriorityQueue<E>();
47 tim 1.1
48 dl 1.4 /**
49 dholmes 1.7 * Creates a new <tt>DelayQueue</tt> that is initially empty.
50 dl 1.4 */
51 tim 1.1 public DelayQueue() {}
52    
53 tim 1.6 /**
54 tim 1.9 * Creates a <tt>DelayQueue</tt> initially containing the elements of the
55 dholmes 1.7 * given collection of {@link Delayed} instances.
56     *
57 jsr166 1.32 * @param c the collection of elements to initially contain
58     * @throws NullPointerException if the specified collection or any
59     * of its elements are null
60 tim 1.6 */
61     public DelayQueue(Collection<? extends E> c) {
62     this.addAll(c);
63     }
64    
65 dholmes 1.7 /**
66 dl 1.16 * Inserts the specified element into this delay queue.
67 dholmes 1.7 *
68 jsr166 1.30 * @param e the element to add
69 jsr166 1.32 * @return <tt>true</tt> (as per the spec for {@link Collection#add})
70     * @throws NullPointerException if the specified element is null
71     */
72     public boolean add(E e) {
73     return offer(e);
74     }
75    
76     /**
77     * Inserts the specified element into this delay queue.
78     *
79     * @param e the element to add
80 dholmes 1.7 * @return <tt>true</tt>
81 jsr166 1.32 * @throws NullPointerException if the specified element is null
82 dholmes 1.7 */
83 jsr166 1.30 public boolean offer(E e) {
84 dl 1.21 final ReentrantLock lock = this.lock;
85 dl 1.2 lock.lock();
86     try {
87 dl 1.3 E first = q.peek();
88 jsr166 1.30 q.offer(e);
89     if (first == null || e.compareTo(first) < 0)
90 dl 1.4 available.signalAll();
91 dl 1.2 return true;
92 tim 1.13 } finally {
93 dl 1.2 lock.unlock();
94     }
95     }
96    
97 dholmes 1.7 /**
98 jsr166 1.32 * Inserts the specified element into this delay queue. As the queue is
99 dholmes 1.7 * unbounded this method will never block.
100 jsr166 1.32 *
101 jsr166 1.30 * @param e the element to add
102 jsr166 1.32 * @throws NullPointerException {@inheritDoc}
103 dholmes 1.7 */
104 jsr166 1.30 public void put(E e) {
105     offer(e);
106 dl 1.2 }
107    
108 dholmes 1.7 /**
109 dl 1.16 * Inserts the specified element into this delay queue. As the queue is
110 dholmes 1.7 * unbounded this method will never block.
111 jsr166 1.32 *
112 jsr166 1.30 * @param e the element to add
113 dl 1.14 * @param timeout This parameter is ignored as the method never blocks
114 dholmes 1.7 * @param unit This parameter is ignored as the method never blocks
115     * @return <tt>true</tt>
116 jsr166 1.32 * @throws NullPointerException {@inheritDoc}
117 dholmes 1.7 */
118 jsr166 1.30 public boolean offer(E e, long timeout, TimeUnit unit) {
119     return offer(e);
120 dl 1.2 }
121    
122 dholmes 1.7 /**
123 jsr166 1.32 * Retrieves and removes the head of this queue, or returns <tt>null</tt>
124     * if this queue has no elements with an expired delay.
125 dholmes 1.7 *
126 jsr166 1.32 * @return the head of this queue, or <tt>null</tt> if this
127     * queue has no elements with an expired delay
128 dholmes 1.7 */
129 jsr166 1.32 public E poll() {
130     final ReentrantLock lock = this.lock;
131     lock.lock();
132     try {
133     E first = q.peek();
134     if (first == null || first.getDelay(TimeUnit.NANOSECONDS) > 0)
135     return null;
136     else {
137     E x = q.poll();
138     assert x != null;
139     if (q.size() != 0)
140     available.signalAll();
141     return x;
142     }
143     } finally {
144     lock.unlock();
145     }
146 dl 1.2 }
147    
148 dl 1.27 /**
149 jsr166 1.32 * Retrieves and removes the head of this queue, waiting if necessary
150     * until an element with an expired delay is available on this queue.
151     *
152 dl 1.27 * @return the head of this queue
153 jsr166 1.32 * @throws InterruptedException {@inheritDoc}
154 dl 1.27 */
155 dl 1.3 public E take() throws InterruptedException {
156 dl 1.21 final ReentrantLock lock = this.lock;
157 dl 1.2 lock.lockInterruptibly();
158     try {
159     for (;;) {
160 dl 1.3 E first = q.peek();
161 dl 1.12 if (first == null) {
162 dl 1.4 available.await();
163 tim 1.13 } else {
164 dl 1.2 long delay = first.getDelay(TimeUnit.NANOSECONDS);
165 dl 1.12 if (delay > 0) {
166     long tl = available.awaitNanos(delay);
167 tim 1.13 } else {
168 dl 1.3 E x = q.poll();
169 dl 1.2 assert x != null;
170     if (q.size() != 0)
171 dl 1.4 available.signalAll(); // wake up other takers
172 dl 1.2 return x;
173 tim 1.6
174 dl 1.2 }
175     }
176     }
177 tim 1.13 } finally {
178 dl 1.2 lock.unlock();
179     }
180     }
181    
182 dl 1.27 /**
183 jsr166 1.32 * Retrieves and removes the head of this queue, waiting if necessary
184     * until an element with an expired delay is available on this queue,
185     * or the specified wait time expires.
186     *
187 dl 1.27 * @return the head of this queue, or <tt>null</tt> if the
188 jsr166 1.32 * specified waiting time elapses before an element with
189     * an expired delay becomes available
190     * @throws InterruptedException {@inheritDoc}
191 dl 1.27 */
192     public E poll(long timeout, TimeUnit unit) throws InterruptedException {
193 dl 1.21 final ReentrantLock lock = this.lock;
194 dl 1.2 lock.lockInterruptibly();
195 dl 1.27 long nanos = unit.toNanos(timeout);
196 dl 1.2 try {
197     for (;;) {
198 dl 1.3 E first = q.peek();
199 dl 1.2 if (first == null) {
200     if (nanos <= 0)
201     return null;
202     else
203 dl 1.4 nanos = available.awaitNanos(nanos);
204 tim 1.13 } else {
205 dl 1.2 long delay = first.getDelay(TimeUnit.NANOSECONDS);
206     if (delay > 0) {
207     if (delay > nanos)
208     delay = nanos;
209 dl 1.4 long timeLeft = available.awaitNanos(delay);
210 dl 1.2 nanos -= delay - timeLeft;
211 tim 1.13 } else {
212 dl 1.3 E x = q.poll();
213 dl 1.2 assert x != null;
214     if (q.size() != 0)
215 tim 1.6 available.signalAll();
216 dl 1.2 return x;
217     }
218     }
219     }
220 tim 1.13 } finally {
221 dl 1.2 lock.unlock();
222     }
223     }
224    
225 dl 1.27 /**
226 dl 1.36 * Retrieves, but does not remove, the head of this queue, or
227     * returns <tt>null</tt> if this queue is empty. Unlike
228     * <tt>poll</tt>, if no expired elements are available in the queue,
229     * this method returns the element that will expire next,
230     * if one exists.
231 dl 1.27 *
232 jsr166 1.32 * @return the head of this queue, or <tt>null</tt> if this
233 dl 1.35 * queue is empty.
234 dl 1.27 */
235 dl 1.3 public E peek() {
236 dl 1.21 final ReentrantLock lock = this.lock;
237 dl 1.2 lock.lock();
238     try {
239     return q.peek();
240 tim 1.13 } finally {
241 dl 1.2 lock.unlock();
242     }
243 tim 1.1 }
244    
245 dl 1.2 public int size() {
246 dl 1.21 final ReentrantLock lock = this.lock;
247 dl 1.2 lock.lock();
248     try {
249     return q.size();
250 tim 1.13 } finally {
251 dl 1.2 lock.unlock();
252     }
253     }
254    
255 jsr166 1.32 /**
256     * @throws UnsupportedOperationException {@inheritDoc}
257     * @throws ClassCastException {@inheritDoc}
258     * @throws NullPointerException {@inheritDoc}
259     * @throws IllegalArgumentException {@inheritDoc}
260     */
261 dl 1.17 public int drainTo(Collection<? super E> c) {
262     if (c == null)
263     throw new NullPointerException();
264     if (c == this)
265     throw new IllegalArgumentException();
266 dl 1.21 final ReentrantLock lock = this.lock;
267 dl 1.17 lock.lock();
268     try {
269     int n = 0;
270     for (;;) {
271     E first = q.peek();
272     if (first == null || first.getDelay(TimeUnit.NANOSECONDS) > 0)
273     break;
274     c.add(q.poll());
275     ++n;
276     }
277     if (n > 0)
278     available.signalAll();
279     return n;
280     } finally {
281     lock.unlock();
282     }
283     }
284    
285 jsr166 1.32 /**
286     * @throws UnsupportedOperationException {@inheritDoc}
287     * @throws ClassCastException {@inheritDoc}
288     * @throws NullPointerException {@inheritDoc}
289     * @throws IllegalArgumentException {@inheritDoc}
290     */
291 dl 1.17 public int drainTo(Collection<? super E> c, int maxElements) {
292     if (c == null)
293     throw new NullPointerException();
294     if (c == this)
295     throw new IllegalArgumentException();
296     if (maxElements <= 0)
297     return 0;
298 dl 1.21 final ReentrantLock lock = this.lock;
299 dl 1.17 lock.lock();
300     try {
301     int n = 0;
302     while (n < maxElements) {
303     E first = q.peek();
304     if (first == null || first.getDelay(TimeUnit.NANOSECONDS) > 0)
305     break;
306     c.add(q.poll());
307     ++n;
308     }
309     if (n > 0)
310     available.signalAll();
311     return n;
312     } finally {
313     lock.unlock();
314     }
315     }
316    
317 dholmes 1.7 /**
318     * Atomically removes all of the elements from this delay queue.
319     * The queue will be empty after this call returns.
320 jsr166 1.32 * Elements with an unexpired delay are not waited for; they are
321     * simply discarded from the queue.
322 dholmes 1.7 */
323 dl 1.2 public void clear() {
324 dl 1.21 final ReentrantLock lock = this.lock;
325 dl 1.2 lock.lock();
326     try {
327     q.clear();
328 tim 1.13 } finally {
329 dl 1.2 lock.unlock();
330     }
331     }
332 tim 1.1
333 dholmes 1.7 /**
334     * Always returns <tt>Integer.MAX_VALUE</tt> because
335     * a <tt>DelayQueue</tt> is not capacity constrained.
336 jsr166 1.32 *
337 dholmes 1.7 * @return <tt>Integer.MAX_VALUE</tt>
338     */
339 dl 1.2 public int remainingCapacity() {
340     return Integer.MAX_VALUE;
341 tim 1.1 }
342 dl 1.2
343 jsr166 1.32 /**
344     * Returns an array containing all of the elements in this queue.
345     * The returned array elements are in no particular order.
346     *
347     * <p>The returned array will be "safe" in that no references to it are
348     * maintained by this queue. (In other words, this method must allocate
349     * a new array). The caller is thus free to modify the returned array.
350 jsr166 1.33 *
351 jsr166 1.32 * <p>This method acts as bridge between array-based and collection-based
352     * APIs.
353     *
354     * @return an array containing all of the elements in this queue
355     */
356 dl 1.2 public Object[] toArray() {
357 dl 1.21 final ReentrantLock lock = this.lock;
358 dl 1.2 lock.lock();
359     try {
360     return q.toArray();
361 tim 1.13 } finally {
362 dl 1.2 lock.unlock();
363     }
364 tim 1.1 }
365 dl 1.2
366 jsr166 1.32 /**
367     * Returns an array containing all of the elements in this queue; the
368     * runtime type of the returned array is that of the specified array.
369     * The returned array elements are in no particular order.
370     * If the queue fits in the specified array, it is returned therein.
371     * Otherwise, a new array is allocated with the runtime type of the
372     * specified array and the size of this queue.
373     *
374     * <p>If this queue fits in the specified array with room to spare
375     * (i.e., the array has more elements than this queue), the element in
376     * the array immediately following the end of the queue is set to
377     * <tt>null</tt>.
378     *
379     * <p>Like the {@link #toArray()} method, this method acts as bridge between
380     * array-based and collection-based APIs. Further, this method allows
381     * precise control over the runtime type of the output array, and may,
382     * under certain circumstances, be used to save allocation costs.
383     *
384 jsr166 1.37 * <p>The following code can be used to dump a delay queue into a newly
385     * allocated array of <tt>Delayed</tt>:
386 jsr166 1.32 *
387     * <pre>
388 jsr166 1.37 * Delayed[] a = q.toArray(new Delayed[0]);</pre>
389 jsr166 1.32 *
390     * Note that <tt>toArray(new Object[0])</tt> is identical in function to
391     * <tt>toArray()</tt>.
392     *
393     * @param a the array into which the elements of the queue are to
394     * be stored, if it is big enough; otherwise, a new array of the
395     * same runtime type is allocated for this purpose
396     * @return an array containing all of the elements in this queue
397     * @throws ArrayStoreException if the runtime type of the specified array
398     * is not a supertype of the runtime type of every element in
399     * this queue
400     * @throws NullPointerException if the specified array is null
401     */
402     public <T> T[] toArray(T[] a) {
403 dl 1.21 final ReentrantLock lock = this.lock;
404 dl 1.2 lock.lock();
405     try {
406 jsr166 1.32 return q.toArray(a);
407 tim 1.13 } finally {
408 dl 1.2 lock.unlock();
409     }
410 tim 1.1 }
411    
412 dl 1.26 /**
413     * Removes a single instance of the specified element from this
414 dl 1.36 * queue, if it is present, whether or not it has expired.
415 dl 1.26 */
416 dholmes 1.7 public boolean remove(Object o) {
417 dl 1.21 final ReentrantLock lock = this.lock;
418 dl 1.2 lock.lock();
419     try {
420 dholmes 1.7 return q.remove(o);
421 tim 1.13 } finally {
422 dl 1.2 lock.unlock();
423     }
424     }
425    
426 dholmes 1.7 /**
427 dl 1.36 * Returns an iterator over all the elements (both expired and
428     * unexpired) in this queue. The iterator does not
429     * return the elements in any particular order. The returned
430     * iterator is a thread-safe "fast-fail" iterator that will throw
431     * {@link ConcurrentModificationException} upon detected
432     * interference.
433 dholmes 1.7 *
434 jsr166 1.32 * @return an iterator over the elements in this queue
435 dholmes 1.7 */
436 dl 1.3 public Iterator<E> iterator() {
437 dl 1.21 final ReentrantLock lock = this.lock;
438 dl 1.2 lock.lock();
439     try {
440 dl 1.34 return new Itr<E>(q.iterator());
441 tim 1.13 } finally {
442 dl 1.2 lock.unlock();
443     }
444     }
445    
446 dl 1.3 private class Itr<E> implements Iterator<E> {
447     private final Iterator<E> iter;
448 tim 1.6 Itr(Iterator<E> i) {
449     iter = i;
450 dl 1.2 }
451    
452 tim 1.6 public boolean hasNext() {
453 dl 1.2 return iter.hasNext();
454 tim 1.6 }
455    
456     public E next() {
457 dl 1.21 final ReentrantLock lock = DelayQueue.this.lock;
458 dl 1.2 lock.lock();
459     try {
460     return iter.next();
461 tim 1.13 } finally {
462 dl 1.2 lock.unlock();
463     }
464 tim 1.6 }
465    
466     public void remove() {
467 dl 1.21 final ReentrantLock lock = DelayQueue.this.lock;
468 dl 1.2 lock.lock();
469     try {
470     iter.remove();
471 tim 1.13 } finally {
472 dl 1.2 lock.unlock();
473     }
474 tim 1.6 }
475 tim 1.1 }
476    
477     }