BlockingQueues do 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. * *
BlockingQueues may be capacity bounded. At any given * time they may have a remainingCapacity beyond which no * additional elements can be put without blocking. * BlockingQueues without any intrinsic capacity constraints always * report Integer.MAX_VALUE remaining capacity. * *
While BlockingQueues are designed to be used primarily * as producer-consumer queues, they support 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; for example, * 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. * *
BlockingQueues do 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. Here is a sketch of a classic producer-consumer program. *
* 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 c = new Consumer(q);
* new Thread(p).start();
* new Thread(c).start();
* }
* }
*
*
*
* @since 1.5
* @spec JSR-166
* @revised $Date: 2003/05/28 23:00:40 $
* @editor $Author: dl $
*/
public interface BlockingQueue