39 import java.util.Iterator;
40 import java.util.NoSuchElementException;
41
42 /**
43 * A {@link Deque} that additionally supports blocking operations that wait
44 * for the deque to become non-empty when retrieving an element, and wait for
45 * space to become available in the deque when storing an element.
46 *
47 * <p>{@code BlockingDeque} methods come in four forms, with different ways
48 * of handling operations that cannot be satisfied immediately, but may be
49 * satisfied at some point in the future:
50 * one throws an exception, the second returns a special value (either
51 * {@code null} or {@code false}, depending on the operation), the third
52 * blocks the current thread indefinitely until the operation can succeed,
53 * and the fourth blocks for only a given maximum time limit before giving
54 * up. These methods are summarized in the following table:
55 *
56 * <table class="plain">
57 * <caption>Summary of BlockingDeque methods</caption>
58 * <tr>
59 * <td style="text-align:center" COLSPAN = 5> <b>First Element (Head)</b></td>
60 * </tr>
61 * <tr>
62 * <td></td>
63 * <td style="text-align:center"><em>Throws exception</em></td>
64 * <td style="text-align:center"><em>Special value</em></td>
65 * <td style="text-align:center"><em>Blocks</em></td>
66 * <td style="text-align:center"><em>Times out</em></td>
67 * </tr>
68 * <tr>
69 * <td><b>Insert</b></td>
70 * <td>{@link #addFirst(Object) addFirst(e)}</td>
71 * <td>{@link #offerFirst(Object) offerFirst(e)}</td>
72 * <td>{@link #putFirst(Object) putFirst(e)}</td>
73 * <td>{@link #offerFirst(Object, long, TimeUnit) offerFirst(e, time, unit)}</td>
74 * </tr>
75 * <tr>
76 * <td><b>Remove</b></td>
77 * <td>{@link #removeFirst() removeFirst()}</td>
78 * <td>{@link #pollFirst() pollFirst()}</td>
79 * <td>{@link #takeFirst() takeFirst()}</td>
80 * <td>{@link #pollFirst(long, TimeUnit) pollFirst(time, unit)}</td>
81 * </tr>
82 * <tr>
83 * <td><b>Examine</b></td>
84 * <td>{@link #getFirst() getFirst()}</td>
85 * <td>{@link #peekFirst() peekFirst()}</td>
86 * <td><em>not applicable</em></td>
87 * <td><em>not applicable</em></td>
88 * </tr>
89 * <tr>
90 * <td style="text-align:center" COLSPAN = 5> <b>Last Element (Tail)</b></td>
91 * </tr>
92 * <tr>
93 * <td></td>
94 * <td style="text-align:center"><em>Throws exception</em></td>
95 * <td style="text-align:center"><em>Special value</em></td>
96 * <td style="text-align:center"><em>Blocks</em></td>
97 * <td style="text-align:center"><em>Times out</em></td>
98 * </tr>
99 * <tr>
100 * <td><b>Insert</b></td>
101 * <td>{@link #addLast(Object) addLast(e)}</td>
102 * <td>{@link #offerLast(Object) offerLast(e)}</td>
103 * <td>{@link #putLast(Object) putLast(e)}</td>
104 * <td>{@link #offerLast(Object, long, TimeUnit) offerLast(e, time, unit)}</td>
105 * </tr>
106 * <tr>
107 * <td><b>Remove</b></td>
108 * <td>{@link #removeLast() removeLast()}</td>
109 * <td>{@link #pollLast() pollLast()}</td>
110 * <td>{@link #takeLast() takeLast()}</td>
111 * <td>{@link #pollLast(long, TimeUnit) pollLast(time, unit)}</td>
112 * </tr>
113 * <tr>
114 * <td><b>Examine</b></td>
115 * <td>{@link #getLast() getLast()}</td>
116 * <td>{@link #peekLast() peekLast()}</td>
117 * <td><em>not applicable</em></td>
118 * <td><em>not applicable</em></td>
119 * </tr>
120 * </table>
121 *
122 * <p>Like any {@link BlockingQueue}, a {@code BlockingDeque} is thread safe,
123 * does not permit null elements, and may (or may not) be
124 * capacity-constrained.
125 *
126 * <p>A {@code BlockingDeque} implementation may be used directly as a FIFO
127 * {@code BlockingQueue}. The methods inherited from the
128 * {@code BlockingQueue} interface are precisely equivalent to
129 * {@code BlockingDeque} methods as indicated in the following table:
130 *
131 * <table class="plain">
132 * <caption>Comparison of BlockingQueue and BlockingDeque methods</caption>
133 * <tr>
134 * <td style="text-align:center"> <b>{@code BlockingQueue} Method</b></td>
135 * <td style="text-align:center"> <b>Equivalent {@code BlockingDeque} Method</b></td>
136 * </tr>
137 * <tr>
138 * <td style="text-align:center" COLSPAN = 2> <b>Insert</b></td>
139 * </tr>
140 * <tr>
141 * <td>{@link #add(Object) add(e)}</td>
142 * <td>{@link #addLast(Object) addLast(e)}</td>
143 * </tr>
144 * <tr>
145 * <td>{@link #offer(Object) offer(e)}</td>
146 * <td>{@link #offerLast(Object) offerLast(e)}</td>
147 * </tr>
148 * <tr>
149 * <td>{@link #put(Object) put(e)}</td>
150 * <td>{@link #putLast(Object) putLast(e)}</td>
151 * </tr>
152 * <tr>
153 * <td>{@link #offer(Object, long, TimeUnit) offer(e, time, unit)}</td>
154 * <td>{@link #offerLast(Object, long, TimeUnit) offerLast(e, time, unit)}</td>
155 * </tr>
156 * <tr>
157 * <td style="text-align:center" COLSPAN = 2> <b>Remove</b></td>
158 * </tr>
159 * <tr>
160 * <td>{@link #remove() remove()}</td>
161 * <td>{@link #removeFirst() removeFirst()}</td>
162 * </tr>
163 * <tr>
164 * <td>{@link #poll() poll()}</td>
165 * <td>{@link #pollFirst() pollFirst()}</td>
166 * </tr>
167 * <tr>
168 * <td>{@link #take() take()}</td>
169 * <td>{@link #takeFirst() takeFirst()}</td>
170 * </tr>
171 * <tr>
172 * <td>{@link #poll(long, TimeUnit) poll(time, unit)}</td>
173 * <td>{@link #pollFirst(long, TimeUnit) pollFirst(time, unit)}</td>
174 * </tr>
175 * <tr>
176 * <td style="text-align:center" COLSPAN = 2> <b>Examine</b></td>
177 * </tr>
178 * <tr>
179 * <td>{@link #element() element()}</td>
180 * <td>{@link #getFirst() getFirst()}</td>
181 * </tr>
182 * <tr>
183 * <td>{@link #peek() peek()}</td>
184 * <td>{@link #peekFirst() peekFirst()}</td>
185 * </tr>
186 * </table>
187 *
188 * <p>Memory consistency effects: As with other concurrent
189 * collections, actions in a thread prior to placing an object into a
190 * {@code BlockingDeque}
191 * <a href="package-summary.html#MemoryVisibility"><i>happen-before</i></a>
192 * actions subsequent to the access or removal of that element from
193 * the {@code BlockingDeque} in another thread.
194 *
195 * <p>This interface is a member of the
196 * <a href="{@docRoot}/java/util/package-summary.html#CollectionsFramework">
197 * Java Collections Framework</a>.
198 *
199 * @since 1.6
200 * @author Doug Lea
201 * @param <E> the type of elements held in this deque
202 */
203 public interface BlockingDeque<E> extends BlockingQueue<E>, Deque<E> {
204 /*
|
39 import java.util.Iterator;
40 import java.util.NoSuchElementException;
41
42 /**
43 * A {@link Deque} that additionally supports blocking operations that wait
44 * for the deque to become non-empty when retrieving an element, and wait for
45 * space to become available in the deque when storing an element.
46 *
47 * <p>{@code BlockingDeque} methods come in four forms, with different ways
48 * of handling operations that cannot be satisfied immediately, but may be
49 * satisfied at some point in the future:
50 * one throws an exception, the second returns a special value (either
51 * {@code null} or {@code false}, depending on the operation), the third
52 * blocks the current thread indefinitely until the operation can succeed,
53 * and the fourth blocks for only a given maximum time limit before giving
54 * up. These methods are summarized in the following table:
55 *
56 * <table class="plain">
57 * <caption>Summary of BlockingDeque methods</caption>
58 * <tr>
59 * <th id="First" colspan="5"> <b>First Element (Head)</b></th>
60 * </tr>
61 * <tr>
62 * <td></td>
63 * <th id="FThrow" style="font-weight:normal; font-style: italic">Throws exception</th>
64 * <th id="FValue" style="font-weight:normal; font-style: italic">Special value</th>
65 * <th id="FBlock" style="font-weight:normal; font-style: italic">Blocks</th>
66 * <th id="FTimes" style="font-weight:normal; font-style: italic">Times out</th>
67 * </tr>
68 * <tr>
69 * <th id="FInsert" style="text-align:left">Insert</th>
70 * <td headers="First FInsert FThrow">{@link #addFirst(Object) addFirst(e)}</td>
71 * <td headers="First FInsert FValue">{@link #offerFirst(Object) offerFirst(e)}</td>
72 * <td headers="First FInsert FBlock">{@link #putFirst(Object) putFirst(e)}</td>
73 * <td headers="First FInsert FTimes">{@link #offerFirst(Object, long, TimeUnit) offerFirst(e, time, unit)}</td>
74 * </tr>
75 * <tr>
76 * <th id="FRemove" style="text-align:left">Remove</th>
77 * <td headers="First FRemove FThrow">{@link #removeFirst() removeFirst()}</td>
78 * <td headers="First FRemove FValue">{@link #pollFirst() pollFirst()}</td>
79 * <td headers="First FRemove FBlock">{@link #takeFirst() takeFirst()}</td>
80 * <td headers="First FRemove FTimes">{@link #pollFirst(long, TimeUnit) pollFirst(time, unit)}</td>
81 * </tr>
82 * <tr>
83 * <th id="FExamine" style="text-align:left">Examine</th>
84 * <td headers="First FExamine FThrow">{@link #getFirst() getFirst()}</td>
85 * <td headers="First FExamine FValue">{@link #peekFirst() peekFirst()}</td>
86 * <td headers="First FExamine FBlock" style="font-style:italic">not applicable</td>
87 * <td headers="First FExamine FTimes" style="font-style:italic">not applicable</td>
88 * </tr>
89 * <tr>
90 * <th id="Last" colspan="5"> <b>Last Element (Tail)</b></th>
91 * </tr>
92 * <tr>
93 * <td></td>
94 * <th id="LThrow" style="font-weight:normal; font-style: italic">Throws exception</th>
95 * <th id="LValue" style="font-weight:normal; font-style: italic">Special value</th>
96 * <th id="LBlock" style="font-weight:normal; font-style: italic">Blocks</th>
97 * <th id="LTimes" style="font-weight:normal; font-style: italic">Times out</th>
98 * </tr>
99 * <tr>
100 * <th id="LInsert" style="text-align:left">Insert</th>
101 * <td headers="Last LInsert LThrow">{@link #addLast(Object) addLast(e)}</td>
102 * <td headers="Last LInsert LValue">{@link #offerLast(Object) offerLast(e)}</td>
103 * <td headers="Last LInsert LBlock">{@link #putLast(Object) putLast(e)}</td>
104 * <td headers="Last LInsert LTimes">{@link #offerLast(Object, long, TimeUnit) offerLast(e, time, unit)}</td>
105 * </tr>
106 * <tr>
107 * <th id="LRemove" style="text-align:left">Remove</th>
108 * <td headers="Last LRemove LThrow">{@link #removeLast() removeLast()}</td>
109 * <td headers="Last LRemove LValue">{@link #pollLast() pollLast()}</td>
110 * <td headers="Last LRemove LBlock">{@link #takeLast() takeLast()}</td>
111 * <td headers="Last LRemove LTimes">{@link #pollLast(long, TimeUnit) pollLast(time, unit)}</td>
112 * </tr>
113 * <tr>
114 * <th id="LExamine" style="text-align:left">Examine</th>
115 * <td headers="Last LExamine LThrow">{@link #getLast() getLast()}</td>
116 * <td headers="Last LExamine LValue">{@link #peekLast() peekLast()}</td>
117 * <td headers="Last LExamine LBlock" style="font-style:italic">not applicable</td>
118 * <td headers="Last LExamine LTimes" style="font-style:italic">not applicable</td>
119 * </tr>
120 * </table>
121 *
122 * <p>Like any {@link BlockingQueue}, a {@code BlockingDeque} is thread safe,
123 * does not permit null elements, and may (or may not) be
124 * capacity-constrained.
125 *
126 * <p>A {@code BlockingDeque} implementation may be used directly as a FIFO
127 * {@code BlockingQueue}. The methods inherited from the
128 * {@code BlockingQueue} interface are precisely equivalent to
129 * {@code BlockingDeque} methods as indicated in the following table:
130 *
131 * <table class="plain">
132 * <caption>Comparison of BlockingQueue and BlockingDeque methods</caption>
133 * <tr>
134 * <td></td>
135 * <th id="BQueue"> {@code BlockingQueue} Method</th>
136 * <th id="BDeque"> Equivalent {@code BlockingDeque} Method</th>
137 * </tr>
138 * <tr>
139 * <th id="Insert" rowspan="4" style="text-align:left; vertical-align:top">Insert</th>
140 * <th id="add" style="font-weight:normal; text-align:left">{@link #add(Object) add(e)}</th>
141 * <td headers="Insert BDeque add">{@link #addLast(Object) addLast(e)}</td>
142 * </tr>
143 * <tr>
144 * <th id="offer1" style="font-weight:normal; text-align:left">{@link #offer(Object) offer(e)}</th>
145 * <td headers="Insert BDeque offer1">{@link #offerLast(Object) offerLast(e)}</td>
146 * </tr>
147 * <tr>
148 * <th id="put" style="font-weight:normal; text-align:left">{@link #put(Object) put(e)}</th>
149 * <td headers="Insert BDeque put">{@link #putLast(Object) putLast(e)}</td>
150 * </tr>
151 * <tr>
152 * <th id="offer2" style="font-weight:normal; text-align:left">{@link #offer(Object, long, TimeUnit) offer(e, time, unit)}</th>
153 * <td headers="Insert BDeque offer2">{@link #offerLast(Object, long, TimeUnit) offerLast(e, time, unit)}</td>
154 * </tr>
155 * <tr>
156 * <th id="Remove" rowspan="4" style="text-align:left; vertical-align:top">Remove</th>
157 * <th id="remove" style="font-weight:normal; text-align:left">{@link #remove() remove()}</th>
158 * <td headers="Remove BDeque remove">{@link #removeFirst() removeFirst()}</td>
159 * </tr>
160 * <tr>
161 * <th id="poll1" style="font-weight:normal; text-align:left">{@link #poll() poll()}</th>
162 * <td headers="Remove BDeque poll1">{@link #pollFirst() pollFirst()}</td>
163 * </tr>
164 * <tr>
165 * <th id="take" style="font-weight:normal; text-align:left">{@link #take() take()}</th>
166 * <td headers="Remove BDeque take">{@link #takeFirst() takeFirst()}</td>
167 * </tr>
168 * <tr>
169 * <th id="poll2" style="font-weight:normal; text-align:left">{@link #poll(long, TimeUnit) poll(time, unit)}</th>
170 * <td headers="Remove BDeque poll2">{@link #pollFirst(long, TimeUnit) pollFirst(time, unit)}</td>
171 * </tr>
172 * <tr>
173 * <th id="Examine" rowspan="2" style="text-align:left; vertical-align:top">Examine</th>
174 * <th id="element" style="font-weight:normal; text-align:left">{@link #element() element()}</th>
175 * <td headers="Examine BDeque element">{@link #getFirst() getFirst()}</td>
176 * </tr>
177 * <tr>
178 * <th id="peek" style="font-weight:normal; text-align:left">{@link #peek() peek()}</th>
179 * <td headers="Examine BDeque peek">{@link #peekFirst() peekFirst()}</td>
180 * </tr>
181 * </table>
182 *
183 * <p>Memory consistency effects: As with other concurrent
184 * collections, actions in a thread prior to placing an object into a
185 * {@code BlockingDeque}
186 * <a href="package-summary.html#MemoryVisibility"><i>happen-before</i></a>
187 * actions subsequent to the access or removal of that element from
188 * the {@code BlockingDeque} in another thread.
189 *
190 * <p>This interface is a member of the
191 * <a href="{@docRoot}/java/util/package-summary.html#CollectionsFramework">
192 * Java Collections Framework</a>.
193 *
194 * @since 1.6
195 * @author Doug Lea
196 * @param <E> the type of elements held in this deque
197 */
198 public interface BlockingDeque<E> extends BlockingQueue<E>, Deque<E> {
199 /*
|