ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/jsr166x/BlockingDeque.java
(Generate patch)

Comparing jsr166/src/jsr166x/BlockingDeque.java (file contents):
Revision 1.1 by dl, Sun Dec 5 21:15:31 2004 UTC vs.
Revision 1.8 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 jsr166x;     // XXX This belongs in java.util!!! XXX
8 +
9   import java.util.concurrent.*;  // XXX This import goes away        XXX
10 < import java.util.*;  
10 > import java.util.*;
11  
12   /**
13   * A {@link Deque} that additionally supports operations that wait for
# Line 32 | Line 33 | import java.util.*;
33   *    <td>{@link #putFirst putFirst(e)}</td>
34   *    <td>{@link #offerFirst(Object, long, TimeUnit) offerFirst(e, time, unit)}</td>
35   *    <td>{@link #putLast putLast(e)}</td>
36 < *    <td>{@link #offerLast(Object, long, TimeUnit) offerLast(e, time, unit)}</td>
36 > *    <td>{@link #offerLast(Object, long, TimeUnit) offerLast(e, time, unit)}</td>
37   *  </tr>
38   *  <tr>
39   *    <td><b>Remove</b></td>
# Line 43 | Line 44 | import java.util.*;
44   *  </tr>
45   * </table>
46   *
47 < * <p>Like any {@link BlockingQueue}, a <tt>BlockingDeque</tt> is
47 > * <p>Like any {@link BlockingQueue}, a {@code BlockingDeque} is
48   * thread safe and may (or may not) be capacity-constrained.  A
49 < * <tt>BlockingDeque</tt> implementation may be used directly as a
50 < * FIFO <tt>BlockingQueue</tt>. The blocking methods inherited from
51 < * the <tt>BlockingQueue</tt> interface are precisely equivalent to
52 < * <tt>BlockingDeque</tt> methods as indicated in the following table:<p>
49 > * {@code BlockingDeque} implementation may be used directly as a
50 > * FIFO {@code BlockingQueue}. The blocking methods inherited from
51 > * the {@code BlockingQueue} interface are precisely equivalent to
52 > * {@code BlockingDeque} methods as indicated in the following table:<p>
53   *
54   * <table BORDER CELLPADDING=3 CELLSPACING=1>
55   *  <tr>
56 < *    <td ALIGN=CENTER> <b><tt>BlockingQueue</tt> Method</b></td>
57 < *    <td ALIGN=CENTER> <b>Equivalent <tt>BlockingDeque</tt> Method</b></td>
56 > *    <td ALIGN=CENTER> <b>{@code BlockingQueue} Method</b></td>
57 > *    <td ALIGN=CENTER> <b>Equivalent {@code BlockingDeque} Method</b></td>
58   *  </tr>
59   *  <tr>
60   *   <tr>
# Line 89 | Line 90 | public interface BlockingDeque<E> extend
90       * Adds the specified element as the first element of this deque,
91       * waiting if necessary for space to become available.
92       * @param o the element to add
93 <     * @throws InterruptedException if interrupted while waiting.
94 <     * @throws NullPointerException if the specified element is <tt>null</tt>.
93 >     * @throws InterruptedException if interrupted while waiting
94 >     * @throws NullPointerException if the specified element is {@code null}
95       */
96      void putFirst(E o) throws InterruptedException;
97  
# Line 98 | Line 99 | public interface BlockingDeque<E> extend
99       * Adds the specified element as the last element of this deque,
100       * waiting if necessary for space to become available.
101       * @param o the element to add
102 <     * @throws InterruptedException if interrupted while waiting.
103 <     * @throws NullPointerException if the specified element is <tt>null</tt>.
102 >     * @throws InterruptedException if interrupted while waiting
103 >     * @throws NullPointerException if the specified element is {@code null}
104       */
105      void putLast(E o) throws InterruptedException;
106  
# Line 107 | Line 108 | public interface BlockingDeque<E> extend
108       * Retrieves and removes the first element of this deque, waiting
109       * if no elements are present on this deque.
110       * @return the head of this deque
111 <     * @throws InterruptedException if interrupted while waiting.
111 >     * @throws InterruptedException if interrupted while waiting
112       */
113      E takeFirst() throws InterruptedException;
114  
# Line 115 | Line 116 | public interface BlockingDeque<E> extend
116       * Retrieves and removes the last element of this deque, waiting
117       * if no elements are present on this deque.
118       * @return the head of this deque
119 <     * @throws InterruptedException if interrupted while waiting.
119 >     * @throws InterruptedException if interrupted while waiting
120       */
121      E takeLast() throws InterruptedException;
122  
# Line 125 | Line 126 | public interface BlockingDeque<E> extend
126       * become available.
127       * @param o the element to add
128       * @param timeout how long to wait before giving up, in units of
129 <     * <tt>unit</tt>
130 <     * @param unit a <tt>TimeUnit</tt> determining how to interpret the
131 <     * <tt>timeout</tt> parameter
132 <     * @return <tt>true</tt> if successful, or <tt>false</tt> if
133 <     * the specified waiting time elapses before space is available.
134 <     * @throws InterruptedException if interrupted while waiting.
135 <     * @throws NullPointerException if the specified element is <tt>null</tt>.
129 >     * {@code unit}
130 >     * @param unit a {@code TimeUnit} determining how to interpret the
131 >     * {@code timeout} parameter
132 >     * @return {@code true} if successful, or {@code false} if
133 >     * the specified waiting time elapses before space is available
134 >     * @throws InterruptedException if interrupted while waiting
135 >     * @throws NullPointerException if the specified element is {@code null}
136       */
137      boolean offerFirst(E o, long timeout, TimeUnit unit)
138          throws InterruptedException;
# Line 142 | Line 143 | public interface BlockingDeque<E> extend
143       * become available.
144       * @param o the element to add
145       * @param timeout how long to wait before giving up, in units of
146 <     * <tt>unit</tt>
147 <     * @param unit a <tt>TimeUnit</tt> determining how to interpret the
148 <     * <tt>timeout</tt> parameter
149 <     * @return <tt>true</tt> if successful, or <tt>false</tt> if
150 <     * the specified waiting time elapses before space is available.
151 <     * @throws InterruptedException if interrupted while waiting.
152 <     * @throws NullPointerException if the specified element is <tt>null</tt>.
146 >     * {@code unit}
147 >     * @param unit a {@code TimeUnit} determining how to interpret the
148 >     * {@code timeout} parameter
149 >     * @return {@code true} if successful, or {@code false} if
150 >     * the specified waiting time elapses before space is available
151 >     * @throws InterruptedException if interrupted while waiting
152 >     * @throws NullPointerException if the specified element is {@code null}
153       */
154      boolean offerLast(E o, long timeout, TimeUnit unit)
155          throws InterruptedException;
# Line 159 | Line 160 | public interface BlockingDeque<E> extend
160       * if necessary up to the specified wait time if no elements are
161       * present on this deque.
162       * @param timeout how long to wait before giving up, in units of
163 <     * <tt>unit</tt>
164 <     * @param unit a <tt>TimeUnit</tt> determining how to interpret the
165 <     * <tt>timeout</tt> parameter
166 <     * @return the head of this deque, or <tt>null</tt> if the
167 <     * specified waiting time elapses before an element is present.
168 <     * @throws InterruptedException if interrupted while waiting.
163 >     * {@code unit}
164 >     * @param unit a {@code TimeUnit} determining how to interpret the
165 >     * {@code timeout} parameter
166 >     * @return the head of this deque, or {@code null} if the
167 >     * specified waiting time elapses before an element is present
168 >     * @throws InterruptedException if interrupted while waiting
169       */
170      E pollFirst(long timeout, TimeUnit unit)
171          throws InterruptedException;
# Line 174 | Line 175 | public interface BlockingDeque<E> extend
175       * if necessary up to the specified wait time if no elements are
176       * present on this deque.
177       * @param timeout how long to wait before giving up, in units of
178 <     * <tt>unit</tt>
179 <     * @param unit a <tt>TimeUnit</tt> determining how to interpret the
180 <     * <tt>timeout</tt> parameter
181 <     * @return the head of this deque, or <tt>null</tt> if the
182 <     * specified waiting time elapses before an element is present.
183 <     * @throws InterruptedException if interrupted while waiting.
178 >     * {@code unit}
179 >     * @param unit a {@code TimeUnit} determining how to interpret the
180 >     * {@code timeout} parameter
181 >     * @return the head of this deque, or {@code null} if the
182 >     * specified waiting time elapses before an element is present
183 >     * @throws InterruptedException if interrupted while waiting
184       */
185      E pollLast(long timeout, TimeUnit unit)
186          throws InterruptedException;
# Line 187 | Line 188 | public interface BlockingDeque<E> extend
188      /**
189       * Adds the specified element as the last element of this deque,
190       * waiting if necessary for space to become available.  This
191 <     * method is equivalent to to putLast
191 >     * method is equivalent to putLast.
192       * @param o the element to add
193 <     * @throws InterruptedException if interrupted while waiting.
194 <     * @throws NullPointerException if the specified element is <tt>null</tt>.
193 >     * @throws InterruptedException if interrupted while waiting
194 >     * @throws NullPointerException if the specified element is {@code null}
195       */
196      void put(E o) throws InterruptedException;
197  
198 <    /**
198 >    /**
199       * Inserts the specified element as the lest element of this
200       * deque, if possible.  When using deques that may impose
201       * insertion restrictions (for example capacity bounds), method
202 <     * <tt>offer</tt> is generally preferable to method {@link
202 >     * {@code offer} is generally preferable to method {@link
203       * Collection#add}, which can fail to insert an element only by
204 <     * throwing an exception.  This method is equivalent to to
205 <     * offerLast
204 >     * throwing an exception.  This method is equivalent to
205 >     * offerLast.
206       *
207 <     * @param o the element to add.
208 <     * @return <tt>true</tt> if it was possible to add the element to
209 <     *         this deque, else <tt>false</tt>
210 <     * @throws NullPointerException if the specified element is <tt>null</tt>
207 >     * @param o the element to add
208 >     * @return {@code true} if it was possible to add the element to
209 >     *         this deque, else {@code false}
210 >     * @throws NullPointerException if the specified element is {@code null}
211       */
212      boolean offer(E o, long timeout, TimeUnit unit)
213          throws InterruptedException;
# Line 214 | Line 215 | public interface BlockingDeque<E> extend
215      /**
216       * Retrieves and removes the first element of this deque, waiting
217       * if no elements are present on this deque.
218 <     * This method is equivalent to to takeFirst
218 >     * This method is equivalent to takeFirst.
219       * @return the head of this deque
220 <     * @throws InterruptedException if interrupted while waiting.
220 >     * @throws InterruptedException if interrupted while waiting
221       */
222      E take() throws InterruptedException;
223  
224      /**
225       * Retrieves and removes the first element of this deque, waiting
226       * if necessary up to the specified wait time if no elements are
227 <     * present on this deque.  This method is equivalent to to
228 <     * pollFirst
227 >     * present on this deque.  This method is equivalent to
228 >     * pollFirst.
229       * @param timeout how long to wait before giving up, in units of
230 <     * <tt>unit</tt>
231 <     * @param unit a <tt>TimeUnit</tt> determining how to interpret the
232 <     * <tt>timeout</tt> parameter
233 <     * @return the head of this deque, or <tt>null</tt> if the
234 <     * specified waiting time elapses before an element is present.
235 <     * @throws InterruptedException if interrupted while waiting.
230 >     * {@code unit}
231 >     * @param unit a {@code TimeUnit} determining how to interpret the
232 >     * {@code timeout} parameter
233 >     * @return the head of this deque, or {@code null} if the
234 >     * specified waiting time elapses before an element is present
235 >     * @throws InterruptedException if interrupted while waiting
236       */
237      E poll(long timeout, TimeUnit unit)
238          throws InterruptedException;

Diff Legend

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