BlockingQueue

Overview

Package

Class

Use

Deprecated

Index

Home >> All >> edu >> emory >> mathcs >> util >> [ concurrent overview ]

PREV CLASS NEXT CLASS

SUMMARY:

JAVADOC |

Sourc code of edu.emory.mathcs.util.concurrent.BlockingQueue

SOURCE |

Download edu.emory.mathcs.util.concurrent.BlockingQueue

DOWNLOAD | NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

edu.emory.mathcs.util.concurrent
Interface BlockingQueue

All Superinterfaces:: java.util.Collection, edu.emory.mathcs.util.Queue

All Known Implementing Classes:: BoundedLinkedQueue, DynamicArrayBlockingQueue, SynchronousQueue

public interface BlockingQueue
extends edu.emory.mathcs.util.Queue

A 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.

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 a remaining capacity of Integer.MAX_VALUE.

While BlockingQueues are designed to be used primarily as producer-consumer queues, they additionally 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, 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.

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, based on a typical producer-consumer scenario. Note that Blocking queues 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

Method Summary

boolean offer(java.lang.Object x, long timeout, TimeUnit unit)
          Add the given object to the queue, waiting if necessary up to a specified wait time for space to become available.

java.lang.Object poll(long timeout, TimeUnit unit)
          Retrieve and remove the first element from the queue, waiting if necessary up to a specified wait time if no objects are present on the queue.

void put(java.lang.Object x)
          Add the given object to the queue, waiting if necessary for space to become available.

int remainingCapacity()
          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.

java.lang.Object take()
          Retrieve and remove the first element from the queue, waiting if no objects are present on the queue.

Methods inherited from interface edu.emory.mathcs.util.Queue

element, offer, peek, poll, remove

Methods inherited from interface java.util.Collection

add, addAll, clear, contains, containsAll, equals, hashCode, isEmpty, iterator, remove, removeAll, retainAll, size, toArray, toArray

Method Detail

take

public java.lang.Object take()
                      throws java.lang.InterruptedException

Retrieve and remove the first element from the queue, waiting if no objects are present on the queue.

poll

public java.lang.Object poll(long timeout,
                             TimeUnit unit)
                      throws java.lang.InterruptedException

Retrieve and remove the first element from the queue, waiting if necessary up to a specified wait time if no objects are present on the queue.

put

public void put(java.lang.Object x)
         throws java.lang.InterruptedException

Add the given object to the queue, waiting if necessary for space to become available.

offer

public boolean offer(java.lang.Object x,
                     long timeout,
                     TimeUnit unit)
              throws java.lang.InterruptedException

Add the given object to the queue, waiting if necessary up to a specified wait time for space to become available.

remainingCapacity

public int remainingCapacity()

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.