ViewVC Help

View File | Revision Log | Show Annotations | Download File | Root Listing

root/jsr166/jsr166/src/main/java/util/concurrent/BlockingQueue.java

Comparing jsr166/src/main/java/util/concurrent/BlockingQueue.java (file contents):
Revision 1.6 by dl, Tue Jun 24 14:34:47 2003 UTC vs.
Revision 1.7 by dholmes, Mon Jul 28 04:11:54 2003 UTC

#	Line 12 | Line 12 | import java.util.Queue;
12		* that wait for elements to exist when retrieving them, and wait for
13		* space to exist when putting them.
14		*
15	<	* <p> <tt>BlockingQueues</tt> do not accept <tt>null</tt> elements.
15	>	* <p>A <tt>BlockingQueue</tt> does 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
21	>	* <p>A <tt>BlockingQueue</tt> may be capacity bounded. At any given
22	>	* time it 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 a remaining capacity of <tt>Integer.MAX_VALUE</tt>.
24	>	* A <tt>BlockingQueue</tt> without any intrinsic capacity constraints always
25	>	* reports a remaining capacity of <tt>Integer.MAX_VALUE</tt>.
26		*
27	<	* <p> While <tt>BlockingQueues</tt> are designed to be used primarily
28	<	* as producer-consumer queues, they additionally support the
27	>	* <p> While <tt>BlockingQueue</tt> is designed to be used primarily
28	>	* as for producer-consumer queues, it additionally supports the
29		* <tt>Collection</tt> interface.  So, for example, it is possible to
30		* remove an arbitrary element from within a queue using
31		* <tt>remove(x)</tt>. However, such operations are in general
#	Line 36 | Line 36 | import java.util.Queue;
36		* fail (throwing an exception) after adding only some of the elements
37		* in <tt>c</tt>.
38		*
39	<	* <p><tt>BlockingQueue</tt>s do <em>not</em> intrinsically support
39	>	* <p>A <tt>BlockingQueue</tt> does <em>not</em> intrinsically support
40		* any kind of &quot;close&quot; or &quot;shutdown&quot; operation to
41		* indicate that no more items will be added.  The needs and usage of
42		* such features tend to be implementation-dependent. For example, a
#	Line 46 | Line 46 | import java.util.Queue;
46		*
47		* <p>
48		* Usage example, based on a typical producer-consumer scenario.
49	<	* Note that Blocking queues can safely be used with multiple producers
50	<	* and multiple consumers.
49	>	* Note that a <tt>BlockingQueue</tt> can safely be used with multiple
50	>	* producers and multiple consumers.
51		* <pre>
52		* class Producer implements Runnable {
53		*   private final BlockingQueue queue;
#	Line 94 | Line 94 | import java.util.Queue;
94		* @author Doug Lea
95		*/
96		public interface BlockingQueue<E> extends Queue<E> {
97	+
98	+	/**
99	+	* @throws IllegalStateException if this queue is full
100	+	* @throws NullPointerException if <tt>x<tt> is <tt>null</tt>.
101	+	*/
102	+	boolean add(E x);
103	+
104	+	/**
105	+	* @throws IllegalStateException if this queue is full
106	+	* @throws NullPointerException if <tt>x<tt> is <tt>null</tt>.
107	+	*/
108	+	boolean addAll(Collection c);
109	+
110	+	/**
111	+	* @throws NullPointerException if <tt>x<tt> is <tt>null</tt>.
112	+	*/
113	+	public boolean offer(E x);
114	+
115		/**
116	<	* Retrieve and remove the first element from the queue, waiting
117	<	* if no objects are present on the queue.
118	<	* @return the object
116	>	* Add the specified element to this queue, waiting if necessary up to the
117	>	* specified wait time for space to become available.
118	>	* @param x the element to add
119	>	* @param timeout how long to wait before giving up, in units of
120	>	* <tt>unit</tt>
121	>	* @param unit a <tt>TimeUnit</tt> determining how to interpret the
122	>	* <tt>timeout</tt> parameter
123	>	* @return <tt>true</tt> if successful, or <tt>false</tt> if
124	>	* the specified waiting time elapses before space is available.
125		* @throws InterruptedException if interrupted while waiting.
126	+	* @throws NullPointerException if <tt>x</tt> is <tt>null</tt>.
127		*/
128	<	E take() throws InterruptedException;
128	>	boolean offer(E x, long timeout, TimeUnit unit)
129	>	throws InterruptedException;
130
131		/**
132	<	* Retrieve and remove the first element from the queue, waiting
133	<	* if necessary up to a specified wait time if no objects are
134	<	* present on the queue.
132	>	* Retrieve and remove the head of this queue, waiting
133	>	* if necessary up to the specified wait time if no elements are
134	>	* present on this queue.
135		* @param timeout how long to wait before giving up, in units of
136		* <tt>unit</tt>
137	<	* @param unit a TimeUnit determining how to interpret the timeout
138	<	* parameter
139	<	* @return the object, or <tt>null</tt> if the specified waiting
140	<	* time elapses before an object is present.
137	>	* @param unit a <tt>TimeUnit</tt> determining how to interpret the
138	>	* <tt>timeout</tt> parameter
139	>	* @return the head of this queue, or <tt>null</tt> if the
140	>	* specified waiting time elapses before an element is present.
141		* @throws InterruptedException if interrupted while waiting.
142		*/
143		E poll(long timeout, TimeUnit unit)
144		throws InterruptedException;
145
146		/**
147	<	* Add the given object to the queue, waiting if necessary for
148	<	* space to become available.
149	<	* @param x the object to add
147	>	* Retrieve and remove the head of this queue, waiting
148	>	* if no elements are present on this queue.
149	>	* @return the head of this queue
150		* @throws InterruptedException if interrupted while waiting.
151		*/
152	<	void put(E x) throws InterruptedException;
152	>	E take() throws InterruptedException;
153	>
154
155		/**
156	<	* Add the given object to the queue, waiting if necessary up to a
157	<	* specified wait time for space to become available.
158	<	* @param x the object to add
132	<	* @param timeout how long to wait before giving up, in units of
133	<	* <tt>unit</tt>
134	<	* @param unit a TimeUnit determining how to interpret the timeout
135	<	* parameter
136	<	* @return <tt>true</tt> if successful, or <tt>false</tt> if
137	<	* the specified waiting time elapses before space is available.
156	>	* Add the specified element to this queue, waiting if necessary for
157	>	* space to become available.
158	>	* @param x the element to add
159		* @throws InterruptedException if interrupted while waiting.
160	+	* @throws NullPointerException if <tt>x</tt> is <tt>null</tt>.
161		*/
162	<	boolean offer(E x, long timeout, TimeUnit unit)
163	<	throws InterruptedException;
162	>	void put(E x) throws InterruptedException;
163	>
164
165		/**
166		* Return the number of elements that this queue can ideally (in
167		* the absence of memory or resource constraints) accept without
168		* blocking, or <tt>Integer.MAX_VALUE</tt> if there is no
169	<	* intrinsic limit.  Note that you <em>cannot</em> always tell if
169	>	* intrinsic limit.
170	>	* <p>Note that you <em>cannot</em> always tell if
171		* an attempt to <tt>add</tt> an element will succeed by
172		* inspecting <tt>remainingCapacity</tt> because it may be the
173		* case that a waiting consumer is ready to <tt>take</tt> an
#	Line 154 | Line 177 | public interface BlockingQueue<E> extend
177		int remainingCapacity();
178
179		}
180	+
181	+
182	+
183	+
184	+
185	+
186	+
187	+

Diff Legend

–	Removed lines
+	Added lines
<	Changed lines
>	Changed lines