ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/jsr166y/TransferQueue.java
Revision: 1.1
Committed: Tue May 29 09:55:32 2007 UTC (16 years, 11 months ago) by dl
Branch: MAIN
Log Message: 
Initial check-in

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