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 {@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/05/28 23:00:40 $
 * @editor $Author: dl $
 */
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 unit 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 unit) 
        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 unit 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 unit) 
        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.4
Committed:	Sat Jun 7 18:20:20 2003 UTC (21 years ago) by dl
Branch:	MAIN
CVS Tags:	JSR166_PRELIMINARY_TEST_RELEASE_1
Changes since 1.3:	+4 -4 lines
Log Message:	Misc documentation updates
#	Content
1	/*
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	package java.util.concurrent;
8	import java.util.Queue;
9
10	/**
11	* A {@link java.util.Queue} that additionally supports operations
12	* that wait for elements to exist when taking them, and wait for
13	* 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	*
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/05/28 23:00:40 $
89	* @editor $Author: dl $
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 unit 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 unit)
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 unit 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 unit)
131	throws InterruptedException;
132
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
146	}