util/concurrent/BlockingDeque.java

/*
 * 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:<p>
 *
 * <table BORDER CELLPADDING=3 CELLSPACING=1>
 *  <tr>
 *    <td></td>
 *    <td ALIGN=CENTER COLSPAN = 2> <b>First Element (Head)</b></td>
 *    <td ALIGN=CENTER COLSPAN = 2> <b>Last Element (Tail)</b></td>
 *  </tr>
 *  <tr>
 *    <td></td>
 *    <td ALIGN=CENTER><em>Block</em></td>
 *    <td ALIGN=CENTER><em>Time out</em></td>
 *    <td ALIGN=CENTER><em>Block</em></td>
 *    <td ALIGN=CENTER><em>Time out</em></td>
 *  </tr>
 *  <tr>
 *    <td><b>Insert</b></td>
 *    <td>{@link #putFirst putFirst(e)}</td>
 *    <td>{@link #offerFirst(Object, long, TimeUnit) offerFirst(e, time, unit)}</td>
 *    <td>{@link #putLast putLast(e)}</td>
 *    <td>{@link #offerLast(Object, long, TimeUnit) offerLast(e, time, unit)}</td> 
 *  </tr>
 *  <tr>
 *    <td><b>Remove</b></td>
 *    <td>{@link #takeFirst takeFirst()}</td>
 *    <td>{@link #pollFirst(long, TimeUnit)  pollFirst(time, unit)}</td>
 *    <td>{@link #takeLast takeLast()}</td>
 *    <td>{@link #pollLast(long, TimeUnit) pollLast(time, unit)}</td>
 *  </tr>
 * </table>
 *
 * <p>Like any {@link BlockingQueue}, a <tt>BlockingDeque</tt> is
 * thread safe and may (or may not) be capacity-constrained.  A
 * <tt>BlockingDeque</tt> implementation may be used directly as a
 * FIFO <tt>BlockingQueue</tt>. The blocking methods inherited from
 * the <tt>BlockingQueue</tt> interface are precisely equivalent to
 * <tt>BlockingDeque</tt> methods as indicated in the following table:<p>
 *
 * <table BORDER CELLPADDING=3 CELLSPACING=1>
 *  <tr>
 *    <td ALIGN=CENTER> <b><tt>BlockingQueue</tt> Method</b></td>
 *    <td ALIGN=CENTER> <b>Equivalent <tt>BlockingDeque</tt> Method</b></td>
 *  </tr>
 *  <tr>
 *   <tr>
 *    <td>{@link java.util.concurrent.BlockingQueue#put put(e)}</td>
 *    <td>{@link #putLast putLast(e)}</td>
 *   </tr>
 *   <tr>
 *    <td>{@link java.util.concurrent.BlockingQueue#take take()}</td>
 *    <td>{@link #takeFirst takeFirst()}</td>
 *   </tr>
 *   <tr>
 *    <td>{@link java.util.concurrent.BlockingQueue#offer(Object, long, TimeUnit) offer(e, time. unit)}</td>
 *    <td>{@link #offerLast(Object, long, TimeUnit) offerLast(e, time, unit)}</td>
 *   </tr>
 *   <tr>
 *    <td>{@link java.util.concurrent.BlockingQueue#poll(long, TimeUnit) poll(time, unit)}</td>
 *    <td>{@link #pollFirst(long, TimeUnit) pollFirst(time, unit)}</td>
 *   </tr>
 * </table>
 *
 *
 * <p>This interface is a member of the
 * <a href="{@docRoot}/../guide/collections/index.html">
 * Java Collections Framework</a>.
 *
 * @since 1.6
 * @author Doug Lea
 * @param <E> the type of elements held in this collection
 */
public interface BlockingDeque<E> extends Deque<E>, BlockingQueue<E> {

