src/jsr166x/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/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:<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 {@code BlockingDeque} is
 * thread safe and may (or may not) be capacity-constrained.  A
 * {@code BlockingDeque} implementation may be used directly as a
 * FIFO {@code BlockingQueue}. The blocking methods inherited from
 * the {@code BlockingQueue} interface are precisely equivalent to
 * {@code BlockingDeque} methods as indicated in the following table:<p>
 *
 * <table BORDER CELLPADDING=3 CELLSPACING=1>
 *  <tr>
 *    <td ALIGN=CENTER> <b>{@code BlockingQueue} Method</b></td>
 *    <td ALIGN=CENTER> <b>Equivalent {@code BlockingDeque} 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 {@code 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 {@code 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
     * {@code unit}
     * @param unit a {@code TimeUnit} determining how to interpret the
     * {@code timeout} parameter
     * @return {@code true} if successful, or {@code false} if
     * the specified waiting time elapses before space is available
     * @throws InterruptedException if interrupted while waiting
     * @throws NullPointerException if the specified element is {@code 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
     * {@code unit}
     * @param unit a {@code TimeUnit} determining how to interpret the
     * {@code timeout} parameter
     * @return {@code true} if successful, or {@code false} if
     * the specified waiting time elapses before space is available
     * @throws InterruptedException if interrupted while waiting
     * @throws NullPointerException if the specified element is {@code 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
     * {@code unit}
     * @param unit a {@code TimeUnit} determining how to interpret the
     * {@code timeout} parameter
     * @return the head of this deque, or {@code 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
     * {@code unit}
     * @param unit a {@code TimeUnit} determining how to interpret the
     * {@code timeout} parameter
     * @return the head of this deque, or {@code 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 {@code 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
     * {@code 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 {@code true} if it was possible to add the element to
     *         this deque, else {@code false}
     * @throws NullPointerException if the specified element is {@code 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
     * {@code unit}
     * @param unit a {@code TimeUnit} determining how to interpret the
     * {@code timeout} parameter
     * @return the head of this deque, or {@code 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;
}
Revision:	1.8
Committed:	Sun Jan 18 20:17:33 2015 UTC (9 years, 3 months ago) by jsr166
Branch:	MAIN
Changes since 1.7:	+1 -0 lines
Log Message:	exactly one blank line before and after package statements
#	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	jsr166	1.4	* http://creativecommons.org/publicdomain/zero/1.0/
5	dl	1.1	*/
6
7			package jsr166x; // XXX This belongs in java.util!!! XXX
8	jsr166	1.8
9	dl	1.1	import java.util.concurrent.*; // XXX This import goes away XXX
10	jsr166	1.2	import java.util.*;
11	dl	1.1
12			/**
13			* A {@link Deque} that additionally supports operations that wait for
14			* the deque to become non-empty when retrieving an element, and wait
15			* for space to become available in the deque when storing an
16			* element. These methods are summarized in the following table:<p>
17			*
18			* <table BORDER CELLPADDING=3 CELLSPACING=1>
19			* <tr>
20			* <td></td>
21			* <td ALIGN=CENTER COLSPAN = 2> <b>First Element (Head)</b></td>
22			* <td ALIGN=CENTER COLSPAN = 2> <b>Last Element (Tail)</b></td>
23			* </tr>
24			* <tr>
25			* <td></td>
26			* <td ALIGN=CENTER><em>Block</em></td>
27			* <td ALIGN=CENTER><em>Time out</em></td>
28			* <td ALIGN=CENTER><em>Block</em></td>
29			* <td ALIGN=CENTER><em>Time out</em></td>
30			* </tr>
31			* <tr>
32			* <td><b>Insert</b></td>
33			* <td>{@link #putFirst putFirst(e)}</td>
34			* <td>{@link #offerFirst(Object, long, TimeUnit) offerFirst(e, time, unit)}</td>
35			* <td>{@link #putLast putLast(e)}</td>
36	jsr166	1.2	* <td>{@link #offerLast(Object, long, TimeUnit) offerLast(e, time, unit)}</td>
37	dl	1.1	* </tr>
38			* <tr>
39			* <td><b>Remove</b></td>
40			* <td>{@link #takeFirst takeFirst()}</td>
41			* <td>{@link #pollFirst(long, TimeUnit) pollFirst(time, unit)}</td>
42			* <td>{@link #takeLast takeLast()}</td>
43			* <td>{@link #pollLast(long, TimeUnit) pollLast(time, unit)}</td>
44			* </tr>
45			* </table>
46			*
47	jsr166	1.7	* <p>Like any {@link BlockingQueue}, a {@code BlockingDeque} is
48	dl	1.1	* thread safe and may (or may not) be capacity-constrained. A
49	jsr166	1.7	* {@code BlockingDeque} implementation may be used directly as a
50			* FIFO {@code BlockingQueue}. The blocking methods inherited from
51			* the {@code BlockingQueue} interface are precisely equivalent to
52			* {@code BlockingDeque} methods as indicated in the following table:<p>
53	dl	1.1	*
54			* <table BORDER CELLPADDING=3 CELLSPACING=1>
55			* <tr>
56	jsr166	1.7	* <td ALIGN=CENTER> <b>{@code BlockingQueue} Method</b></td>
57			* <td ALIGN=CENTER> <b>Equivalent {@code BlockingDeque} Method</b></td>
58	dl	1.1	* </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 o the element to add
93	jsr166	1.5	* @throws InterruptedException if interrupted while waiting
94	jsr166	1.7	* @throws NullPointerException if the specified element is {@code null}
95	dl	1.1	*/
96			void putFirst(E o) 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 o the element to add
102	jsr166	1.5	* @throws InterruptedException if interrupted while waiting
103	jsr166	1.7	* @throws NullPointerException if the specified element is {@code null}
104	dl	1.1	*/
105			void putLast(E o) 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	jsr166	1.5	* @throws InterruptedException if interrupted while waiting
112	dl	1.1	*/
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	jsr166	1.5	* @throws InterruptedException if interrupted while waiting
120	dl	1.1	*/
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 o the element to add
128			* @param timeout how long to wait before giving up, in units of
129	jsr166	1.7	* {@code unit}
130			* @param unit a {@code TimeUnit} determining how to interpret the
131			* {@code timeout} parameter
132			* @return {@code true} if successful, or {@code false} if
133	jsr166	1.5	* the specified waiting time elapses before space is available
134			* @throws InterruptedException if interrupted while waiting
135	jsr166	1.7	* @throws NullPointerException if the specified element is {@code null}
136	dl	1.1	*/
137			boolean offerFirst(E o, 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 o the element to add
145			* @param timeout how long to wait before giving up, in units of
146	jsr166	1.7	* {@code unit}
147			* @param unit a {@code TimeUnit} determining how to interpret the
148			* {@code timeout} parameter
149			* @return {@code true} if successful, or {@code false} if
150	jsr166	1.5	* the specified waiting time elapses before space is available
151			* @throws InterruptedException if interrupted while waiting
152	jsr166	1.7	* @throws NullPointerException if the specified element is {@code null}
153	dl	1.1	*/
154			boolean offerLast(E o, 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	jsr166	1.7	* {@code unit}
164			* @param unit a {@code TimeUnit} determining how to interpret the
165			* {@code timeout} parameter
166			* @return the head of this deque, or {@code null} if the
167	jsr166	1.5	* specified waiting time elapses before an element is present
168			* @throws InterruptedException if interrupted while waiting
169	dl	1.1	*/
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	jsr166	1.7	* {@code unit}
179			* @param unit a {@code TimeUnit} determining how to interpret the
180			* {@code timeout} parameter
181			* @return the head of this deque, or {@code null} if the
182	jsr166	1.5	* specified waiting time elapses before an element is present
183			* @throws InterruptedException if interrupted while waiting
184	dl	1.1	*/
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. This
191	jsr166	1.6	* method is equivalent to putLast.
192	dl	1.1	* @param o the element to add
193	jsr166	1.5	* @throws InterruptedException if interrupted while waiting
194	jsr166	1.7	* @throws NullPointerException if the specified element is {@code null}
195	dl	1.1	*/
196			void put(E o) throws InterruptedException;
197
198	jsr166	1.2	/**
199	dl	1.1	* Inserts the specified element as the lest element of this
200			* deque, if possible. When using deques that may impose
201			* insertion restrictions (for example capacity bounds), method
202	jsr166	1.7	* {@code offer} is generally preferable to method {@link
203	dl	1.1	* Collection#add}, which can fail to insert an element only by
204	jsr166	1.3	* throwing an exception. This method is equivalent to
205	jsr166	1.5	* offerLast.
206	dl	1.1	*
207	jsr166	1.5	* @param o the element to add
208	jsr166	1.7	* @return {@code true} if it was possible to add the element to
209			* this deque, else {@code false}
210			* @throws NullPointerException if the specified element is {@code null}
211	dl	1.1	*/
212			boolean offer(E o, long timeout, TimeUnit unit)
213			throws InterruptedException;
214
215			/**
216			* Retrieves and removes the first element of this deque, waiting
217			* if no elements are present on this deque.
218	jsr166	1.5	* This method is equivalent to takeFirst.
219	dl	1.1	* @return the head of this deque
220	jsr166	1.5	* @throws InterruptedException if interrupted while waiting
221	dl	1.1	*/
222			E take() throws InterruptedException;
223
224			/**
225			* Retrieves and removes the first element of this deque, waiting
226			* if necessary up to the specified wait time if no elements are
227	jsr166	1.3	* present on this deque. This method is equivalent to
228	jsr166	1.5	* pollFirst.
229	dl	1.1	* @param timeout how long to wait before giving up, in units of
230	jsr166	1.7	* {@code unit}
231			* @param unit a {@code TimeUnit} determining how to interpret the
232			* {@code timeout} parameter
233			* @return the head of this deque, or {@code null} if the
234	jsr166	1.5	* specified waiting time elapses before an element is present
235			* @throws InterruptedException if interrupted while waiting
236	dl	1.1	*/
237			E poll(long timeout, TimeUnit unit)
238			throws InterruptedException;
239			}