Source code: edu/emory/mathcs/util/concurrent/BlockingQueue.java
1 /*
2 * Written by Doug Lea with assistance from members of JCP JSR-166
3 * Expert Group and released to the public domain. Use, modify, and
4 * redistribute this code in any way without acknowledgement.
5 */
6
7 package edu.emory.mathcs.util.concurrent;
8
9 import edu.emory.mathcs.util.*;
10
11 /**
12 * A {@link java.util.Queue} that additionally supports operations
13 * that wait for elements to exist when retrieving them, and wait for
14 * space to exist when putting them.
15 *
16 * <p> <tt>BlockingQueues</tt> do not accept <tt>null</tt> elements.
17 * Implementations throw <tt>IllegalArgumentException</tt> on attempts
18 * to <tt>add</tt>, <tt>put</tt> or <tt>offer</tt> a <tt>null</tt>. A
19 * <tt>null</tt> is used as a sentinel value to indicate failure of
20 * <tt>poll</tt> operations.
21 *
22 * <p><tt>BlockingQueues</tt> may be capacity bounded. At any given
23 * time they may have a <tt>remainingCapacity</tt> beyond which no
24 * additional elements can be <tt>put</tt> without blocking.
25 * BlockingQueues without any intrinsic capacity constraints always
26 * report a remaining capacity of <tt>Integer.MAX_VALUE</tt>.
27 *
28 * <p> While <tt>BlockingQueues</tt> are designed to be used primarily
29 * as producer-consumer queues, they additionally support the
30 * <tt>Collection</tt> interface. So, for example, it is possible to
31 * remove an arbitrary element from within a queue using
32 * <tt>remove(x)</tt>. However, such operations are in general
33 * <em>NOT</em> performed very efficiently, and are intended for only
34 * occasional use, such as when a queued message is cancelled. Also,
35 * the bulk operations, most notably <tt>addAll</tt> are <em>NOT</em>
36 * performed atomically, so it is possible for <tt>addAll(c)</tt> to
37 * fail (throwing an exception) after adding only some of the elements
38 * in <tt>c</tt>.
39 *
40 * <p><tt>BlockingQueue</tt>s do <em>not</em> intrinsically support
41 * any kind of "close" or "shutdown" operation to
42 * indicate that no more items will be added. The needs and usage of
43 * such features tend to be implementation-dependent. For example, a
44 * common tactic is for producers to insert special
45 * <em>end-of-stream</em> or <em>poison</em> objects, that are
46 * interpreted accordingly when taken by consumers.
47 *
48 * <p>
49 * Usage example, based on a typical producer-consumer scenario.
50 * Note that Blocking queues can safely be used with multiple producers
51 * and multiple consumers.
52 * <pre>
53 * class Producer implements Runnable {
54 * private final BlockingQueue queue;
55 * Producer(BlockingQueue q) { queue = q; }
56 * public void run() {
57 * try {
58 * while(true) { queue.put(produce()); }
59 * }
60 * catch (InterruptedException ex) { ... handle ...}
61 * }
62 * Object produce() { ... }
63 * }
64 *
65 * class Consumer implements Runnable {
66 * private final BlockingQueue queue;
67 * Concumer(BlockingQueue q) { queue = q; }
68 * public void run() {
69 * try {
70 * while(true) { consume(queue.take()); }
71 * }
72 * catch (InterruptedException ex) { ... handle ...}
73 * }
74 * void consume(Object x) { ... }
75 * }
76 *
77 * class Setup {
78 * void main() {
79 * BlockingQueue q = new SomeQueueImplementation();
80 * Producer p = new Producer(q);
81 * Consumer c1 = new Consumer(q);
82 * Consumer c2 = new Consumer(q);
83 * new Thread(p).start();
84 * new Thread(c1).start();
85 * new Thread(c2).start();
86 * }
87 * }
88 * </pre>
89 *
90 *
91 * @since 1.5
92 * @spec JSR-166
93 * @revised $Date: 2003/08/11 17:22:45 $
94 * @editor $Author: dawidk $
95 * @author Doug Lea
96 */
97 public interface BlockingQueue extends Queue {
98 /**
99 * Retrieve and remove the first element from the queue, waiting
100 * if no objects are present on the queue.
101 * @return the object
102 * @throws InterruptedException if interrupted while waiting.
103 */
104 Object take() throws InterruptedException;
105
106 /**
107 * Retrieve and remove the first element from the queue, waiting
108 * if necessary up to a specified wait time if no objects are
109 * present on the queue.
110 * @param timeout how long to wait before giving up, in units of
111 * <tt>unit</tt>
112 * @param unit a TimeUnit determining how to interpret the timeout
113 * parameter
114 * @return the object, or <tt>null</tt> if the specified waiting
115 * time elapses before an object is present.
116 * @throws InterruptedException if interrupted while waiting.
117 */
118 Object poll(long timeout, TimeUnit unit)
119 throws InterruptedException;
120
121 /**
122 * Add the given object to the queue, waiting if necessary for
123 * space to become available.
124 * @param x the object to add
125 * @throws InterruptedException if interrupted while waiting.
126 */
127 void put(Object x) throws InterruptedException;
128
129 /**
130 * Add the given object to the queue, waiting if necessary up to a
131 * specified wait time for space to become available.
132 * @param x the object to add
133 * @param timeout how long to wait before giving up, in units of
134 * <tt>unit</tt>
135 * @param unit a TimeUnit determining how to interpret the timeout
136 * parameter
137 * @return <tt>true</tt> if successful, or <tt>false</tt> if
138 * the specified waiting time elapses before space is available.
139 * @throws InterruptedException if interrupted while waiting.
140 */
141 boolean offer(Object x, long timeout, TimeUnit unit)
142 throws InterruptedException;
143
144 /**
145 * Return the number of elements that this queue can ideally (in
146 * the absence of memory or resource constraints) accept without
147 * blocking, or <tt>Integer.MAX_VALUE</tt> if there is no
148 * intrinsic limit. Note that you <em>cannot</em> always tell if
149 * an attempt to <tt>add</tt> an element will succeed by
150 * inspecting <tt>remainingCapacity</tt> because it may be the
151 * case that a waiting consumer is ready to <tt>take</tt> an
152 * element out of an otherwise full queue.
153 * @return the remaining capacity
154 */
155 int remainingCapacity();
156
157 }