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.13 by jsr166, Sun Jan 18 20:17:33 2015 UTC

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

Diff Legend

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