ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/main/java/util/concurrent/BlockingQueue.java
Revision: 1.37
Committed: Tue May 17 04:17:31 2005 UTC (19 years ago) by jsr166
Branch: MAIN
Changes since 1.36: +136 -74 lines
Log Message: 
doc fixes

File Contents

# User Rev Content
1 dl 1.2 /*
2     * Written by Doug Lea with assistance from members of JCP JSR-166
3 dl 1.26 * Expert Group and released to the public domain, as explained at
4     * http://creativecommons.org/licenses/publicdomain
5 dl 1.2 */
6    
7 tim 1.1 package java.util.concurrent;
8 tim 1.9
9     import java.util.Collection;
10 tim 1.1 import java.util.Queue;
11    
12     /**
13 dl 1.4 * A {@link java.util.Queue} that additionally supports operations
14 dl 1.32 * that wait for the queue to become non-empty when retrieving an
15     * element, and wait for space to become available in the queue when
16 jsr166 1.37 * storing an element.
17     *
18     * <p><tt>BlockingQueue</tt> methods come in four forms, with different ways
19     * of handling operations that cannot be satisfied immediately, but may be
20     * satisfied at some point in the future:
21     * one throws an exception, the second returns a special value (either
22     * <tt>null</tt> or <tt>false</tt>, depending on the operation), the third
23     * blocks the current thread indefinitely until the operation can succeed,
24     * and the fourth blocks for only a given maximum time limit before giving
25     * up. These methods are summarized in the following table:
26 dl 1.31 *
27 jsr166 1.36 * <p>
28 dl 1.32 * <table BORDER CELLPADDING=3 CELLSPACING=1>
29 dl 1.31 * <tr>
30 dl 1.32 * <td></td>
31     * <td ALIGN=CENTER><em>Throws exception</em></td>
32 jsr166 1.37 * <td ALIGN=CENTER><em>Special value</em></td>
33 dl 1.32 * <td ALIGN=CENTER><em>Blocks</em></td>
34     * <td ALIGN=CENTER><em>Times out</em></td>
35 dl 1.31 * </tr>
36     * <tr>
37 dl 1.32 * <td><b>Insert</b></td>
38     * <td>{@link #add add(e)}</td>
39     * <td>{@link #offer offer(e)}</td>
40     * <td>{@link #put put(e)}</td>
41     * <td>{@link #offer(Object, long, TimeUnit) offer(e, time, unit)}</td>
42 dl 1.31 * </tr>
43     * <tr>
44 dl 1.32 * <td><b>Remove</b></td>
45     * <td>{@link #remove remove()}</td>
46     * <td>{@link #poll poll()}</td>
47     * <td>{@link #take take()}</td>
48     * <td>{@link #poll(long, TimeUnit) poll(time, unit)}</td>
49 dl 1.31 * </tr>
50     * <tr>
51 dl 1.32 * <td><b>Examine</b></td>
52     * <td>{@link #element element()}</td>
53     * <td>{@link #peek peek()}</td>
54     * <td><em>not applicable</em></td>
55     * <td><em>not applicable</em></td>
56 dl 1.31 * </tr>
57 dl 1.32 * </table>
58 dl 1.2 *
59 dholmes 1.7 * <p>A <tt>BlockingQueue</tt> does not accept <tt>null</tt> elements.
60 dholmes 1.10 * Implementations throw <tt>NullPointerException</tt> on attempts
61 dl 1.2 * to <tt>add</tt>, <tt>put</tt> or <tt>offer</tt> a <tt>null</tt>. A
62     * <tt>null</tt> is used as a sentinel value to indicate failure of
63     * <tt>poll</tt> operations.
64     *
65 dholmes 1.7 * <p>A <tt>BlockingQueue</tt> may be capacity bounded. At any given
66     * time it may have a <tt>remainingCapacity</tt> beyond which no
67 dl 1.2 * additional elements can be <tt>put</tt> without blocking.
68 dholmes 1.7 * A <tt>BlockingQueue</tt> without any intrinsic capacity constraints always
69     * reports a remaining capacity of <tt>Integer.MAX_VALUE</tt>.
70 dl 1.2 *
71 dl 1.29 * <p> <tt>BlockingQueue</tt> implementations are designed to be used
72     * primarily for producer-consumer queues, but additionally support
73     * the {@link java.util.Collection} interface. So, for example, it is
74     * possible to remove an arbitrary element from a queue using
75 dl 1.6 * <tt>remove(x)</tt>. However, such operations are in general
76 dl 1.18 * <em>not</em> performed very efficiently, and are intended for only
77 dl 1.29 * occasional use, such as when a queued message is cancelled.
78     *
79     * <p> <tt>BlockingQueue</tt> implementations are thread-safe. All
80     * queuing methods achieve their effects atomically using internal
81     * locks or other forms of concurrency control. However, the
82     * <em>bulk</em> Collection operations <tt>addAll</tt>,
83     * <tt>containsAll</tt>, <tt>retainAll</tt> and <tt>removeAll</tt> are
84     * <em>not</em> necessarily performed atomically unless specified
85     * otherwise in an implementation. So it is possible, for example, for
86     * <tt>addAll(c)</tt> to fail (throwing an exception) after adding
87 dl 1.18 * only some of the elements in <tt>c</tt>.
88 dl 1.2 *
89 dholmes 1.7 * <p>A <tt>BlockingQueue</tt> does <em>not</em> intrinsically support
90 dl 1.2 * any kind of &quot;close&quot; or &quot;shutdown&quot; operation to
91     * indicate that no more items will be added. The needs and usage of
92 brian 1.5 * such features tend to be implementation-dependent. For example, a
93 dl 1.2 * common tactic is for producers to insert special
94     * <em>end-of-stream</em> or <em>poison</em> objects, that are
95     * interpreted accordingly when taken by consumers.
96 tim 1.1 *
97     * <p>
98 brian 1.5 * Usage example, based on a typical producer-consumer scenario.
99 tim 1.9 * Note that a <tt>BlockingQueue</tt> can safely be used with multiple
100 dholmes 1.7 * producers and multiple consumers.
101 tim 1.1 * <pre>
102     * class Producer implements Runnable {
103     * private final BlockingQueue queue;
104     * Producer(BlockingQueue q) { queue = q; }
105     * public void run() {
106     * try {
107 jsr166 1.37 * while (true) { queue.put(produce()); }
108 tim 1.15 * } catch (InterruptedException ex) { ... handle ...}
109 tim 1.1 * }
110     * Object produce() { ... }
111     * }
112     *
113     * class Consumer implements Runnable {
114     * private final BlockingQueue queue;
115 dl 1.21 * Consumer(BlockingQueue q) { queue = q; }
116 tim 1.1 * public void run() {
117     * try {
118 jsr166 1.37 * while (true) { consume(queue.take()); }
119 tim 1.15 * } catch (InterruptedException ex) { ... handle ...}
120 tim 1.1 * }
121     * void consume(Object x) { ... }
122     * }
123     *
124     * class Setup {
125     * void main() {
126     * BlockingQueue q = new SomeQueueImplementation();
127     * Producer p = new Producer(q);
128 brian 1.5 * Consumer c1 = new Consumer(q);
129     * Consumer c2 = new Consumer(q);
130 tim 1.1 * new Thread(p).start();
131 brian 1.5 * new Thread(c1).start();
132     * new Thread(c2).start();
133 tim 1.1 * }
134     * }
135     * </pre>
136     *
137 dl 1.28 * <p>This interface is a member of the
138     * <a href="{@docRoot}/../guide/collections/index.html">
139     * Java Collections Framework</a>.
140 jsr166 1.33 *
141 tim 1.1 * @since 1.5
142 dl 1.6 * @author Doug Lea
143 dl 1.24 * @param <E> the type of elements held in this collection
144 tim 1.1 */
145     public interface BlockingQueue<E> extends Queue<E> {
146 jsr166 1.37 /**
147     * Inserts the specified element into this queue if it is possible to do
148     * so immediately without violating capacity restrictions, returning
149     * <tt>true</tt> upon success and throwing an
150     * <tt>IllegalStateException</tt> if no space is currently available.
151     * When using a capacity-restricted queue, it is generally preferable to
152     * use {@link #offer(Object) offer}.
153     *
154     * @param e the element to add
155     * @return <tt>true</tt> (as per the spec for {@link Collection#add})
156     * @throws IllegalStateException if the element cannot be added at this
157     * time due to capacity restrictions
158     * @throws ClassCastException if the class of the specified element
159     * prevents it from being added to this queue
160     * @throws NullPointerException if the specified element is null
161     * @throws IllegalArgumentException if some property of the specified
162     * element prevents it from being added to this queue
163     */
164     boolean add(E e);
165 dholmes 1.7
166     /**
167 jsr166 1.37 * Inserts the specified element into this queue if it is possible to do
168     * so immediately without violating capacity restrictions, returning
169     * <tt>true</tt> upon success and <tt>false</tt> if no space is currently
170     * available. When using a capacity-restricted queue, this method is
171     * generally preferable to {@link #add}, which can fail to insert an
172     * element only by throwing an exception.
173     *
174     * @param e the element to add
175     * @return <tt>true</tt> if the element was added to this queue, else
176     * <tt>false</tt>
177     * @throws ClassCastException if the class of the specified element
178     * prevents it from being added to this queue
179     * @throws NullPointerException if the specified element is null
180     * @throws IllegalArgumentException if some property of the specified
181     * element prevents it from being added to this queue
182 dholmes 1.7 */
183 jsr166 1.35 boolean offer(E e);
184 jsr166 1.33
185 tim 1.1 /**
186 dl 1.20 * Inserts the specified element into this queue, waiting if necessary
187 jsr166 1.37 * for space to become available.
188     *
189 jsr166 1.35 * @param e the element to add
190 jsr166 1.37 * @throws InterruptedException if interrupted while waiting
191     * @throws ClassCastException if the class of the specified element
192     * prevents it from being added to this queue
193     * @throws NullPointerException if the specified element is null
194     * @throws IllegalArgumentException if some property of the specified
195     * element prevents it from being added to this queue
196 tim 1.1 */
197 jsr166 1.37 void put(E e) throws InterruptedException;
198 tim 1.1
199     /**
200 jsr166 1.37 * Inserts the specified element into this queue, waiting up to the
201     * specified wait time if necessary for space to become available.
202     *
203     * @param e the element to add
204 dl 1.6 * @param timeout how long to wait before giving up, in units of
205 jsr166 1.37 * <tt>unit</tt>
206 tim 1.9 * @param unit a <tt>TimeUnit</tt> determining how to interpret the
207 jsr166 1.37 * <tt>timeout</tt> parameter
208     * @return <tt>true</tt> if successful, or <tt>false</tt> if
209     * the specified waiting time elapses before space is available
210     * @throws InterruptedException if interrupted while waiting
211     * @throws ClassCastException if the class of the specified element
212     * prevents it from being added to this queue
213     * @throws NullPointerException if the specified element is null
214     * @throws IllegalArgumentException if some property of the specified
215     * element prevents it from being added to this queue
216 tim 1.1 */
217 jsr166 1.37 boolean offer(E e, long timeout, TimeUnit unit)
218 tim 1.1 throws InterruptedException;
219    
220     /**
221 jsr166 1.37 * Retrieves and removes the head of this queue, waiting if necessary
222     * until an element becomes available.
223     *
224 dholmes 1.7 * @return the head of this queue
225 jsr166 1.37 * @throws InterruptedException if interrupted while waiting
226 tim 1.1 */
227 dholmes 1.7 E take() throws InterruptedException;
228    
229 tim 1.1 /**
230 jsr166 1.37 * Retrieves and removes the head of this queue, waiting up to the
231     * specified wait time if necessary for an element to become available.
232     *
233     * @param timeout how long to wait before giving up, in units of
234     * <tt>unit</tt>
235     * @param unit a <tt>TimeUnit</tt> determining how to interpret the
236     * <tt>timeout</tt> parameter
237     * @return the head of this queue, or <tt>null</tt> if the
238     * specified waiting time elapses before an element is available
239     * @throws InterruptedException if interrupted while waiting
240 tim 1.1 */
241 jsr166 1.37 E poll(long timeout, TimeUnit unit)
242     throws InterruptedException;
243 dholmes 1.7
244 dl 1.2 /**
245 jsr166 1.34 * Returns the number of additional elements that this queue can ideally
246     * (in the absence of memory or resource constraints) accept without
247     * blocking, or <tt>Integer.MAX_VALUE</tt> if there is no intrinsic
248     * limit.
249     *
250     * <p>Note that you <em>cannot</em> always tell if an attempt to insert
251     * an element will succeed by inspecting <tt>remainingCapacity</tt>
252     * because it may be the case that another thread is about to
253 jsr166 1.37 * insert or remove an element.
254 jsr166 1.34 *
255 dl 1.2 * @return the remaining capacity
256 dl 1.6 */
257     int remainingCapacity();
258 tim 1.1
259 dl 1.18 /**
260 jsr166 1.37 * Removes a single instance of the specified element from this queue,
261     * if it is present. More formally, removes an element <tt>e</tt> such
262     * that <tt>o.equals(e)</tt>, if this queue contains one or more such
263     * elements. Returns true if this queue contained the specified element
264     * (or equivalently, if this queue changed as a result of the call).
265 dl 1.18 *
266 jsr166 1.37 * @param o element to be removed from this queue, if present
267     * @return <tt>true</tt> if this queue changed as a result of the call
268     * @throws ClassCastException if the class of the specified element
269     * is incompatible with this queue (optional)
270     * @throws NullPointerException if the specified element is null (optional)
271 dl 1.18 */
272 jsr166 1.37 boolean remove(Object o);
273    
274     /**
275     * Returns <tt>true</tt> if this queue contains the specified element.
276     * More formally, returns <tt>true</tt> if and only if this queue contains
277     * at least one element <tt>e</tt> such that <tt>o.equals(e)</tt>.
278     *
279     * @param o object to be checked for containment in this queue
280     * @return <tt>true</tt> if this queue contains the specified element
281     * @throws ClassCastException if the class of the specified element
282     * is incompatible with this queue (optional)
283     * @throws NullPointerException if the specified element is null (optional)
284     */
285     public boolean contains(Object o);
286 dholmes 1.7
287 dl 1.18 /**
288 dl 1.22 * Removes all available elements from this queue and adds them
289 jsr166 1.37 * to the given collection. This operation may be more
290 dl 1.22 * efficient than repeatedly polling this queue. A failure
291 jsr166 1.37 * encountered while attempting to add elements to
292 dl 1.22 * collection <tt>c</tt> may result in elements being in neither,
293     * either or both collections when the associated exception is
294 jsr166 1.37 * thrown. Attempts to drain a queue to itself result in
295 dl 1.22 * <tt>IllegalArgumentException</tt>. Further, the behavior of
296     * this operation is undefined if the specified collection is
297     * modified while the operation is in progress.
298 dl 1.18 *
299 dl 1.22 * @param c the collection to transfer elements into
300 jsr166 1.37 * @return the number of elements transferred
301     * @throws UnsupportedOperationException if addition of elements
302     * is not supported by the specified collection
303     * @throws ClassCastException if the class of an element of this queue
304     * prevents it from being added to the specified collection
305     * @throws NullPointerException if the specified collection is null
306     * @throws IllegalArgumentException if the specified collection is this
307     * queue, or some property of an element of this queue prevents
308     * it from being added to the specified collection
309 dl 1.18 */
310 dl 1.22 int drainTo(Collection<? super E> c);
311 jsr166 1.33
312 dl 1.22 /**
313     * Removes at most the given number of available elements from
314 jsr166 1.37 * this queue and adds them to the given collection. A failure
315     * encountered while attempting to add elements to
316 dl 1.22 * collection <tt>c</tt> may result in elements being in neither,
317     * either or both collections when the associated exception is
318 jsr166 1.37 * thrown. Attempts to drain a queue to itself result in
319 dl 1.22 * <tt>IllegalArgumentException</tt>. Further, the behavior of
320     * this operation is undefined if the specified collection is
321     * modified while the operation is in progress.
322     *
323     * @param c the collection to transfer elements into
324     * @param maxElements the maximum number of elements to transfer
325 jsr166 1.37 * @return the number of elements transferred
326     * @throws UnsupportedOperationException if addition of elements
327     * is not supported by the specified collection
328     * @throws ClassCastException if the class of an element of this queue
329     * prevents it from being added to the specified collection
330     * @throws NullPointerException if the specified collection is null
331     * @throws IllegalArgumentException if the specified collection is this
332     * queue, or some property of an element of this queue prevents
333     * it from being added to the specified collection
334 dl 1.22 */
335     int drainTo(Collection<? super E> c, int maxElements);
336 dl 1.18 }