/* * 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.Collection; 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 storing them. * *

A BlockingQueue does not accept null elements. * Implementations throw NullPointerException 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 * for producer-consumer queues, it additionally supports the {@link * java.util.Collection} interface. So, for example, it is possible * to remove an arbitrary element from 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 * necessarily 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;
 *   Consumer(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 * @author Doug Lea */ public interface BlockingQueue extends Queue { /** * Inserts the specified element into this queue, if possible. When * using queues that may impose insertion restrictions (for * example capacity bounds), method offer is generally * preferable to method {@link Collection#add}, which can fail to * insert an element only by throwing an exception. * * @param o the element to add. * @return true if it was possible to add the element to * this queue, else false * @throws NullPointerException if the specified element is null */ boolean offer(E o); /** * Inserts the specified element into this queue, waiting if necessary * up to the specified wait time for space to become available. * @param o 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 the specified element is null. */ boolean offer(E o, long timeout, TimeUnit unit) throws InterruptedException; /** * Retrieves and removes 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; /** * Retrieves and removes 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; /** * Adds the specified element to this queue, waiting if necessary for * space to become available. * @param o the element to add * @throws InterruptedException if interrupted while waiting. * @throws NullPointerException if the specified element is null. */ void put(E o) throws InterruptedException; /** * Returns 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(); /** * Adds the specified element to this queue if it is possible to * do so immediately, returning true upon success, else * throwing an IllegalStateException. * @param o the element * @return true (as per the general contract of * Collection.add). * * @throws NullPointerException if the specified element is null * @throws IllegalStateException if element cannot be added */ boolean add(E o); /** * Adds all of the elements in the specified collection to this * queue if it is possible to do so. The behavior of this * operation need not be atomic; a failure may occur after * adding only some elements. * * @param c collection whose elements are to be added to this queue * @return true if this queue changed as a result of the * call. * @throws NullPointerException if c or any element in c * is null * @throws IllegalStateException if any element cannot be added. * */ boolean addAll(Collection c); }