Java in a Nutshell, 5th Edition

Name

BlockingQueue<E>

Synopsis

This interface extends the java.util.Queue interface of the Java Collections Framework and adds blocking put( ) and take( ) methods. Blocking queues are useful in many concurrent algorithms in which a producer thread puts objects onto a queue and a consumer thread removes them for some kind of processing. The producer thread must block if a bounded queue fills up, and the consumer thread must block if no objects are available on the queue.

In addition to put( ) and take( ) methods that block indefinitely, BlockingQueue also defines timed versions of the Queue methods offer( ) and poll( ) that wait up to the specified time. The timeout is specified as both a long and a TimeUnit constant.

drainTo( ) removes all available elements from a BlockingQueue, adds them to the specified collection, and returns the number of elements removed from the queue. drainTo( ) does not block. A variant on this method puts an upper bound on the number of elements removed from the queue.

remainingCapacity( ) returns the number of elements that can be added to the queue before it becomes full or returns Integer.MAX_VALUE if the BlockingQueue is not a bounded queue. For bounded queues, this method provides a hint as to whether a call to put( ) will block.

BlockingQueue implementations are not allowed to accept null elements. The BlockingQueue interface refines the Collection.add( ) and Queue.offer( ) contracts to indicate that these methods throw NullPointerException if passed ...