| 1 |
/* |
| 2 |
* Written by Doug Lea with assistance from members of JCP JSR-166 |
| 3 |
* Expert Group and released to the public domain, as explained at |
| 4 |
* http://creativecommons.org/licenses/publicdomain |
| 5 |
*/ |
| 6 |
|
| 7 |
package java.util.concurrent; |
| 8 |
|
| 9 |
import java.util.Collection; |
| 10 |
import java.util.Queue; |
| 11 |
|
| 12 |
/** |
| 13 |
* A {@link java.util.Queue} that additionally supports operations |
| 14 |
* 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 |
* 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 |
* |
| 27 |
* <p> |
| 28 |
* <table BORDER CELLPADDING=3 CELLSPACING=1> |
| 29 |
* <tr> |
| 30 |
* <td></td> |
| 31 |
* <td ALIGN=CENTER><em>Throws exception</em></td> |
| 32 |
* <td ALIGN=CENTER><em>Special value</em></td> |
| 33 |
* <td ALIGN=CENTER><em>Blocks</em></td> |
| 34 |
* <td ALIGN=CENTER><em>Times out</em></td> |
| 35 |
* </tr> |
| 36 |
* <tr> |
| 37 |
* <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 |
* </tr> |
| 43 |
* <tr> |
| 44 |
* <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 |
* </tr> |
| 50 |
* <tr> |
| 51 |
* <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 |
* </tr> |
| 57 |
* </table> |
| 58 |
* |
| 59 |
* <p>A <tt>BlockingQueue</tt> does not accept <tt>null</tt> elements. |
| 60 |
* Implementations throw <tt>NullPointerException</tt> on attempts |
| 61 |
* 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 |
* <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 |
* additional elements can be <tt>put</tt> without blocking. |
| 68 |
* A <tt>BlockingQueue</tt> without any intrinsic capacity constraints always |
| 69 |
* reports a remaining capacity of <tt>Integer.MAX_VALUE</tt>. |
| 70 |
* |
| 71 |
* <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 |
* <tt>remove(x)</tt>. However, such operations are in general |
| 76 |
* <em>not</em> performed very efficiently, and are intended for only |
| 77 |
* 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 |
* only some of the elements in <tt>c</tt>. |
| 88 |
* |
| 89 |
* <p>A <tt>BlockingQueue</tt> does <em>not</em> intrinsically support |
| 90 |
* any kind of "close" or "shutdown" operation to |
| 91 |
* indicate that no more items will be added. The needs and usage of |
| 92 |
* such features tend to be implementation-dependent. For example, a |
| 93 |
* 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 |
* |
| 97 |
* <p> |
| 98 |
* Usage example, based on a typical producer-consumer scenario. |
| 99 |
* Note that a <tt>BlockingQueue</tt> can safely be used with multiple |
| 100 |
* producers and multiple consumers. |
| 101 |
* <pre> |
| 102 |
* class Producer implements Runnable { |
| 103 |
* private final BlockingQueue queue; |
| 104 |
* Producer(BlockingQueue q) { queue = q; } |
| 105 |
* public void run() { |
| 106 |
* try { |
| 107 |
* while (true) { queue.put(produce()); } |
| 108 |
* } catch (InterruptedException ex) { ... handle ...} |
| 109 |
* } |
| 110 |
* Object produce() { ... } |
| 111 |
* } |
| 112 |
* |
| 113 |
* class Consumer implements Runnable { |
| 114 |
* private final BlockingQueue queue; |
| 115 |
* Consumer(BlockingQueue q) { queue = q; } |
| 116 |
* public void run() { |
| 117 |
* try { |
| 118 |
* while (true) { consume(queue.take()); } |
| 119 |
* } catch (InterruptedException ex) { ... handle ...} |
| 120 |
* } |
| 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 |
* Consumer c1 = new Consumer(q); |
| 129 |
* Consumer c2 = new Consumer(q); |
| 130 |
* new Thread(p).start(); |
| 131 |
* new Thread(c1).start(); |
| 132 |
* new Thread(c2).start(); |
| 133 |
* } |
| 134 |
* } |
| 135 |
* </pre> |
| 136 |
* |
| 137 |
* <p>This interface is a member of the |
| 138 |
* <a href="{@docRoot}/../guide/collections/index.html"> |
| 139 |
* Java Collections Framework</a>. |
| 140 |
* |
| 141 |
* @since 1.5 |
| 142 |
* @author Doug Lea |
| 143 |
* @param <E> the type of elements held in this collection |
| 144 |
*/ |
| 145 |
public interface BlockingQueue<E> extends Queue<E> { |
| 146 |
/** |
| 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 |
|
| 166 |
/** |
| 167 |
* 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 |
*/ |
| 183 |
boolean offer(E e); |
| 184 |
|
| 185 |
/** |
| 186 |
* Inserts the specified element into this queue, waiting if necessary |
| 187 |
* for space to become available. |
| 188 |
* |
| 189 |
* @param e the element to add |
| 190 |
* @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 |
*/ |
| 197 |
void put(E e) throws InterruptedException; |
| 198 |
|
| 199 |
/** |
| 200 |
* 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 |
* @param timeout how long to wait before giving up, in units of |
| 205 |
* <tt>unit</tt> |
| 206 |
* @param unit a <tt>TimeUnit</tt> determining how to interpret the |
| 207 |
* <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 |
*/ |
| 217 |
boolean offer(E e, long timeout, TimeUnit unit) |
| 218 |
throws InterruptedException; |
| 219 |
|
| 220 |
/** |
| 221 |
* Retrieves and removes the head of this queue, waiting if necessary |
| 222 |
* until an element becomes available. |
| 223 |
* |
| 224 |
* @return the head of this queue |
| 225 |
* @throws InterruptedException if interrupted while waiting |
| 226 |
*/ |
| 227 |
E take() throws InterruptedException; |
| 228 |
|
| 229 |
/** |
| 230 |
* 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 |
*/ |
| 241 |
E poll(long timeout, TimeUnit unit) |
| 242 |
throws InterruptedException; |
| 243 |
|
| 244 |
/** |
| 245 |
* 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 |
* insert or remove an element. |
| 254 |
* |
| 255 |
* @return the remaining capacity |
| 256 |
*/ |
| 257 |
int remainingCapacity(); |
| 258 |
|
| 259 |
/** |
| 260 |
* 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 |
* |
| 266 |
* @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 |
*/ |
| 272 |
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 |
|
| 287 |
/** |
| 288 |
* Removes all available elements from this queue and adds them |
| 289 |
* to the given collection. This operation may be more |
| 290 |
* efficient than repeatedly polling this queue. A failure |
| 291 |
* encountered while attempting to add elements to |
| 292 |
* collection <tt>c</tt> may result in elements being in neither, |
| 293 |
* either or both collections when the associated exception is |
| 294 |
* thrown. Attempts to drain a queue to itself result in |
| 295 |
* <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 |
* |
| 299 |
* @param c the collection to transfer elements into |
| 300 |
* @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 |
*/ |
| 310 |
int drainTo(Collection<? super E> c); |
| 311 |
|
| 312 |
/** |
| 313 |
* Removes at most the given number of available elements from |
| 314 |
* this queue and adds them to the given collection. A failure |
| 315 |
* encountered while attempting to add elements to |
| 316 |
* collection <tt>c</tt> may result in elements being in neither, |
| 317 |
* either or both collections when the associated exception is |
| 318 |
* thrown. Attempts to drain a queue to itself result in |
| 319 |
* <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 |
* @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 |
*/ |
| 335 |
int drainTo(Collection<? super E> c, int maxElements); |
| 336 |
} |
