/* * Written by Doug Lea with assistance from members of JCP JSR-166 * Expert Group and released to the public domain, as explained at * http://creativecommons.org/licenses/publicdomain */ package java.util.concurrent; import java.util.*; /** * A {@link Deque} that additionally supports operations that wait for * the deque to become non-empty when retrieving an element, and wait * for space to become available in the deque when storing an * element. These methods are summarized in the following table:
* *
* | First Element (Head) | *Last Element (Tail) | *||
* | Block | *Time out | *Block | *Time out | *
Insert | *{@link #putFirst putFirst(e)} | *{@link #offerFirst(Object, long, TimeUnit) offerFirst(e, time, unit)} | *{@link #putLast putLast(e)} | *{@link #offerLast(Object, long, TimeUnit) offerLast(e, time, unit)} | *
Remove | *{@link #takeFirst takeFirst()} | *{@link #pollFirst(long, TimeUnit) pollFirst(time, unit)} | *{@link #takeLast takeLast()} | *{@link #pollLast(long, TimeUnit) pollLast(time, unit)} | *
Like any {@link BlockingQueue}, a BlockingDeque is * thread safe and may (or may not) be capacity-constrained. A * BlockingDeque implementation may be used directly as a * FIFO BlockingQueue. The blocking methods inherited from * the BlockingQueue interface are precisely equivalent to * BlockingDeque methods as indicated in the following table:
* *
BlockingQueue Method | *Equivalent BlockingDeque Method | *
{@link java.util.concurrent.BlockingQueue#put put(e)} | *{@link #putLast putLast(e)} | *
{@link java.util.concurrent.BlockingQueue#take take()} | *{@link #takeFirst takeFirst()} | *
{@link java.util.concurrent.BlockingQueue#offer(Object, long, TimeUnit) offer(e, time. unit)} | *{@link #offerLast(Object, long, TimeUnit) offerLast(e, time, unit)} | *
{@link java.util.concurrent.BlockingQueue#poll(long, TimeUnit) poll(time, unit)} | *{@link #pollFirst(long, TimeUnit) pollFirst(time, unit)} | *
This interface is a member of the
*
* Java Collections Framework.
*
* @since 1.6
* @author Doug Lea
* @param This method is equivalent to {@link #putLast}.
*
* @param e the element to add
* @throws InterruptedException if interrupted while waiting.
* @throws NullPointerException if the specified element is null.
*/
void put(E e) throws InterruptedException;
/**
* Inserts the specified element as the last element of this
* deque, if possible. When using deques that may impose
* insertion restrictions (for example capacity bounds), method
* offer is generally preferable to method {@link
* Collection#add}, which can fail to insert an element only by
* throwing an exception.
*
* This method is equivalent to {@link #offerLast}.
*
* @param e the element to add.
* @return true if it was possible to add the element to
* this deque, else false
* @throws NullPointerException if the specified element is null
*/
boolean offer(E e, long timeout, TimeUnit unit)
throws InterruptedException;
/**
* Retrieves and removes the first element of this deque, waiting
* if no elements are present on this deque.
*
* This method is equivalent to {@link #takeFirst}.
*
* @return the head of this deque
* @throws InterruptedException if interrupted while waiting.
*/
E take() throws InterruptedException;
/**
* Retrieves and removes the first element of this deque, waiting
* if necessary up to the specified wait time if no elements are
* present on this deque.
*
* This method is equivalent to {@link #pollFirst}.
*
* @param timeout how long to wait before giving up, in units of
* unit
* @param unit a TimeUnit determining how to interpret the
* timeout parameter
* @return the head of this deque, or null if the
* specified waiting time elapses before an element is present.
* @throws InterruptedException if interrupted while waiting.
*/
E poll(long timeout, TimeUnit unit)
throws InterruptedException;
}