util/concurrent/BlockingQueue.java

/*
 * 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 <tt>BlockingQueue</tt> is a {@link java.util.Queue} that
 * additionally supports operations that wait for elements to exist
 * when taking them, and wait for space to exist when putting them.
 *
 * <p> <tt>BlockingQueues</tt> do not accept <tt>null</tt> elements.
 * Implementations throw <tt>IllegalArgumentException</tt> on attempts
 * to <tt>add</tt>, <tt>put</tt> or <tt>offer</tt> a <tt>null</tt>.  A
 * <tt>null</tt> is used as a sentinel value to indicate failure of
 * <tt>poll</tt> operations.
 *
 * <p><tt>BlockingQueues</tt> may be capacity bounded. At any given
 * time they may have a <tt>remainingCapacity</tt> beyond which no
 * additional elements can be <tt>put</tt> without blocking.
 * BlockingQueues without any intrinsic capacity constraints always
 * report <tt>Integer.MAX_VALUE</tt> remaining capacity.
 *
 * <p> While <tt>BlockingQueues</tt> are designed to be used primarily
 * as producer-consumer queues, they support the <tt>Collection</tt>
 * interface. So for example, it is possible to remove an arbitrary
 * element from within a queue using <tt>remove(x)</tt>. However,
 * such operations are in general <em>NOT</em> performed very
 * efficiently, and are intended for only occasional use; for example,
 * when a queued message is cancelled. Also, the bulk operations, most
 * notably <tt>addAll</tt> are <em>NOT</em> performed atomically, so
 * it is possible for <tt>addAll(c)</tt> to fail (throwing an
 * exception) after adding only some of the elements in <tt>c</tt>.
 *
 * <p><tt>BlockingQueue</tt>s do <em>not</em> intrinsically support
 * any kind of &quot;close&quot; or &quot;shutdown&quot; 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
 * <em>end-of-stream</em> or <em>poison</em> objects, that are
 * interpreted accordingly when taken by consumers.
 *
 * <p>
 * Usage example. Here is a sketch of a classic producer-consumer program.
 * <pre>
 * 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();
 *   }
 * }
 * </pre>
 *
 *
 * @since 1.5
 * @spec JSR-166
 * @revised $Date: 2003/03/31 03:50:08 $
 * @editor $Author: dholmes $
 */
public interface BlockingQueue<E> extends Queue<E> {
    /**
     * Take an object from the queue, waiting if necessary for
     * an object to be present.
     * @return the object
     * @throws InterruptedException if interrupted while waiting.
     */
    public E take() throws InterruptedException;

    /**
     * Take an object from the queue if one is available within given wait 
     * time
     * @param timeout the maximum time to wait
     * @param granularity the time unit of the timeout argument.
     * @return the object, or <tt>null</tt> if the specified
     * waiting time elapses before an object is present.
     * @throws InterruptedException if interrupted while waiting.
     */
    public E poll(long timeout, TimeUnit granularity) 
        throws InterruptedException;

    /**
     * Add the given object to the queue, waiting if necessary for
     * space to become available.
     * @param x the object to add
     * @throws InterruptedException if interrupted while waiting.
     */
    public void put(E x) throws InterruptedException;

    /**
     * Add the given object to the queue if space is available within
     * given wait time.
     * @param x the object to add
     * @param timeout the maximum time to wait
     * @param granularity the time unit of the timeout argument.
     * @return <tt>true</tt> if successful, or <tt>false</tt> if 
     * the specified waiting time elapses before space is available.
     * @throws InterruptedException if interrupted while waiting.
     */
    public boolean offer(E x, long timeout, TimeUnit granularity) 
        throws InterruptedException;

