/*
* 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/publicdomain/zero/1.0/
*/
package jsr166x; // XXX This belongs in java.util!!! XXX
import java.util.concurrent.*; // XXX This import goes away XXX
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 the type of elements held in this collection
*/
public interface BlockingDeque extends Deque, BlockingQueue {
/**
* Adds the specified element as the first element of this deque,
* waiting if necessary for space to become available.
* @param o the element to add
* @throws InterruptedException if interrupted while waiting
* @throws NullPointerException if the specified element is null
*/
void putFirst(E o) throws InterruptedException;
/**
* Adds the specified element as the last element of this deque,
* waiting if necessary for space to become available.
* @param o the element to add
* @throws InterruptedException if interrupted while waiting
* @throws NullPointerException if the specified element is null
*/
void putLast(E o) throws InterruptedException;
/**
* Retrieves and removes the first element of this deque, waiting
* if no elements are present on this deque.
* @return the head of this deque
* @throws InterruptedException if interrupted while waiting
*/
E takeFirst() throws InterruptedException;
/**
* Retrieves and removes the last element of this deque, waiting
* if no elements are present on this deque.
* @return the head of this deque
* @throws InterruptedException if interrupted while waiting
*/
E takeLast() throws InterruptedException;
/**
* Inserts the specified element as the first element of this deque,
* waiting if necessary up to the specified wait time for space to
* become available.
* @param o the element to add
* @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 true if successful, or false if
* the specified waiting time elapses before space is available
* @throws InterruptedException if interrupted while waiting
* @throws NullPointerException if the specified element is null
*/
boolean offerFirst(E o, long timeout, TimeUnit unit)
throws InterruptedException;
/**
* Inserts the specified element as the last element of this deque,
* waiting if necessary up to the specified wait time for space to
* become available.
* @param o the element to add
* @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 true if successful, or false if
* the specified waiting time elapses before space is available
* @throws InterruptedException if interrupted while waiting
* @throws NullPointerException if the specified element is null
*/
boolean offerLast(E o, long timeout, TimeUnit unit)
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.
* @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 pollFirst(long timeout, TimeUnit unit)
throws InterruptedException;
/**
* Retrieves and removes the last element of this deque, waiting
* if necessary up to the specified wait time if no elements are
* present on this deque.
* @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 pollLast(long timeout, TimeUnit unit)
throws InterruptedException;
/**
* Adds the specified element as the last element of this deque,
* waiting if necessary for space to become available. This
* method is equivalent to putLast
* @param o the element to add
* @throws InterruptedException if interrupted while waiting
* @throws NullPointerException if the specified element is null
*/
void put(E o) throws InterruptedException;
/**
* Inserts the specified element as the lest 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
* offerLast.
*
* @param o 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 o, 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 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
* 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;
}