    /**
     * 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 <tt>null</tt>.
     */
    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 <tt>null</tt>.
     */
    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
     * <tt>unit</tt>
     * @param unit a <tt>TimeUnit</tt> determining how to interpret the
     * <tt>timeout</tt> parameter
     * @return <tt>true</tt> if successful, or <tt>false</tt> if
     * the specified waiting time elapses before space is available.
     * @throws InterruptedException if interrupted while waiting.
     * @throws NullPointerException if the specified element is <tt>null</tt>.
     */
    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
     * <tt>unit</tt>
     * @param unit a <tt>TimeUnit</tt> determining how to interpret the
     * <tt>timeout</tt> parameter
     * @return <tt>true</tt> if successful, or <tt>false</tt> if
     * the specified waiting time elapses before space is available.
     * @throws InterruptedException if interrupted while waiting.
     * @throws NullPointerException if the specified element is <tt>null</tt>.
     */
    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
     * <tt>unit</tt>
     * @param unit a <tt>TimeUnit</tt> determining how to interpret the
     * <tt>timeout</tt> parameter
     * @return the head of this deque, or <tt>null</tt> 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
     * <tt>unit</tt>
     * @param unit a <tt>TimeUnit</tt> determining how to interpret the
     * <tt>timeout</tt> parameter
     * @return the head of this deque, or <tt>null</tt> 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 to putLast
     * @param o the element to add
     * @throws InterruptedException if interrupted while waiting.
     * @throws NullPointerException if the specified element is <tt>null</tt>.
     */
    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
     * <tt>offer</tt> 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 to
     * offerLast
     *
     * @param o the element to add.
     * @return <tt>true</tt> if it was possible to add the element to
     *         this deque, else <tt>false</tt>
     * @throws NullPointerException if the specified element is <tt>null</tt>
     */
    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 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 to
     * pollFirst
     * @param timeout how long to wait before giving up, in units of
     * <tt>unit</tt>
     * @param unit a <tt>TimeUnit</tt> determining how to interpret the
     * <tt>timeout</tt> parameter
     * @return the head of this deque, or <tt>null</tt> 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;
}
Revision:	1.1
Committed:	Tue Dec 28 12:14:13 2004 UTC (19 years, 5 months ago) by dl
Branch:	MAIN
Log Message:	Prepare jsr166x classes for Mustang integration
#	User	Rev	Content
1	dl	1.1	/*
2			* Written by Doug Lea with assistance from members of JCP JSR-166
3			* Expert Group and released to the public domain, as explained at
4			* http://creativecommons.org/licenses/publicdomain
5			*/
6
7			package java.util.concurrent;
8			import java.util.*;
9
10			/**
11			* A {@link Deque} that additionally supports operations that wait for
12			* the deque to become non-empty when retrieving an element, and wait
13			* for space to become available in the deque when storing an
14			* element. These methods are summarized in the following table:<p>
15			*
16			* <table BORDER CELLPADDING=3 CELLSPACING=1>
17			* <tr>
18			* <td></td>
19			* <td ALIGN=CENTER COLSPAN = 2> <b>First Element (Head)</b></td>
20			* <td ALIGN=CENTER COLSPAN = 2> <b>Last Element (Tail)</b></td>
21			* </tr>
22			* <tr>
23			* <td></td>
24			* <td ALIGN=CENTER><em>Block</em></td>
25			* <td ALIGN=CENTER><em>Time out</em></td>
26			* <td ALIGN=CENTER><em>Block</em></td>
27			* <td ALIGN=CENTER><em>Time out</em></td>
28			* </tr>
29			* <tr>
30			* <td><b>Insert</b></td>
31			* <td>{@link #putFirst putFirst(e)}</td>
32			* <td>{@link #offerFirst(Object, long, TimeUnit) offerFirst(e, time, unit)}</td>
33			* <td>{@link #putLast putLast(e)}</td>
34			* <td>{@link #offerLast(Object, long, TimeUnit) offerLast(e, time, unit)}</td>
35			* </tr>
36			* <tr>
37			* <td><b>Remove</b></td>
38			* <td>{@link #takeFirst takeFirst()}</td>
39			* <td>{@link #pollFirst(long, TimeUnit) pollFirst(time, unit)}</td>
40			* <td>{@link #takeLast takeLast()}</td>
41			* <td>{@link #pollLast(long, TimeUnit) pollLast(time, unit)}</td>
42			* </tr>
43			* </table>
44			*
45			* <p>Like any {@link BlockingQueue}, a <tt>BlockingDeque</tt> is
46			* thread safe and may (or may not) be capacity-constrained. A
47			* <tt>BlockingDeque</tt> implementation may be used directly as a
48			* FIFO <tt>BlockingQueue</tt>. The blocking methods inherited from
49			* the <tt>BlockingQueue</tt> interface are precisely equivalent to
50			* <tt>BlockingDeque</tt> methods as indicated in the following table:<p>
51			*
52			* <table BORDER CELLPADDING=3 CELLSPACING=1>
53			* <tr>
54			* <td ALIGN=CENTER> <b><tt>BlockingQueue</tt> Method</b></td>
55			* <td ALIGN=CENTER> <b>Equivalent <tt>BlockingDeque</tt> Method</b></td>
56			* </tr>
57			* <tr>
58			* <tr>
59			* <td>{@link java.util.concurrent.BlockingQueue#put put(e)}</td>
60			* <td>{@link #putLast putLast(e)}</td>
61			* </tr>
62			* <tr>
63			* <td>{@link java.util.concurrent.BlockingQueue#take take()}</td>
64			* <td>{@link #takeFirst takeFirst()}</td>
65			* </tr>
66			* <tr>
67			* <td>{@link java.util.concurrent.BlockingQueue#offer(Object, long, TimeUnit) offer(e, time. unit)}</td>
68			* <td>{@link #offerLast(Object, long, TimeUnit) offerLast(e, time, unit)}</td>
69			* </tr>
70			* <tr>
71			* <td>{@link java.util.concurrent.BlockingQueue#poll(long, TimeUnit) poll(time, unit)}</td>
72			* <td>{@link #pollFirst(long, TimeUnit) pollFirst(time, unit)}</td>
73			* </tr>
74			* </table>
75			*
76			*
77			* <p>This interface is a member of the
78			* <a href="{@docRoot}/../guide/collections/index.html">
79			* Java Collections Framework</a>.
80			*
81			* @since 1.6
82			* @author Doug Lea
83			* @param <E> the type of elements held in this collection
84			*/
85			public interface BlockingDeque<E> extends Deque<E>, BlockingQueue<E> {
86
87			/**
88			* Adds the specified element as the first element of this deque,
89			* waiting if necessary for space to become available.
90			* @param o the element to add
91			* @throws InterruptedException if interrupted while waiting.
92			* @throws NullPointerException if the specified element is <tt>null</tt>.
93			*/
94			void putFirst(E o) throws InterruptedException;
95
96			/**
97			* Adds the specified element as the last element of this deque,
98			* waiting if necessary for space to become available.
99			* @param o the element to add
100			* @throws InterruptedException if interrupted while waiting.
101			* @throws NullPointerException if the specified element is <tt>null</tt>.
102			*/
103			void putLast(E o) throws InterruptedException;
104
105			/**
106			* Retrieves and removes the first element of this deque, waiting
107			* if no elements are present on this deque.
108			* @return the head of this deque
109			* @throws InterruptedException if interrupted while waiting.
110			*/
111			E takeFirst() throws InterruptedException;
112
113			/**
114			* Retrieves and removes the last element of this deque, waiting
115			* if no elements are present on this deque.
116			* @return the head of this deque
117			* @throws InterruptedException if interrupted while waiting.
118			*/
119			E takeLast() throws InterruptedException;
120
121			/**
122			* Inserts the specified element as the first element of this deque,
123			* waiting if necessary up to the specified wait time for space to
124			* become available.
125			* @param o the element to add
126			* @param timeout how long to wait before giving up, in units of
127			* <tt>unit</tt>
128			* @param unit a <tt>TimeUnit</tt> determining how to interpret the
129			* <tt>timeout</tt> parameter
130			* @return <tt>true</tt> if successful, or <tt>false</tt> if
131			* the specified waiting time elapses before space is available.
132			* @throws InterruptedException if interrupted while waiting.
133			* @throws NullPointerException if the specified element is <tt>null</tt>.
134			*/
135			boolean offerFirst(E o, long timeout, TimeUnit unit)
136			throws InterruptedException;
137
138			/**
139			* Inserts the specified element as the last element of this deque,
140			* waiting if necessary up to the specified wait time for space to
141			* become available.
142			* @param o the element to add
143			* @param timeout how long to wait before giving up, in units of
144			* <tt>unit</tt>
145			* @param unit a <tt>TimeUnit</tt> determining how to interpret the
146			* <tt>timeout</tt> parameter
147			* @return <tt>true</tt> if successful, or <tt>false</tt> if
148			* the specified waiting time elapses before space is available.
149			* @throws InterruptedException if interrupted while waiting.
150			* @throws NullPointerException if the specified element is <tt>null</tt>.
151			*/
152			boolean offerLast(E o, long timeout, TimeUnit unit)
153			throws InterruptedException;
154
155
156			/**
157			* Retrieves and removes the first element of this deque, waiting
158			* if necessary up to the specified wait time if no elements are
159			* present on this deque.
160			* @param timeout how long to wait before giving up, in units of
161			* <tt>unit</tt>
162			* @param unit a <tt>TimeUnit</tt> determining how to interpret the
163			* <tt>timeout</tt> parameter
164			* @return the head of this deque, or <tt>null</tt> if the
165			* specified waiting time elapses before an element is present.
166			* @throws InterruptedException if interrupted while waiting.
167			*/
168			E pollFirst(long timeout, TimeUnit unit)
169			throws InterruptedException;
170
171			/**
172			* Retrieves and removes the last element of this deque, waiting
173			* if necessary up to the specified wait time if no elements are
174			* present on this deque.
175			* @param timeout how long to wait before giving up, in units of
176			* <tt>unit</tt>
177			* @param unit a <tt>TimeUnit</tt> determining how to interpret the
178			* <tt>timeout</tt> parameter
179			* @return the head of this deque, or <tt>null</tt> if the
180			* specified waiting time elapses before an element is present.
181			* @throws InterruptedException if interrupted while waiting.
182			*/
183			E pollLast(long timeout, TimeUnit unit)
184			throws InterruptedException;
185
186			/**
187			* Adds the specified element as the last element of this deque,
188			* waiting if necessary for space to become available. This
189			* method is equivalent to to putLast
190			* @param o the element to add
191			* @throws InterruptedException if interrupted while waiting.
192			* @throws NullPointerException if the specified element is <tt>null</tt>.
193			*/
194			void put(E o) throws InterruptedException;
195
196			/**
197			* Inserts the specified element as the lest element of this
198			* deque, if possible. When using deques that may impose
199			* insertion restrictions (for example capacity bounds), method
200			* <tt>offer</tt> is generally preferable to method {@link
201			* Collection#add}, which can fail to insert an element only by
202			* throwing an exception. This method is equivalent to to
203			* offerLast
204			*
205			* @param o the element to add.
206			* @return <tt>true</tt> if it was possible to add the element to
207			* this deque, else <tt>false</tt>
208			* @throws NullPointerException if the specified element is <tt>null</tt>
209			*/
210			boolean offer(E o, long timeout, TimeUnit unit)
211			throws InterruptedException;
212
213			/**
214			* Retrieves and removes the first element of this deque, waiting
215			* if no elements are present on this deque.
216			* This method is equivalent to to takeFirst
217			* @return the head of this deque
218			* @throws InterruptedException if interrupted while waiting.
219			*/
220			E take() throws InterruptedException;
221
222			/**
223			* Retrieves and removes the first element of this deque, waiting
224			* if necessary up to the specified wait time if no elements are
225			* present on this deque. This method is equivalent to to
226			* pollFirst
227			* @param timeout how long to wait before giving up, in units of
228			* <tt>unit</tt>
229			* @param unit a <tt>TimeUnit</tt> determining how to interpret the
230			* <tt>timeout</tt> parameter
231			* @return the head of this deque, or <tt>null</tt> if the
232			* specified waiting time elapses before an element is present.
233			* @throws InterruptedException if interrupted while waiting.
234			*/
235			E poll(long timeout, TimeUnit unit)
236			throws InterruptedException;
237			}