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.9
Committed:	Fri Jul 15 18:49:12 2016 UTC (7 years, 9 months ago) by jsr166
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.8:	+0 -1 lines
Log Message:	whitespace
#	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			* <p>This interface is a member of the
79			* <a href="{@docRoot}/../guide/collections/index.html">
80			* Java Collections Framework</a>.
81			*
82			* @since 1.6
83			* @author Doug Lea
84			* @param <E> the type of elements held in this collection
85			*/
86			public interface BlockingDeque<E> extends Deque<E>, BlockingQueue<E> {
87
88			/**
89			* Adds the specified element as the first element of this deque,
90			* waiting if necessary for space to become available.
91			* @param o the element to add
92	jsr166	1.5	* @throws InterruptedException if interrupted while waiting
93	jsr166	1.7	* @throws NullPointerException if the specified element is {@code null}
94	dl	1.1	*/
95			void putFirst(E o) throws InterruptedException;
96
97			/**
98			* Adds the specified element as the last element of this deque,
99			* waiting if necessary for space to become available.
100			* @param o the element to add
101	jsr166	1.5	* @throws InterruptedException if interrupted while waiting
102	jsr166	1.7	* @throws NullPointerException if the specified element is {@code null}
103	dl	1.1	*/
104			void putLast(E o) throws InterruptedException;
105
106			/**
107			* Retrieves and removes the first element of this deque, waiting
108			* if no elements are present on this deque.
109			* @return the head of this deque
110	jsr166	1.5	* @throws InterruptedException if interrupted while waiting
111	dl	1.1	*/
112			E takeFirst() throws InterruptedException;
113
114			/**
115			* Retrieves and removes the last element of this deque, waiting
116			* if no elements are present on this deque.
117			* @return the head of this deque
118	jsr166	1.5	* @throws InterruptedException if interrupted while waiting
119	dl	1.1	*/
120			E takeLast() throws InterruptedException;
121
122			/**
123			* Inserts the specified element as the first element of this deque,
124			* waiting if necessary up to the specified wait time for space to
125			* become available.
126			* @param o the element to add
127			* @param timeout how long to wait before giving up, in units of
128	jsr166	1.7	* {@code unit}
129			* @param unit a {@code TimeUnit} determining how to interpret the
130			* {@code timeout} parameter
131			* @return {@code true} if successful, or {@code false} if
132	jsr166	1.5	* the specified waiting time elapses before space is available
133			* @throws InterruptedException if interrupted while waiting
134	jsr166	1.7	* @throws NullPointerException if the specified element is {@code null}
135	dl	1.1	*/
136			boolean offerFirst(E o, long timeout, TimeUnit unit)
137			throws InterruptedException;
138
139			/**
140			* Inserts the specified element as the last element of this deque,
141			* waiting if necessary up to the specified wait time for space to
142			* become available.
143			* @param o the element to add
144			* @param timeout how long to wait before giving up, in units of
145	jsr166	1.7	* {@code unit}
146			* @param unit a {@code TimeUnit} determining how to interpret the
147			* {@code timeout} parameter
148			* @return {@code true} if successful, or {@code false} if
149	jsr166	1.5	* the specified waiting time elapses before space is available
150			* @throws InterruptedException if interrupted while waiting
151	jsr166	1.7	* @throws NullPointerException if the specified element is {@code null}
152	dl	1.1	*/
153			boolean offerLast(E o, long timeout, TimeUnit unit)
154			throws InterruptedException;
155
156
157			/**
158			* Retrieves and removes the first element of this deque, waiting
159			* if necessary up to the specified wait time if no elements are
160			* present on this deque.
161			* @param timeout how long to wait before giving up, in units of
162	jsr166	1.7	* {@code unit}
163			* @param unit a {@code TimeUnit} determining how to interpret the
164			* {@code timeout} parameter
165			* @return the head of this deque, or {@code null} if the
166	jsr166	1.5	* specified waiting time elapses before an element is present
167			* @throws InterruptedException if interrupted while waiting
168	dl	1.1	*/
169			E pollFirst(long timeout, TimeUnit unit)
170			throws InterruptedException;
171
172			/**
173			* Retrieves and removes the last element of this deque, waiting
174			* if necessary up to the specified wait time if no elements are
175			* present on this deque.
176			* @param timeout how long to wait before giving up, in units of
177	jsr166	1.7	* {@code unit}
178			* @param unit a {@code TimeUnit} determining how to interpret the
179			* {@code timeout} parameter
180			* @return the head of this deque, or {@code null} if the
181	jsr166	1.5	* specified waiting time elapses before an element is present
182			* @throws InterruptedException if interrupted while waiting
183	dl	1.1	*/
184			E pollLast(long timeout, TimeUnit unit)
185			throws InterruptedException;
186
187			/**
188			* Adds the specified element as the last element of this deque,
189			* waiting if necessary for space to become available. This
190	jsr166	1.6	* method is equivalent to putLast.
191	dl	1.1	* @param o the element to add
192	jsr166	1.5	* @throws InterruptedException if interrupted while waiting
193	jsr166	1.7	* @throws NullPointerException if the specified element is {@code null}
194	dl	1.1	*/
195			void put(E o) throws InterruptedException;
196
197	jsr166	1.2	/**
198	dl	1.1	* Inserts the specified element as the lest element of this
199			* deque, if possible. When using deques that may impose
200			* insertion restrictions (for example capacity bounds), method
201	jsr166	1.7	* {@code offer} is generally preferable to method {@link
202	dl	1.1	* Collection#add}, which can fail to insert an element only by
203	jsr166	1.3	* throwing an exception. This method is equivalent to
204	jsr166	1.5	* offerLast.
205	dl	1.1	*
206	jsr166	1.5	* @param o the element to add
207	jsr166	1.7	* @return {@code true} if it was possible to add the element to
208			* this deque, else {@code false}
209			* @throws NullPointerException if the specified element is {@code null}
210	dl	1.1	*/
211			boolean offer(E o, long timeout, TimeUnit unit)
212			throws InterruptedException;
213
214			/**
215			* Retrieves and removes the first element of this deque, waiting
216			* if no elements are present on this deque.
217	jsr166	1.5	* This method is equivalent to takeFirst.
218	dl	1.1	* @return the head of this deque
219	jsr166	1.5	* @throws InterruptedException if interrupted while waiting
220	dl	1.1	*/
221			E take() throws InterruptedException;
222
223			/**
224			* Retrieves and removes the first element of this deque, waiting
225			* if necessary up to the specified wait time if no elements are
226	jsr166	1.3	* present on this deque. This method is equivalent to
227	jsr166	1.5	* pollFirst.
228	dl	1.1	* @param timeout how long to wait before giving up, in units of
229	jsr166	1.7	* {@code unit}
230			* @param unit a {@code TimeUnit} determining how to interpret the
231			* {@code timeout} parameter
232			* @return the head of this deque, or {@code null} if the
233	jsr166	1.5	* specified waiting time elapses before an element is present
234			* @throws InterruptedException if interrupted while waiting
235	dl	1.1	*/
236			E poll(long timeout, TimeUnit unit)
237			throws InterruptedException;
238			}