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 /* |