ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/main/java/util/concurrent/TransferQueue.java
Revision: 1.2
Committed: Wed Jul 29 02:35:48 2009 UTC (14 years, 10 months ago) by jsr166
Branch: MAIN
Changes since 1.1: +11 -9 lines
Log Message: 
sync with jsr166y package

File Contents

# User Rev Content
1 jsr166 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
5     */
6    
7     package java.util.concurrent;
8    
9     /**
10     * A {@link BlockingQueue} in which producers may wait for consumers
11     * to receive elements. A {@code TransferQueue} may be useful for
12     * example in message passing applications in which producers
13 jsr166 1.2 * sometimes (using method {@link #transfer}) await receipt of
14     * elements by consumers invoking {@code take} or {@code poll}, while
15     * at other times enqueue elements (via method {@code put}) without
16     * waiting for receipt. {@linkplain
17     * #tryTransfer(Object) Non-blocking} and {@linkplain
18     * #tryTransfer(Object,long,TimeUnit) time-out} versions of {@code
19     * tryTransfer} are also available. A {@code TransferQueue} may also
20     * be queried, via {@link #hasWaitingConsumer}, whether there are any
21     * threads waiting for items, which is a converse analogy to a {@code
22     * peek} operation.
23 jsr166 1.1 *
24 jsr166 1.2 * <p>Like other blocking queues, a {@code TransferQueue} may be
25 jsr166 1.1 * capacity bounded. If so, an attempted {@code transfer} operation
26     * may initially block waiting for available space, and/or
27     * subsequently block waiting for reception by a consumer. Note that
28     * in a queue with zero capacity, such as {@link SynchronousQueue},
29     * {@code put} and {@code transfer} are effectively synonymous.
30     *
31     * <p>This interface is a member of the
32     * <a href="{@docRoot}/../technotes/guides/collections/index.html">
33     * Java Collections Framework</a>.
34     *
35     * @since 1.7
36     * @author Doug Lea
37     * @param <E> the type of elements held in this collection
38     */
39     public interface TransferQueue<E> extends BlockingQueue<E> {
40     /**
41     * Transfers the specified element if there exists a consumer
42     * already waiting to receive it, otherwise returning {@code false}
43     * without enqueuing the element.
44     *
45     * @param e the element to transfer
46     * @return {@code true} if the element was transferred, else
47     * {@code false}
48     * @throws ClassCastException if the class of the specified element
49     * prevents it from being added to this queue
50     * @throws NullPointerException if the specified element is null
51     * @throws IllegalArgumentException if some property of the specified
52     * element prevents it from being added to this queue
53     */
54     boolean tryTransfer(E e);
55    
56     /**
57     * Inserts the specified element into this queue, waiting if
58     * necessary for space to become available and the element to be
59     * dequeued by a consumer invoking {@code take} or {@code poll}.
60     *
61     * @param e the element to transfer
62     * @throws InterruptedException if interrupted while waiting,
63     * in which case the element is not enqueued
64     * @throws ClassCastException if the class of the specified element
65     * prevents it from being added to this queue
66     * @throws NullPointerException if the specified element is null
67     * @throws IllegalArgumentException if some property of the specified
68     * element prevents it from being added to this queue
69     */
70     void transfer(E e) throws InterruptedException;
71    
72     /**
73     * Inserts the specified element into this queue, waiting up to
74     * the specified wait time if necessary for space to become
75     * available and the element to be dequeued by a consumer invoking
76     * {@code take} or {@code poll}.
77     *
78     * @param e the element to transfer
79     * @param timeout how long to wait before giving up, in units of
80     * {@code unit}
81     * @param unit a {@code TimeUnit} determining how to interpret the
82     * {@code timeout} parameter
83     * @return {@code true} if successful, or {@code false} if
84     * the specified waiting time elapses before completion,
85     * in which case the element is not enqueued
86     * @throws InterruptedException if interrupted while waiting,
87     * in which case the element is not enqueued
88     * @throws ClassCastException if the class of the specified element
89     * prevents it from being added to this queue
90     * @throws NullPointerException if the specified element is null
91     * @throws IllegalArgumentException if some property of the specified
92     * element prevents it from being added to this queue
93     */
94     boolean tryTransfer(E e, long timeout, TimeUnit unit)
95     throws InterruptedException;
96    
97     /**
98     * Returns {@code true} if there is at least one consumer waiting
99     * to dequeue an element via {@code take} or {@code poll}.
100     * The return value represents a momentary state of affairs.
101     *
102     * @return {@code true} if there is at least one waiting consumer
103     */
104     boolean hasWaitingConsumer();
105    
106     /**
107     * Returns an estimate of the number of consumers waiting to
108     * dequeue elements via {@code take} or {@code poll}. The return
109     * value is an approximation of a momentary state of affairs, that
110     * may be inaccurate if consumers have completed or given up
111     * waiting. The value may be useful for monitoring and heuristics,
112     * but not for synchronization control. Implementations of this
113     * method are likely to be noticeably slower than those for
114     * {@link #hasWaitingConsumer}.
115     *
116     * @return the number of consumers waiting to dequeue elements
117     */
118     int getWaitingConsumerCount();
119     }