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 |
4 |
> |
* http://creativecommons.org/publicdomain/zero/1.0/ |
5 |
|
*/ |
6 |
|
|
7 |
|
package jsr166x; // XXX This belongs in java.util!!! XXX |
8 |
+ |
|
9 |
|
import java.util.concurrent.*; // XXX This import goes away XXX |
10 |
|
import java.util.*; |
11 |
|
|
44 |
|
* </tr> |
45 |
|
* </table> |
46 |
|
* |
47 |
< |
* <p>Like any {@link BlockingQueue}, a <tt>BlockingDeque</tt> is |
47 |
> |
* <p>Like any {@link BlockingQueue}, a {@code BlockingDeque} is |
48 |
|
* thread safe and may (or may not) be capacity-constrained. A |
49 |
< |
* <tt>BlockingDeque</tt> implementation may be used directly as a |
50 |
< |
* FIFO <tt>BlockingQueue</tt>. The blocking methods inherited from |
51 |
< |
* the <tt>BlockingQueue</tt> interface are precisely equivalent to |
52 |
< |
* <tt>BlockingDeque</tt> methods as indicated in the following table:<p> |
49 |
> |
* {@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 |
|
* |
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> |
56 |
> |
* <td ALIGN=CENTER> <b>{@code BlockingQueue} Method</b></td> |
57 |
> |
* <td ALIGN=CENTER> <b>Equivalent {@code BlockingDeque} Method</b></td> |
58 |
|
* </tr> |
59 |
|
* <tr> |
60 |
|
* <tr> |
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 |
< |
* @throws InterruptedException if interrupted while waiting. |
94 |
< |
* @throws NullPointerException if the specified element is <tt>null</tt>. |
93 |
> |
* @throws InterruptedException if interrupted while waiting |
94 |
> |
* @throws NullPointerException if the specified element is {@code null} |
95 |
|
*/ |
96 |
|
void putFirst(E o) throws InterruptedException; |
97 |
|
|
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 |
< |
* @throws InterruptedException if interrupted while waiting. |
103 |
< |
* @throws NullPointerException if the specified element is <tt>null</tt>. |
102 |
> |
* @throws InterruptedException if interrupted while waiting |
103 |
> |
* @throws NullPointerException if the specified element is {@code null} |
104 |
|
*/ |
105 |
|
void putLast(E o) throws InterruptedException; |
106 |
|
|
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. |
111 |
> |
* @throws InterruptedException if interrupted while waiting |
112 |
|
*/ |
113 |
|
E takeFirst() throws InterruptedException; |
114 |
|
|
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. |
119 |
> |
* @throws InterruptedException if interrupted while waiting |
120 |
|
*/ |
121 |
|
E takeLast() throws InterruptedException; |
122 |
|
|
126 |
|
* become available. |
127 |
|
* @param o 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>. |
129 |
> |
* {@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 |
> |
* the specified waiting time elapses before space is available |
134 |
> |
* @throws InterruptedException if interrupted while waiting |
135 |
> |
* @throws NullPointerException if the specified element is {@code null} |
136 |
|
*/ |
137 |
|
boolean offerFirst(E o, long timeout, TimeUnit unit) |
138 |
|
throws InterruptedException; |
143 |
|
* become available. |
144 |
|
* @param o 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>. |
146 |
> |
* {@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 |
> |
* the specified waiting time elapses before space is available |
151 |
> |
* @throws InterruptedException if interrupted while waiting |
152 |
> |
* @throws NullPointerException if the specified element is {@code null} |
153 |
|
*/ |
154 |
|
boolean offerLast(E o, long timeout, TimeUnit unit) |
155 |
|
throws InterruptedException; |
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. |
163 |
> |
* {@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 |
> |
* 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; |
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. |
178 |
> |
* {@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 |
> |
* 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; |
188 |
|
/** |
189 |
|
* Adds the specified element as the last element of this deque, |
190 |
|
* waiting if necessary for space to become available. This |
191 |
< |
* method is equivalent to to putLast |
191 |
> |
* method is equivalent to putLast. |
192 |
|
* @param o the element to add |
193 |
< |
* @throws InterruptedException if interrupted while waiting. |
194 |
< |
* @throws NullPointerException if the specified element is <tt>null</tt>. |
193 |
> |
* @throws InterruptedException if interrupted while waiting |
194 |
> |
* @throws NullPointerException if the specified element is {@code null} |
195 |
|
*/ |
196 |
|
void put(E o) throws InterruptedException; |
197 |
|
|
199 |
|
* 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 |
< |
* <tt>offer</tt> is generally preferable to method {@link |
202 |
> |
* {@code offer} is generally preferable to method {@link |
203 |
|
* Collection#add}, which can fail to insert an element only by |
204 |
< |
* throwing an exception. This method is equivalent to to |
205 |
< |
* offerLast |
204 |
> |
* throwing an exception. This method is equivalent to |
205 |
> |
* offerLast. |
206 |
|
* |
207 |
< |
* @param o the element to add. |
208 |
< |
* @return <tt>true</tt> if it was possible to add the element to |
209 |
< |
* this deque, else <tt>false</tt> |
210 |
< |
* @throws NullPointerException if the specified element is <tt>null</tt> |
207 |
> |
* @param o the element to add |
208 |
> |
* @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 |
|
*/ |
212 |
|
boolean offer(E o, long timeout, TimeUnit unit) |
213 |
|
throws InterruptedException; |
215 |
|
/** |
216 |
|
* Retrieves and removes the first element of this deque, waiting |
217 |
|
* if no elements are present on this deque. |
218 |
< |
* This method is equivalent to to takeFirst |
218 |
> |
* This method is equivalent to takeFirst. |
219 |
|
* @return the head of this deque |
220 |
< |
* @throws InterruptedException if interrupted while waiting. |
220 |
> |
* @throws InterruptedException if interrupted while waiting |
221 |
|
*/ |
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 |
< |
* present on this deque. This method is equivalent to to |
228 |
< |
* pollFirst |
227 |
> |
* present on this deque. This method is equivalent to |
228 |
> |
* pollFirst. |
229 |
|
* @param timeout how long to wait before giving up, in units of |
230 |
< |
* <tt>unit</tt> |
231 |
< |
* @param unit a <tt>TimeUnit</tt> determining how to interpret the |
232 |
< |
* <tt>timeout</tt> parameter |
233 |
< |
* @return the head of this deque, or <tt>null</tt> if the |
234 |
< |
* specified waiting time elapses before an element is present. |
235 |
< |
* @throws InterruptedException if interrupted while waiting. |
230 |
> |
* {@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 |
> |
* specified waiting time elapses before an element is present |
235 |
> |
* @throws InterruptedException if interrupted while waiting |
236 |
|
*/ |
237 |
|
E poll(long timeout, TimeUnit unit) |
238 |
|
throws InterruptedException; |