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 e the element to add
     * @throws InterruptedException if interrupted while waiting.
     * @throws NullPointerException if the specified element is <tt>null</tt>.
     */
    void putFirst(E e) throws InterruptedException;

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