36 package java.util.concurrent;
37
38 import java.util.Deque;
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 BORDER CELLPADDING=3 CELLSPACING=1>
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 addFirst(e)}</td>
71 * <td>{@link #offerFirst(Object) offerFirst(e)}</td>
72 * <td>{@link #putFirst 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>
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 BORDER CELLPADDING=3 CELLSPACING=1>
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>
|
36 package java.util.concurrent;
37
38 import java.util.Deque;
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 addFirst(e)}</td>
71 * <td>{@link #offerFirst(Object) offerFirst(e)}</td>
72 * <td>{@link #putFirst 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>
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>
|