ViewVC Help

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

root/jsr166/jsr166/src/jsr166y/TransferQueue.java

Comparing jsr166/src/jsr166y/TransferQueue.java (file contents):
Revision 1.5 by jsr166, Tue Jul 21 00:15:14 2009 UTC vs.
Revision 1.11 by jsr166, Sun Aug 2 22:58:50 2009 UTC

#	Line 11 | Line 11 | import java.util.concurrent.*;
11		* A {@link BlockingQueue} in which producers may wait for consumers
12		* to receive elements.  A {@code TransferQueue} may be useful for
13		* example in message passing applications in which producers
14	<	* sometimes (using method {@code transfer}) await receipt of
15	<	* elements by consumers invoking {@code take} or {@code poll},
16	<	* while at other times enqueue elements (via method {@code put})
17	<	* without waiting for receipt. Non-blocking and time-out versions of
18	<	* {@code tryTransfer} are also available.  A TransferQueue may also
19	<	* be queried via {@code hasWaitingConsumer} whether there are any
20	<	* threads waiting for items, which is a converse analogy to a
21	<	* {@code peek} operation.
14	>	* sometimes (using method {@link #transfer}) await receipt of
15	>	* elements by consumers invoking {@code take} or {@code poll}, while
16	>	* at other times enqueue elements (via method {@code put}) without
17	>	* waiting for receipt.
18	>	* {@linkplain #tryTransfer(Object) Non-blocking} and
19	>	* {@linkplain #tryTransfer(Object,long,TimeUnit) time-out} versions of
20	>	* {@code tryTransfer} are also available.
21	>	* A {@code TransferQueue} may also be queried, via {@link
22	>	* #hasWaitingConsumer}, whether there are any threads waiting for
23	>	* items, which is a converse analogy to a {@code peek} operation.
24		*
25	<	* <p>Like any {@code BlockingQueue}, a {@code TransferQueue} may be
26	<	* capacity bounded. If so, an attempted {@code transfer} operation
27	<	* may initially block waiting for available space, and/or
28	<	* subsequently block waiting for reception by a consumer.  Note that
29	<	* in a queue with zero capacity, such as {@link SynchronousQueue},
30	<	* {@code put} and {@code transfer} are effectively synonymous.
25	>	* <p>Like other blocking queues, a {@code TransferQueue} may be
26	>	* capacity bounded.  If so, an attempted transfer operation may
27	>	* initially block waiting for available space, and/or subsequently
28	>	* block waiting for reception by a consumer.  Note that in a queue
29	>	* with zero capacity, such as {@link SynchronousQueue}, {@code put}
30	>	* and {@code transfer} are effectively synonymous.
31		*
32		* <p>This interface is a member of the
33		* <a href="{@docRoot}/../technotes/guides/collections/index.html">
#	Line 37 | Line 39 | import java.util.concurrent.*;
39		*/
40		public interface TransferQueue<E> extends BlockingQueue<E> {
41		/**
42	<	* Transfers the specified element if there exists a consumer
43	<	* already waiting to receive it, otherwise returning {@code false}
44	<	* without enqueuing the element.
42	>	* Transfers the element to a waiting consumer immediately, if possible.
43	>	*
44	>	* <p>More precisely, transfers the specified element immediately
45	>	* if there exists a consumer already waiting to receive it (in
46	>	* {@link #take} or timed {@link #poll(long,TimeUnit) poll}),
47	>	* otherwise returning {@code false} without enqueuing the element.
48		*
49		* @param e the element to transfer
50		* @return {@code true} if the element was transferred, else
#	Line 53 | Line 58 | public interface TransferQueue<E> extend
58		boolean tryTransfer(E e);
59
60		/**
61	<	* Inserts the specified element into this queue, waiting if
62	<	* necessary for space to become available and the element to be
63	<	* dequeued by a consumer invoking {@code take} or {@code poll}.
61	>	* Transfers the element to a consumer, waiting if necessary to do so.
62	>	*
63	>	* <p>More precisely, transfers the specified element immediately
64	>	* if there exists a consumer already waiting to receive it (in
65	>	* {@link #take} or timed {@link #poll(long,TimeUnit) poll}),
66	>	* else waits until the element is received by a consumer.
67		*
68		* @param e the element to transfer
69		* @throws InterruptedException if interrupted while waiting,
70	<	*         in which case the element is not enqueued
70	>	*         in which case the element is not left enqueued
71		* @throws ClassCastException if the class of the specified element
72		*         prevents it from being added to this queue
73		* @throws NullPointerException if the specified element is null
#	Line 69 | Line 77 | public interface TransferQueue<E> extend
77		void transfer(E e) throws InterruptedException;
78
79		/**
80	<	* Inserts the specified element into this queue, waiting up to
81	<	* the specified wait time if necessary for space to become
82	<	* available and the element to be dequeued by a consumer invoking
83	<	* {@code take} or {@code poll}.
80	>	* Transfers the element to a consumer if it is possible to do so
81	>	* before the timeout elapses.
82	>	*
83	>	* <p>More precisely, transfers the specified element immediately
84	>	* if there exists a consumer already waiting to receive it (in
85	>	* {@link #take} or timed {@link #poll(long,TimeUnit) poll}),
86	>	* else waits until the element is received by a consumer,
87	>	* returning {@code false} if the specified wait time elapses
88	>	* before the element can be transferred.
89		*
90		* @param e the element to transfer
91		* @param timeout how long to wait before giving up, in units of
#	Line 81 | Line 94 | public interface TransferQueue<E> extend
94		*        {@code timeout} parameter
95		* @return {@code true} if successful, or {@code false} if
96		*         the specified waiting time elapses before completion,
97	<	*         in which case the element is not enqueued
97	>	*         in which case the element is not left enqueued
98		* @throws InterruptedException if interrupted while waiting,
99	<	*         in which case the element is not enqueued
99	>	*         in which case the element is not left enqueued
100		* @throws ClassCastException if the class of the specified element
101		*         prevents it from being added to this queue
102		* @throws NullPointerException if the specified element is null
#	Line 95 | Line 108 | public interface TransferQueue<E> extend
108
109		/**
110		* Returns {@code true} if there is at least one consumer waiting
111	<	* to dequeue an element via {@code take} or {@code poll}.
111	>	* to receive an element via {@link #take} or
112	>	* timed {@link #poll(long,TimeUnit) poll}.
113		* The return value represents a momentary state of affairs.
114		*
115		* @return {@code true} if there is at least one waiting consumer
#	Line 104 | Line 118 | public interface TransferQueue<E> extend
118
119		/**
120		* Returns an estimate of the number of consumers waiting to
121	<	* dequeue elements via {@code take} or {@code poll}. The return
122	<	* value is an approximation of a momentary state of affairs, that
123	<	* may be inaccurate if consumers have completed or given up
124	<	* waiting. The value may be useful for monitoring and heuristics,
125	<	* but not for synchronization control. Implementations of this
121	>	* receive elements via {@link #take} or timed
122	>	* {@link #poll(long,TimeUnit) poll}.  The return value is an
123	>	* approximation of a momentary state of affairs, that may be
124	>	* inaccurate if consumers have completed or given up waiting.
125	>	* The value may be useful for monitoring and heuristics, but
126	>	* not for synchronization control.  Implementations of this
127		* method are likely to be noticeably slower than those for
128		* {@link #hasWaitingConsumer}.
129		*
130	<	* @return the number of consumers waiting to dequeue elements
130	>	* @return the number of consumers waiting to receive elements
131		*/
132		int getWaitingConsumerCount();
133		}

Diff Legend

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