ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/jsr166y/TransferQueue.java
Revision: 1.2
Committed: Wed Jul 11 14:30:37 2007 UTC (16 years, 10 months ago) by dl
Branch: MAIN
Changes since 1.1: +13 -11 lines
Log Message: 
Clarify getWaitingConsumerCount

File Contents

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