ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/jsr166x/BlockingDeque.java
Revision: 1.4
Committed: Tue Mar 15 19:47:02 2011 UTC (13 years, 1 month ago) by jsr166
Branch: MAIN
CVS Tags: jdk7-compat, release-1_7_0
Changes since 1.3: +1 -1 lines
Log Message: 
Update Creative Commons license URL in legal notices

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 jsr166 1.4 * http://creativecommons.org/publicdomain/zero/1.0/
5 dl 1.1 */
6    
7     package jsr166x; // XXX This belongs in java.util!!! XXX
8     import java.util.concurrent.*; // XXX This import goes away XXX
9 jsr166 1.2 import java.util.*;
10 dl 1.1
11     /**
12     * A {@link Deque} that additionally supports operations that wait for
13     * the deque to become non-empty when retrieving an element, and wait
14     * for space to become available in the deque when storing an
15     * element. These methods are summarized in the following table:<p>
16     *
17     * <table BORDER CELLPADDING=3 CELLSPACING=1>
18     * <tr>
19     * <td></td>
20     * <td ALIGN=CENTER COLSPAN = 2> <b>First Element (Head)</b></td>
21     * <td ALIGN=CENTER COLSPAN = 2> <b>Last Element (Tail)</b></td>
22     * </tr>
23     * <tr>
24     * <td></td>
25     * <td ALIGN=CENTER><em>Block</em></td>
26     * <td ALIGN=CENTER><em>Time out</em></td>
27     * <td ALIGN=CENTER><em>Block</em></td>
28     * <td ALIGN=CENTER><em>Time out</em></td>
29     * </tr>
30     * <tr>
31     * <td><b>Insert</b></td>
32     * <td>{@link #putFirst putFirst(e)}</td>
33     * <td>{@link #offerFirst(Object, long, TimeUnit) offerFirst(e, time, unit)}</td>
34     * <td>{@link #putLast putLast(e)}</td>
35 jsr166 1.2 * <td>{@link #offerLast(Object, long, TimeUnit) offerLast(e, time, unit)}</td>
36 dl 1.1 * </tr>
37     * <tr>
38     * <td><b>Remove</b></td>
39     * <td>{@link #takeFirst takeFirst()}</td>
40     * <td>{@link #pollFirst(long, TimeUnit) pollFirst(time, unit)}</td>
41     * <td>{@link #takeLast takeLast()}</td>
42     * <td>{@link #pollLast(long, TimeUnit) pollLast(time, unit)}</td>
43     * </tr>
44     * </table>
45     *
46     * <p>Like any {@link BlockingQueue}, a <tt>BlockingDeque</tt> is
47     * thread safe and may (or may not) be capacity-constrained. A
48     * <tt>BlockingDeque</tt> implementation may be used directly as a
49     * FIFO <tt>BlockingQueue</tt>. The blocking methods inherited from
50     * the <tt>BlockingQueue</tt> interface are precisely equivalent to
51     * <tt>BlockingDeque</tt> methods as indicated in the following table:<p>
52     *
53     * <table BORDER CELLPADDING=3 CELLSPACING=1>
54     * <tr>
55     * <td ALIGN=CENTER> <b><tt>BlockingQueue</tt> Method</b></td>
56     * <td ALIGN=CENTER> <b>Equivalent <tt>BlockingDeque</tt> Method</b></td>
57     * </tr>
58     * <tr>
59     * <tr>
60     * <td>{@link java.util.concurrent.BlockingQueue#put put(e)}</td>
61     * <td>{@link #putLast putLast(e)}</td>
62     * </tr>
63     * <tr>
64     * <td>{@link java.util.concurrent.BlockingQueue#take take()}</td>
65     * <td>{@link #takeFirst takeFirst()}</td>
66     * </tr>
67     * <tr>
68     * <td>{@link java.util.concurrent.BlockingQueue#offer(Object, long, TimeUnit) offer(e, time. unit)}</td>
69     * <td>{@link #offerLast(Object, long, TimeUnit) offerLast(e, time, unit)}</td>
70     * </tr>
71     * <tr>
72     * <td>{@link java.util.concurrent.BlockingQueue#poll(long, TimeUnit) poll(time, unit)}</td>
73     * <td>{@link #pollFirst(long, TimeUnit) pollFirst(time, unit)}</td>
74     * </tr>
75     * </table>
76     *
77     *
78     * <p>This interface is a member of the
79     * <a href="{@docRoot}/../guide/collections/index.html">
80     * Java Collections Framework</a>.
81     *
82     * @since 1.6
83     * @author Doug Lea
84     * @param <E> the type of elements held in this collection
85     */
86     public interface BlockingDeque<E> extends Deque<E>, BlockingQueue<E> {
87    
88     /**
89     * Adds the specified element as the first element of this deque,
90     * waiting if necessary for space to become available.
91     * @param o the element to add
92     * @throws InterruptedException if interrupted while waiting.
93     * @throws NullPointerException if the specified element is <tt>null</tt>.
94     */
95     void putFirst(E o) throws InterruptedException;
96    
97     /**
98     * Adds the specified element as the last element of this deque,
99     * waiting if necessary for space to become available.
100     * @param o the element to add
101     * @throws InterruptedException if interrupted while waiting.
102     * @throws NullPointerException if the specified element is <tt>null</tt>.
103     */
104     void putLast(E o) throws InterruptedException;
105    
106     /**
107     * Retrieves and removes the first element of this deque, waiting
108     * if no elements are present on this deque.
109     * @return the head of this deque
110     * @throws InterruptedException if interrupted while waiting.
111     */
112     E takeFirst() throws InterruptedException;
113    
114     /**
115     * Retrieves and removes the last element of this deque, waiting
116     * if no elements are present on this deque.
117     * @return the head of this deque
118     * @throws InterruptedException if interrupted while waiting.
119     */
120     E takeLast() throws InterruptedException;
121    
122     /**
123     * Inserts the specified element as the first element of this deque,
124     * waiting if necessary up to the specified wait time for space to
125     * become available.
126     * @param o the element to add
127     * @param timeout how long to wait before giving up, in units of
128     * <tt>unit</tt>
129     * @param unit a <tt>TimeUnit</tt> determining how to interpret the
130     * <tt>timeout</tt> parameter
131     * @return <tt>true</tt> if successful, or <tt>false</tt> if
132     * the specified waiting time elapses before space is available.
133     * @throws InterruptedException if interrupted while waiting.
134     * @throws NullPointerException if the specified element is <tt>null</tt>.
135     */
136     boolean offerFirst(E o, long timeout, TimeUnit unit)
137     throws InterruptedException;
138    
139     /**
140     * Inserts the specified element as the last element of this deque,
141     * waiting if necessary up to the specified wait time for space to
142     * become available.
143     * @param o the element to add
144     * @param timeout how long to wait before giving up, in units of
145     * <tt>unit</tt>
146     * @param unit a <tt>TimeUnit</tt> determining how to interpret the
147     * <tt>timeout</tt> parameter
148     * @return <tt>true</tt> if successful, or <tt>false</tt> if
149     * the specified waiting time elapses before space is available.
150     * @throws InterruptedException if interrupted while waiting.
151     * @throws NullPointerException if the specified element is <tt>null</tt>.
152     */
153     boolean offerLast(E o, long timeout, TimeUnit unit)
154     throws InterruptedException;
155    
156    
157     /**
158     * Retrieves and removes the first element of this deque, waiting
159     * if necessary up to the specified wait time if no elements are
160     * present on this deque.
161     * @param timeout how long to wait before giving up, in units of
162     * <tt>unit</tt>
163     * @param unit a <tt>TimeUnit</tt> determining how to interpret the
164     * <tt>timeout</tt> parameter
165     * @return the head of this deque, or <tt>null</tt> if the
166     * specified waiting time elapses before an element is present.
167     * @throws InterruptedException if interrupted while waiting.
168     */
169     E pollFirst(long timeout, TimeUnit unit)
170     throws InterruptedException;
171    
172     /**
173     * Retrieves and removes the last element of this deque, waiting
174     * if necessary up to the specified wait time if no elements are
175     * present on this deque.
176     * @param timeout how long to wait before giving up, in units of
177     * <tt>unit</tt>
178     * @param unit a <tt>TimeUnit</tt> determining how to interpret the
179     * <tt>timeout</tt> parameter
180     * @return the head of this deque, or <tt>null</tt> if the
181     * specified waiting time elapses before an element is present.
182     * @throws InterruptedException if interrupted while waiting.
183     */
184     E pollLast(long timeout, TimeUnit unit)
185     throws InterruptedException;
186    
187     /**
188     * Adds the specified element as the last element of this deque,
189     * waiting if necessary for space to become available. This
190 jsr166 1.3 * method is equivalent to putLast
191 dl 1.1 * @param o the element to add
192     * @throws InterruptedException if interrupted while waiting.
193     * @throws NullPointerException if the specified element is <tt>null</tt>.
194     */
195     void put(E o) throws InterruptedException;
196    
197 jsr166 1.2 /**
198 dl 1.1 * Inserts the specified element as the lest element of this
199     * deque, if possible. When using deques that may impose
200     * insertion restrictions (for example capacity bounds), method
201     * <tt>offer</tt> is generally preferable to method {@link
202     * Collection#add}, which can fail to insert an element only by
203 jsr166 1.3 * throwing an exception. This method is equivalent to
204 dl 1.1 * offerLast
205     *
206     * @param o the element to add.
207     * @return <tt>true</tt> if it was possible to add the element to
208     * this deque, else <tt>false</tt>
209     * @throws NullPointerException if the specified element is <tt>null</tt>
210     */
211     boolean offer(E o, long timeout, TimeUnit unit)
212     throws InterruptedException;
213    
214     /**
215     * Retrieves and removes the first element of this deque, waiting
216     * if no elements are present on this deque.
217 jsr166 1.3 * This method is equivalent to takeFirst
218 dl 1.1 * @return the head of this deque
219     * @throws InterruptedException if interrupted while waiting.
220     */
221     E take() throws InterruptedException;
222    
223     /**
224     * Retrieves and removes the first element of this deque, waiting
225     * if necessary up to the specified wait time if no elements are
226 jsr166 1.3 * present on this deque. This method is equivalent to
227 dl 1.1 * pollFirst
228     * @param timeout how long to wait before giving up, in units of
229     * <tt>unit</tt>
230     * @param unit a <tt>TimeUnit</tt> determining how to interpret the
231     * <tt>timeout</tt> parameter
232     * @return the head of this deque, or <tt>null</tt> if the
233     * specified waiting time elapses before an element is present.
234     * @throws InterruptedException if interrupted while waiting.
235     */
236     E poll(long timeout, TimeUnit unit)
237     throws InterruptedException;
238     }