/* * Written by Doug Lea with assistance from members of JCP JSR-166 * Expert Group and released to the public domain. Use, modify, and * redistribute this code in any way without acknowledgement. */ package java.util.concurrent; import java.util.Queue; /** * A {@link java.util.Queue} that additionally supports operations * that wait for elements to exist when retrieving them, and wait for * space to exist when putting them. * *

A BlockingQueue does not accept null elements. * Implementations throw IllegalArgumentException on attempts * to add, put or offer a null. A * null is used as a sentinel value to indicate failure of * poll operations. * *

A BlockingQueue may be capacity bounded. At any given * time it may have a remainingCapacity beyond which no * additional elements can be put without blocking. * A BlockingQueue without any intrinsic capacity constraints always * reports a remaining capacity of Integer.MAX_VALUE. * *

While BlockingQueue is designed to be used primarily * as for producer-consumer queues, it additionally supports the * Collection interface. So, for example, it is possible to * remove an arbitrary element from within a queue using * remove(x). However, such operations are in general * NOT performed very efficiently, and are intended for only * occasional use, such as when a queued message is cancelled. Also, * the bulk operations, most notably addAll are NOT * performed atomically, so it is possible for addAll(c) to * fail (throwing an exception) after adding only some of the elements * in c. * *

A BlockingQueue does not intrinsically support * any kind of "close" or "shutdown" operation to * indicate that no more items will be added. The needs and usage of * such features tend to be implementation-dependent. For example, a * common tactic is for producers to insert special * end-of-stream or poison objects, that are * interpreted accordingly when taken by consumers. * *

* Usage example, based on a typical producer-consumer scenario. * Note that a BlockingQueue can safely be used with multiple * producers and multiple consumers. * 

 * class Producer implements Runnable {
 *   private final BlockingQueue queue;
 *   Producer(BlockingQueue q) { queue = q; }
 *   public void run() {
 *     try {
 *       while(true) { queue.put(produce()); }
 *     }
 *     catch (InterruptedException ex) { ... handle ...}
 *   }
 *   Object produce() { ... }
 * }
 *
 * class Consumer implements Runnable {
 *   private final BlockingQueue queue;
 *   Concumer(BlockingQueue q) { queue = q; }
 *   public void run() {
 *     try {
 *       while(true) { consume(queue.take()); }
 *     }
 *     catch (InterruptedException ex) { ... handle ...}
 *   }
 *   void consume(Object x) { ... }
 * }
 *
 * class Setup {
 *   void main() {
 *     BlockingQueue q = new SomeQueueImplementation();
 *     Producer p = new Producer(q);
 *     Consumer c1 = new Consumer(q);
 *     Consumer c2 = new Consumer(q);
 *     new Thread(p).start();
 *     new Thread(c1).start();
 *     new Thread(c2).start();
 *   }
 * }
 *
* * * @since 1.5 * @spec JSR-166 * @revised $Date: 2003/07/28 04:11:54 $ * @editor $Author: dholmes $ * @author Doug Lea */ public interface BlockingQueue extends Queue { /** * @throws IllegalStateException if this queue is full * @throws NullPointerException if x is null. */ boolean add(E x); /** * @throws IllegalStateException if this queue is full * @throws NullPointerException if x is null. */ boolean addAll(Collection c); /** * @throws NullPointerException if x is null. */ public boolean offer(E x); /** * Add the specified element to this queue, waiting if necessary up to the * specified wait time for space to become available. * @param x the element to add * @param timeout how long to wait before giving up, in units of * unit * @param unit a TimeUnit determining how to interpret the * timeout parameter * @return true if successful, or false if * the specified waiting time elapses before space is available. * @throws InterruptedException if interrupted while waiting. * @throws NullPointerException if x is null. */ boolean offer(E x, long timeout, TimeUnit unit) throws InterruptedException; /** * Retrieve and remove the head of this queue, waiting * if necessary up to the specified wait time if no elements are * present on this queue. * @param timeout how long to wait before giving up, in units of * unit * @param unit a TimeUnit determining how to interpret the * timeout parameter * @return the head of this queue, or null if the * specified waiting time elapses before an element is present. * @throws InterruptedException if interrupted while waiting. */ E poll(long timeout, TimeUnit unit) throws InterruptedException; /** * Retrieve and remove the head of this queue, waiting * if no elements are present on this queue. * @return the head of this queue * @throws InterruptedException if interrupted while waiting. */ E take() throws InterruptedException; /** * Add the specified element to this queue, waiting if necessary for * space to become available. * @param x the element to add * @throws InterruptedException if interrupted while waiting. * @throws NullPointerException if x is null. */ void put(E x) throws InterruptedException; /** * Return the number of elements that this queue can ideally (in * the absence of memory or resource constraints) accept without * blocking, or Integer.MAX_VALUE if there is no * intrinsic limit. *

Note that you cannot always tell if * an attempt to add an element will succeed by * inspecting remainingCapacity because it may be the * case that a waiting consumer is ready to take an * element out of an otherwise full queue. * @return the remaining capacity */ int remainingCapacity(); }