2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 * This code is free software; you can redistribute it and/or modify it
5 * under the terms of the GNU General Public License version 2 only, as
6 * published by the Free Software Foundation. Oracle designates this
7 * particular file as subject to the "Classpath" exception as provided
8 * by Oracle in the LICENSE file that accompanied this code.
10 * This code is distributed in the hope that it will be useful, but WITHOUT
11 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
13 * version 2 for more details (a copy is included in the LICENSE file that
14 * accompanied this code).
16 * You should have received a copy of the GNU General Public License version
17 * 2 along with this work; if not, write to the Free Software Foundation,
18 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
21 * or visit www.oracle.com if you need additional information or have any
26 * This file is available under and governed by the GNU General Public
27 * License version 2 only, as published by the Free Software Foundation.
28 * However, the following notice accompanied the original version of this
31 * Written by Doug Lea with assistance from members of JCP JSR-166
32 * Expert Group and released to the public domain, as explained at
33 * http://creativecommons.org/publicdomain/zero/1.0/
36 package java.util.concurrent;
40 * A {@link Deque} that additionally supports blocking operations that wait
41 * for the deque to become non-empty when retrieving an element, and wait for
42 * space to become available in the deque when storing an element.
44 * <p><tt>BlockingDeque</tt> methods come in four forms, with different ways
45 * of handling operations that cannot be satisfied immediately, but may be
46 * satisfied at some point in the future:
47 * one throws an exception, the second returns a special value (either
48 * <tt>null</tt> or <tt>false</tt>, depending on the operation), the third
49 * blocks the current thread indefinitely until the operation can succeed,
50 * and the fourth blocks for only a given maximum time limit before giving
51 * up. These methods are summarized in the following table:
54 * <table BORDER CELLPADDING=3 CELLSPACING=1>
56 * <td ALIGN=CENTER COLSPAN = 5> <b>First Element (Head)</b></td>
60 * <td ALIGN=CENTER><em>Throws exception</em></td>
61 * <td ALIGN=CENTER><em>Special value</em></td>
62 * <td ALIGN=CENTER><em>Blocks</em></td>
63 * <td ALIGN=CENTER><em>Times out</em></td>
66 * <td><b>Insert</b></td>
67 * <td>{@link #addFirst addFirst(e)}</td>
68 * <td>{@link #offerFirst(Object) offerFirst(e)}</td>
69 * <td>{@link #putFirst putFirst(e)}</td>
70 * <td>{@link #offerFirst(Object, long, TimeUnit) offerFirst(e, time, unit)}</td>
73 * <td><b>Remove</b></td>
74 * <td>{@link #removeFirst removeFirst()}</td>
75 * <td>{@link #pollFirst pollFirst()}</td>
76 * <td>{@link #takeFirst takeFirst()}</td>
77 * <td>{@link #pollFirst(long, TimeUnit) pollFirst(time, unit)}</td>
80 * <td><b>Examine</b></td>
81 * <td>{@link #getFirst getFirst()}</td>
82 * <td>{@link #peekFirst peekFirst()}</td>
83 * <td><em>not applicable</em></td>
84 * <td><em>not applicable</em></td>
87 * <td ALIGN=CENTER COLSPAN = 5> <b>Last Element (Tail)</b></td>
91 * <td ALIGN=CENTER><em>Throws exception</em></td>
92 * <td ALIGN=CENTER><em>Special value</em></td>
93 * <td ALIGN=CENTER><em>Blocks</em></td>
94 * <td ALIGN=CENTER><em>Times out</em></td>
97 * <td><b>Insert</b></td>
98 * <td>{@link #addLast addLast(e)}</td>
99 * <td>{@link #offerLast(Object) offerLast(e)}</td>
100 * <td>{@link #putLast putLast(e)}</td>
101 * <td>{@link #offerLast(Object, long, TimeUnit) offerLast(e, time, unit)}</td>
104 * <td><b>Remove</b></td>
105 * <td>{@link #removeLast() removeLast()}</td>
106 * <td>{@link #pollLast() pollLast()}</td>
107 * <td>{@link #takeLast takeLast()}</td>
108 * <td>{@link #pollLast(long, TimeUnit) pollLast(time, unit)}</td>
111 * <td><b>Examine</b></td>
112 * <td>{@link #getLast getLast()}</td>
113 * <td>{@link #peekLast peekLast()}</td>
114 * <td><em>not applicable</em></td>
115 * <td><em>not applicable</em></td>
119 * <p>Like any {@link BlockingQueue}, a <tt>BlockingDeque</tt> is thread safe,
120 * does not permit null elements, and may (or may not) be
121 * capacity-constrained.
123 * <p>A <tt>BlockingDeque</tt> implementation may be used directly as a FIFO
124 * <tt>BlockingQueue</tt>. The methods inherited from the
125 * <tt>BlockingQueue</tt> interface are precisely equivalent to
126 * <tt>BlockingDeque</tt> methods as indicated in the following table:
129 * <table BORDER CELLPADDING=3 CELLSPACING=1>
131 * <td ALIGN=CENTER> <b><tt>BlockingQueue</tt> Method</b></td>
132 * <td ALIGN=CENTER> <b>Equivalent <tt>BlockingDeque</tt> Method</b></td>
135 * <td ALIGN=CENTER COLSPAN = 2> <b>Insert</b></td>
138 * <td>{@link #add(Object) add(e)}</td>
139 * <td>{@link #addLast(Object) addLast(e)}</td>
142 * <td>{@link #offer(Object) offer(e)}</td>
143 * <td>{@link #offerLast(Object) offerLast(e)}</td>
146 * <td>{@link #put(Object) put(e)}</td>
147 * <td>{@link #putLast(Object) putLast(e)}</td>
150 * <td>{@link #offer(Object, long, TimeUnit) offer(e, time, unit)}</td>
151 * <td>{@link #offerLast(Object, long, TimeUnit) offerLast(e, time, unit)}</td>
154 * <td ALIGN=CENTER COLSPAN = 2> <b>Remove</b></td>
157 * <td>{@link #remove() remove()}</td>
158 * <td>{@link #removeFirst() removeFirst()}</td>
161 * <td>{@link #poll() poll()}</td>
162 * <td>{@link #pollFirst() pollFirst()}</td>
165 * <td>{@link #take() take()}</td>
166 * <td>{@link #takeFirst() takeFirst()}</td>
169 * <td>{@link #poll(long, TimeUnit) poll(time, unit)}</td>
170 * <td>{@link #pollFirst(long, TimeUnit) pollFirst(time, unit)}</td>
173 * <td ALIGN=CENTER COLSPAN = 2> <b>Examine</b></td>
176 * <td>{@link #element() element()}</td>
177 * <td>{@link #getFirst() getFirst()}</td>
180 * <td>{@link #peek() peek()}</td>
181 * <td>{@link #peekFirst() peekFirst()}</td>
185 * <p>Memory consistency effects: As with other concurrent
186 * collections, actions in a thread prior to placing an object into a
187 * {@code BlockingDeque}
188 * <a href="package-summary.html#MemoryVisibility"><i>happen-before</i></a>
189 * actions subsequent to the access or removal of that element from
190 * the {@code BlockingDeque} in another thread.
192 * <p>This interface is a member of the
193 * <a href="{@docRoot}/../technotes/guides/collections/index.html">
194 * Java Collections Framework</a>.
198 * @param <E> the type of elements held in this collection
200 public interface BlockingDeque<E> extends BlockingQueue<E>, Deque<E> {
202 * We have "diamond" multiple interface inheritance here, and that
203 * introduces ambiguities. Methods might end up with different
204 * specs depending on the branch chosen by javadoc. Thus a lot of
205 * methods specs here are copied from superinterfaces.
209 * Inserts the specified element at the front of this deque if it is
210 * possible to do so immediately without violating capacity restrictions,
211 * throwing an <tt>IllegalStateException</tt> if no space is currently
212 * available. When using a capacity-restricted deque, it is generally
213 * preferable to use {@link #offerFirst(Object) offerFirst}.
215 * @param e the element to add
216 * @throws IllegalStateException {@inheritDoc}
217 * @throws ClassCastException {@inheritDoc}
218 * @throws NullPointerException if the specified element is null
219 * @throws IllegalArgumentException {@inheritDoc}
224 * Inserts the specified element at the end of this deque if it is
225 * possible to do so immediately without violating capacity restrictions,
226 * throwing an <tt>IllegalStateException</tt> if no space is currently
227 * available. When using a capacity-restricted deque, it is generally
228 * preferable to use {@link #offerLast(Object) offerLast}.
230 * @param e the element to add
231 * @throws IllegalStateException {@inheritDoc}
232 * @throws ClassCastException {@inheritDoc}
233 * @throws NullPointerException if the specified element is null
234 * @throws IllegalArgumentException {@inheritDoc}
239 * Inserts the specified element at the front of this deque if it is
240 * possible to do so immediately without violating capacity restrictions,
241 * returning <tt>true</tt> upon success and <tt>false</tt> if no space is
242 * currently available.
243 * When using a capacity-restricted deque, this method is generally
244 * preferable to the {@link #addFirst(Object) addFirst} method, which can
245 * fail to insert an element only by throwing an exception.
247 * @param e the element to add
248 * @throws ClassCastException {@inheritDoc}
249 * @throws NullPointerException if the specified element is null
250 * @throws IllegalArgumentException {@inheritDoc}
252 boolean offerFirst(E e);
255 * Inserts the specified element at the end of this deque if it is
256 * possible to do so immediately without violating capacity restrictions,
257 * returning <tt>true</tt> upon success and <tt>false</tt> if no space is
258 * currently available.
259 * When using a capacity-restricted deque, this method is generally
260 * preferable to the {@link #addLast(Object) addLast} method, which can
261 * fail to insert an element only by throwing an exception.
263 * @param e the element to add
264 * @throws ClassCastException {@inheritDoc}
265 * @throws NullPointerException if the specified element is null
266 * @throws IllegalArgumentException {@inheritDoc}
268 boolean offerLast(E e);
271 * Inserts the specified element at the front of this deque,
272 * waiting if necessary for space to become available.
274 * @param e the element to add
275 * @throws InterruptedException if interrupted while waiting
276 * @throws ClassCastException if the class of the specified element
277 * prevents it from being added to this deque
278 * @throws NullPointerException if the specified element is null
279 * @throws IllegalArgumentException if some property of the specified
280 * element prevents it from being added to this deque
282 void putFirst(E e) throws InterruptedException;
285 * Inserts the specified element at the end of this deque,
286 * waiting if necessary for space to become available.
288 * @param e the element to add
289 * @throws InterruptedException if interrupted while waiting
290 * @throws ClassCastException if the class of the specified element
291 * prevents it from being added to this deque
292 * @throws NullPointerException if the specified element is null
293 * @throws IllegalArgumentException if some property of the specified
294 * element prevents it from being added to this deque
296 void putLast(E e) throws InterruptedException;
299 * Inserts the specified element at the front of this deque,
300 * waiting up to the specified wait time if necessary for space to
303 * @param e the element to add
304 * @param timeout how long to wait before giving up, in units of
306 * @param unit a <tt>TimeUnit</tt> determining how to interpret the
307 * <tt>timeout</tt> parameter
308 * @return <tt>true</tt> if successful, or <tt>false</tt> if
309 * the specified waiting time elapses before space is available
310 * @throws InterruptedException if interrupted while waiting
311 * @throws ClassCastException if the class of the specified element
312 * prevents it from being added to this deque
313 * @throws NullPointerException if the specified element is null
314 * @throws IllegalArgumentException if some property of the specified
315 * element prevents it from being added to this deque
317 boolean offerFirst(E e, long timeout, TimeUnit unit)
318 throws InterruptedException;
321 * Inserts the specified element at the end of this deque,
322 * waiting up to the specified wait time if necessary for space to
325 * @param e the element to add
326 * @param timeout how long to wait before giving up, in units of
328 * @param unit a <tt>TimeUnit</tt> determining how to interpret the
329 * <tt>timeout</tt> parameter
330 * @return <tt>true</tt> if successful, or <tt>false</tt> if
331 * the specified waiting time elapses before space is available
332 * @throws InterruptedException if interrupted while waiting
333 * @throws ClassCastException if the class of the specified element
334 * prevents it from being added to this deque
335 * @throws NullPointerException if the specified element is null
336 * @throws IllegalArgumentException if some property of the specified
337 * element prevents it from being added to this deque
339 boolean offerLast(E e, long timeout, TimeUnit unit)
340 throws InterruptedException;
343 * Retrieves and removes the first element of this deque, waiting
344 * if necessary until an element becomes available.
346 * @return the head of this deque
347 * @throws InterruptedException if interrupted while waiting
349 E takeFirst() throws InterruptedException;
352 * Retrieves and removes the last element of this deque, waiting
353 * if necessary until an element becomes available.
355 * @return the tail of this deque
356 * @throws InterruptedException if interrupted while waiting
358 E takeLast() throws InterruptedException;
361 * Retrieves and removes the first element of this deque, waiting
362 * up to the specified wait time if necessary for an element to
365 * @param timeout how long to wait before giving up, in units of
367 * @param unit a <tt>TimeUnit</tt> determining how to interpret the
368 * <tt>timeout</tt> parameter
369 * @return the head of this deque, or <tt>null</tt> if the specified
370 * waiting time elapses before an element is available
371 * @throws InterruptedException if interrupted while waiting
373 E pollFirst(long timeout, TimeUnit unit)
374 throws InterruptedException;
377 * Retrieves and removes the last element of this deque, waiting
378 * up to the specified wait time if necessary for an element to
381 * @param timeout how long to wait before giving up, in units of
383 * @param unit a <tt>TimeUnit</tt> determining how to interpret the
384 * <tt>timeout</tt> parameter
385 * @return the tail of this deque, or <tt>null</tt> if the specified
386 * waiting time elapses before an element is available
387 * @throws InterruptedException if interrupted while waiting
389 E pollLast(long timeout, TimeUnit unit)
390 throws InterruptedException;
393 * Removes the first occurrence of the specified element from this deque.
394 * If the deque does not contain the element, it is unchanged.
395 * More formally, removes the first element <tt>e</tt> such that
396 * <tt>o.equals(e)</tt> (if such an element exists).
397 * Returns <tt>true</tt> if this deque contained the specified element
398 * (or equivalently, if this deque changed as a result of the call).
400 * @param o element to be removed from this deque, if present
401 * @return <tt>true</tt> if an element was removed as a result of this call
402 * @throws ClassCastException if the class of the specified element
403 * is incompatible with this deque
404 * (<a href="../Collection.html#optional-restrictions">optional</a>)
405 * @throws NullPointerException if the specified element is null
406 * (<a href="../Collection.html#optional-restrictions">optional</a>)
408 boolean removeFirstOccurrence(Object o);
411 * Removes the last occurrence of the specified element from this deque.
412 * If the deque does not contain the element, it is unchanged.
413 * More formally, removes the last element <tt>e</tt> such that
414 * <tt>o.equals(e)</tt> (if such an element exists).
415 * Returns <tt>true</tt> if this deque contained the specified element
416 * (or equivalently, if this deque changed as a result of the call).
418 * @param o element to be removed from this deque, if present
419 * @return <tt>true</tt> if an element was removed as a result of this call
420 * @throws ClassCastException if the class of the specified element
421 * is incompatible with this deque
422 * (<a href="../Collection.html#optional-restrictions">optional</a>)
423 * @throws NullPointerException if the specified element is null
424 * (<a href="../Collection.html#optional-restrictions">optional</a>)
426 boolean removeLastOccurrence(Object o);
428 // *** BlockingQueue methods ***
431 * Inserts the specified element into the queue represented by this deque
432 * (in other words, at the tail of this deque) if it is possible to do so
433 * immediately without violating capacity restrictions, returning
434 * <tt>true</tt> upon success and throwing an
435 * <tt>IllegalStateException</tt> if no space is currently available.
436 * When using a capacity-restricted deque, it is generally preferable to
437 * use {@link #offer(Object) offer}.
439 * <p>This method is equivalent to {@link #addLast(Object) addLast}.
441 * @param e the element to add
442 * @throws IllegalStateException {@inheritDoc}
443 * @throws ClassCastException if the class of the specified element
444 * prevents it from being added to this deque
445 * @throws NullPointerException if the specified element is null
446 * @throws IllegalArgumentException if some property of the specified
447 * element prevents it from being added to this deque
452 * Inserts the specified element into the queue represented by this deque
453 * (in other words, at the tail of this deque) if it is possible to do so
454 * immediately without violating capacity restrictions, returning
455 * <tt>true</tt> upon success and <tt>false</tt> if no space is currently
456 * available. When using a capacity-restricted deque, this method is
457 * generally preferable to the {@link #add} method, which can fail to
458 * insert an element only by throwing an exception.
460 * <p>This method is equivalent to {@link #offerLast(Object) offerLast}.
462 * @param e the element to add
463 * @throws ClassCastException if the class of the specified element
464 * prevents it from being added to this deque
465 * @throws NullPointerException if the specified element is null
466 * @throws IllegalArgumentException if some property of the specified
467 * element prevents it from being added to this deque
472 * Inserts the specified element into the queue represented by this deque
473 * (in other words, at the tail of this deque), waiting if necessary for
474 * space to become available.
476 * <p>This method is equivalent to {@link #putLast(Object) putLast}.
478 * @param e the element to add
479 * @throws InterruptedException {@inheritDoc}
480 * @throws ClassCastException if the class of the specified element
481 * prevents it from being added to this deque
482 * @throws NullPointerException if the specified element is null
483 * @throws IllegalArgumentException if some property of the specified
484 * element prevents it from being added to this deque
486 void put(E e) throws InterruptedException;
489 * Inserts the specified element into the queue represented by this deque
490 * (in other words, at the tail of this deque), waiting up to the
491 * specified wait time if necessary for space to become available.
493 * <p>This method is equivalent to
494 * {@link #offerLast(Object,long,TimeUnit) offerLast}.
496 * @param e the element to add
497 * @return <tt>true</tt> if the element was added to this deque, else
499 * @throws InterruptedException {@inheritDoc}
500 * @throws ClassCastException if the class of the specified element
501 * prevents it from being added to this deque
502 * @throws NullPointerException if the specified element is null
503 * @throws IllegalArgumentException if some property of the specified
504 * element prevents it from being added to this deque
506 boolean offer(E e, long timeout, TimeUnit unit)
507 throws InterruptedException;
510 * Retrieves and removes the head of the queue represented by this deque
511 * (in other words, the first element of this deque).
512 * This method differs from {@link #poll poll} only in that it
513 * throws an exception if this deque is empty.
515 * <p>This method is equivalent to {@link #removeFirst() removeFirst}.
517 * @return the head of the queue represented by this deque
518 * @throws NoSuchElementException if this deque is empty
523 * Retrieves and removes the head of the queue represented by this deque
524 * (in other words, the first element of this deque), or returns
525 * <tt>null</tt> if this deque is empty.
527 * <p>This method is equivalent to {@link #pollFirst()}.
529 * @return the head of this deque, or <tt>null</tt> if this deque is empty
534 * Retrieves and removes the head of the queue represented by this deque
535 * (in other words, the first element of this deque), waiting if
536 * necessary until an element becomes available.
538 * <p>This method is equivalent to {@link #takeFirst() takeFirst}.
540 * @return the head of this deque
541 * @throws InterruptedException if interrupted while waiting
543 E take() throws InterruptedException;
546 * Retrieves and removes the head of the queue represented by this deque
547 * (in other words, the first element of this deque), waiting up to the
548 * specified wait time if necessary for an element to become available.
550 * <p>This method is equivalent to
551 * {@link #pollFirst(long,TimeUnit) pollFirst}.
553 * @return the head of this deque, or <tt>null</tt> if the
554 * specified waiting time elapses before an element is available
555 * @throws InterruptedException if interrupted while waiting
557 E poll(long timeout, TimeUnit unit)
558 throws InterruptedException;
561 * Retrieves, but does not remove, the head of the queue represented by
562 * this deque (in other words, the first element of this deque).
563 * This method differs from {@link #peek peek} only in that it throws an
564 * exception if this deque is empty.
566 * <p>This method is equivalent to {@link #getFirst() getFirst}.
568 * @return the head of this deque
569 * @throws NoSuchElementException if this deque is empty
574 * Retrieves, but does not remove, the head of the queue represented by
575 * this deque (in other words, the first element of this deque), or
576 * returns <tt>null</tt> if this deque is empty.
578 * <p>This method is equivalent to {@link #peekFirst() peekFirst}.
580 * @return the head of this deque, or <tt>null</tt> if this deque is empty
585 * Removes the first occurrence of the specified element from this deque.
586 * If the deque does not contain the element, it is unchanged.
587 * More formally, removes the first element <tt>e</tt> such that
588 * <tt>o.equals(e)</tt> (if such an element exists).
589 * Returns <tt>true</tt> if this deque contained the specified element
590 * (or equivalently, if this deque changed as a result of the call).
592 * <p>This method is equivalent to
593 * {@link #removeFirstOccurrence(Object) removeFirstOccurrence}.
595 * @param o element to be removed from this deque, if present
596 * @return <tt>true</tt> if this deque changed as a result of the call
597 * @throws ClassCastException if the class of the specified element
598 * is incompatible with this deque
599 * (<a href="../Collection.html#optional-restrictions">optional</a>)
600 * @throws NullPointerException if the specified element is null
601 * (<a href="../Collection.html#optional-restrictions">optional</a>)
603 boolean remove(Object o);
606 * Returns <tt>true</tt> if this deque contains the specified element.
607 * More formally, returns <tt>true</tt> if and only if this deque contains
608 * at least one element <tt>e</tt> such that <tt>o.equals(e)</tt>.
610 * @param o object to be checked for containment in this deque
611 * @return <tt>true</tt> if this deque contains the specified element
612 * @throws ClassCastException if the class of the specified element
613 * is incompatible with this deque
614 * (<a href="../Collection.html#optional-restrictions">optional</a>)
615 * @throws NullPointerException if the specified element is null
616 * (<a href="../Collection.html#optional-restrictions">optional</a>)
618 public boolean contains(Object o);
621 * Returns the number of elements in this deque.
623 * @return the number of elements in this deque
628 * Returns an iterator over the elements in this deque in proper sequence.
629 * The elements will be returned in order from first (head) to last (tail).
631 * @return an iterator over the elements in this deque in proper sequence
633 Iterator<E> iterator();
635 // *** Stack methods ***
638 * Pushes an element onto the stack represented by this deque. In other
639 * words, inserts the element at the front of this deque unless it would
640 * violate capacity restrictions.
642 * <p>This method is equivalent to {@link #addFirst(Object) addFirst}.
644 * @throws IllegalStateException {@inheritDoc}
645 * @throws ClassCastException {@inheritDoc}
646 * @throws NullPointerException if the specified element is null
647 * @throws IllegalArgumentException {@inheritDoc}