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 |
jsr166 |
1.4 |
import java.util.*; |
9 |
dl |
1.1 |
|
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 |
jsr166 |
1.4 |
* <td>{@link #offerLast(Object, long, TimeUnit) offerLast(e, time, unit)}</td> |
35 |
dl |
1.1 |
* </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 |
dl |
1.3 |
* method is equivalent to putLast. |
190 |
dl |
1.1 |
* @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 |
jsr166 |
1.4 |
/** |
197 |
jsr166 |
1.5 |
* Inserts the specified element as the last element of this |
198 |
dl |
1.1 |
* 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 |
dl |
1.2 |
* throwing an exception. This method is equivalent to |
203 |
dl |
1.3 |
* offerLast. |
204 |
dl |
1.1 |
* |
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 |
dl |
1.3 |
* This method is equivalent to takeFirst. |
217 |
dl |
1.1 |
* @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 |
dl |
1.2 |
* present on this deque. This method is equivalent to |
226 |
dl |
1.3 |
* pollFirst. |
227 |
dl |
1.1 |
* @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 |
|
|
} |