    /**
     * Return the number of elements that this queue can ideally (in
     * the absence of memory or resource constraints) accept without
     * blocking, or <tt>Integer.MAX_VALUE</tt> if there is no
     * intrinsic limit.  Note that you <em>cannot</em> always tell if
     * an attempt to <tt>add</tt> an element will succeed by
     * inspecting <tt>remainingCapacity</tt> because it may be the
     * case that a waiting consumer is ready to <tt>take</tt> an
     * element out of an otherwise full queue.
     * @return the remaining capacity
     **/
    public int remainingCapacity();

}
Revision:	1.2
Committed:	Tue May 27 18:14:39 2003 UTC (21 years ago) by dl
Branch:	MAIN
Changes since 1.1:	+53 -22 lines
Log Message:	re-check-in initial implementations
#	User	Rev	Content
1	dl	1.2	/*
2			* Written by Doug Lea with assistance from members of JCP JSR-166
3			* Expert Group and released to the public domain. Use, modify, and
4			* redistribute this code in any way without acknowledgement.
5			*/
6
7	tim	1.1	package java.util.concurrent;
8			import java.util.Queue;
9
10			/**
11	dl	1.2	* A <tt>BlockingQueue</tt> is a {@link java.util.Queue} that
12			* additionally supports operations that wait for elements to exist
13			* when taking them, and wait for space to exist when putting them.
14			*
15			* <p> <tt>BlockingQueues</tt> do not accept <tt>null</tt> elements.
16			* Implementations throw <tt>IllegalArgumentException</tt> on attempts
17			* to <tt>add</tt>, <tt>put</tt> or <tt>offer</tt> a <tt>null</tt>. A
18			* <tt>null</tt> is used as a sentinel value to indicate failure of
19			* <tt>poll</tt> operations.
20			*
21			* <p><tt>BlockingQueues</tt> may be capacity bounded. At any given
22			* time they may have a <tt>remainingCapacity</tt> beyond which no
23			* additional elements can be <tt>put</tt> without blocking.
24			* BlockingQueues without any intrinsic capacity constraints always
25			* report <tt>Integer.MAX_VALUE</tt> remaining capacity.
26			*
27			* <p> While <tt>BlockingQueues</tt> are designed to be used primarily
28			* as producer-consumer queues, they support the <tt>Collection</tt>
29			* interface. So for example, it is possible to remove an arbitrary
30			* element from within a queue using <tt>remove(x)</tt>. However,
31			* such operations are in general <em>NOT</em> performed very
32			* efficiently, and are intended for only occasional use; for example,
33			* when a queued message is cancelled. Also, the bulk operations, most
34			* notably <tt>addAll</tt> are <em>NOT</em> performed atomically, so
35			* it is possible for <tt>addAll(c)</tt> to fail (throwing an
36			* exception) after adding only some of the elements in <tt>c</tt>.
37			*
38			* <p><tt>BlockingQueue</tt>s do <em>not</em> intrinsically support
39			* any kind of "close" or "shutdown" operation to
40			* indicate that no more items will be added. The needs and usage of
41			* such features tend to be implementation dependent. For example, a
42			* common tactic is for producers to insert special
43			* <em>end-of-stream</em> or <em>poison</em> objects, that are
44			* interpreted accordingly when taken by consumers.
45	tim	1.1	*
46			* <p>
47			* Usage example. Here is a sketch of a classic producer-consumer program.
48			* <pre>
49			* class Producer implements Runnable {
50			* private final BlockingQueue queue;
51			* Producer(BlockingQueue q) { queue = q; }
52			* public void run() {
53			* try {
54			* while(true) { queue.put(produce()); }
55			* }
56			* catch (InterruptedException ex) { ... handle ...}
57			* }
58			* Object produce() { ... }
59			* }
60			*
61			*
62			* class Consumer implements Runnable {
63			* private final BlockingQueue queue;
64			* Concumer(BlockingQueue q) { queue = q; }
65			* public void run() {
66			* try {
67			* while(true) { consume(queue.take()); }
68			* }
69			* catch (InterruptedException ex) { ... handle ...}
70			* }
71			* void consume(Object x) { ... }
72			* }
73			*
74			* class Setup {
75			* void main() {
76			* BlockingQueue q = new SomeQueueImplementation();
77			* Producer p = new Producer(q);
78			* Consumer c = new Consumer(q);
79			* new Thread(p).start();
80			* new Thread(c).start();
81			* }
82			* }
83			* </pre>
84			*
85			*
86			* @since 1.5
87			* @spec JSR-166
88			* @revised $Date: 2003/03/31 03:50:08 $
89			* @editor $Author: dholmes $
90			*/
91			public interface BlockingQueue<E> extends Queue<E> {
92			/**
93			* Take an object from the queue, waiting if necessary for
94			* an object to be present.
95			* @return the object
96			* @throws InterruptedException if interrupted while waiting.
97			*/
98			public E take() throws InterruptedException;
99
100			/**
101			* Take an object from the queue if one is available within given wait
102			* time
103			* @param timeout the maximum time to wait
104			* @param granularity the time unit of the timeout argument.
105			* @return the object, or <tt>null</tt> if the specified
106			* waiting time elapses before an object is present.
107			* @throws InterruptedException if interrupted while waiting.
108			*/
109			public E poll(long timeout, TimeUnit granularity)
110			throws InterruptedException;
111
112			/**
113			* Add the given object to the queue, waiting if necessary for
114			* space to become available.
115			* @param x the object to add
116			* @throws InterruptedException if interrupted while waiting.
117			*/
118			public void put(E x) throws InterruptedException;
119
120			/**
121			* Add the given object to the queue if space is available within
122			* given wait time.
123			* @param x the object to add
124			* @param timeout the maximum time to wait
125			* @param granularity the time unit of the timeout argument.
126			* @return <tt>true</tt> if successful, or <tt>false</tt> if
127			* the specified waiting time elapses before space is available.
128			* @throws InterruptedException if interrupted while waiting.
129			*/
130			public boolean offer(E x, long timeout, TimeUnit granularity)
131			throws InterruptedException;
132	dl	1.2
133			/**
134			* Return the number of elements that this queue can ideally (in
135			* the absence of memory or resource constraints) accept without
136			* blocking, or <tt>Integer.MAX_VALUE</tt> if there is no
137			* intrinsic limit. Note that you <em>cannot</em> always tell if
138			* an attempt to <tt>add</tt> an element will succeed by
139			* inspecting <tt>remainingCapacity</tt> because it may be the
140			* case that a waiting consumer is ready to <tt>take</tt> an
141			* element out of an otherwise full queue.
142			* @return the remaining capacity
143			**/
144			public int remainingCapacity();
145	tim	1.1
146			}