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.4 by jsr166, Mon Jan 5 03:40:08 2009 UTC vs.
Revision 1.7 by jsr166, Thu Jul 30 22:45:39 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.  {@linkplain
18	>	* #tryTransfer(Object) Non-blocking} and {@linkplain
19	>	* #tryTransfer(Object,long,TimeUnit) time-out} versions of {@code
20	>	* tryTransfer} are also available.  A {@code TransferQueue} may also
21	>	* be queried, via {@link #hasWaitingConsumer}, whether there are any
22	>	* threads waiting for items, which is a converse analogy to a {@code
23	>	* peek} operation.
24		*
25	<	* <p>Like any {@code BlockingQueue}, a {@code TransferQueue} may be
25	>	* <p>Like other blocking queues, 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
#	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 specified element immediately if there exists a
43	>	* consumer already waiting to receive it (in {@link #take} or
44	>	* timed {@link #poll(Object,long,TimeUnit) poll}), otherwise
45	>	* returning {@code false} without enqueuing the element.
46		*
47		* @param e the element to transfer
48		* @return {@code true} if the element was transferred, else
#	Line 55 | Line 58 | public interface TransferQueue<E> extend
58		/**
59		* Inserts the specified element into this queue, waiting if
60		* necessary for space to become available and the element to be
61	<	* dequeued by a consumer invoking {@code take} or {@code poll}.
61	>	* received by a consumer invoking {@code take} or {@code poll}.
62		*
63		* @param e the element to transfer
64		* @throws InterruptedException if interrupted while waiting,
65	<	*         in which case the element is not enqueued.
65	>	*         in which case the element is not enqueued
66		* @throws ClassCastException if the class of the specified element
67		*         prevents it from being added to this queue
68		* @throws NullPointerException if the specified element is null
#	Line 71 | Line 74 | public interface TransferQueue<E> extend
74		/**
75		* Inserts the specified element into this queue, waiting up to
76		* the specified wait time if necessary for space to become
77	<	* available and the element to be dequeued by a consumer invoking
77	>	* available and the element to be received by a consumer invoking
78		* {@code take} or {@code poll}.
79		*
80		* @param e the element to transfer
#	Line 81 | Line 84 | public interface TransferQueue<E> extend
84		*        {@code timeout} parameter
85		* @return {@code true} if successful, or {@code false} if
86		*         the specified waiting time elapses before completion,
87	<	*         in which case the element is not enqueued.
87	>	*         in which case the element is not enqueued
88		* @throws InterruptedException if interrupted while waiting,
89	<	*         in which case the element is not enqueued.
89	>	*         in which case the element is not enqueued
90		* @throws ClassCastException if the class of the specified element
91		*         prevents it from being added to this queue
92		* @throws NullPointerException if the specified element is null
#	Line 95 | Line 98 | public interface TransferQueue<E> extend
98
99		/**
100		* Returns {@code true} if there is at least one consumer waiting
101	<	* to dequeue an element via {@code take} or {@code poll}.
101	>	* to receive an element via {@link #take} or
102	>	* timed {@link #poll(Object,long,TimeUnit) poll}.
103		* The return value represents a momentary state of affairs.
104		*
105		* @return {@code true} if there is at least one waiting consumer
#	Line 104 | Line 108 | public interface TransferQueue<E> extend
108
109		/**
110		* Returns an estimate of the number of consumers waiting to
111	<	* dequeue elements via {@code take} or {@code poll}. The return
111	>	* receive elements via {@link #take} or
112	>	* timed {@link #poll(Object,long,TimeUnit) poll}. The return
113		* value is an approximation of a momentary state of affairs, that
114		* may be inaccurate if consumers have completed or given up
115		* waiting. The value may be useful for monitoring and heuristics,
#	Line 112 | Line 117 | public interface TransferQueue<E> extend
117		* method are likely to be noticeably slower than those for
118		* {@link #hasWaitingConsumer}.
119		*
120	<	* @return the number of consumers waiting to dequeue elements
120	>	* @return the number of consumers waiting to receive elements
121		*/
122		int getWaitingConsumerCount();
123		}

Diff Legend

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