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

Comparing jsr166/src/main/java/util/concurrent/BlockingDeque.java (file contents):
Revision 1.23 by dl, Wed Apr 20 19:08:20 2011 UTC vs.
Revision 1.24 by jsr166, Wed Jan 16 01:59:47 2013 UTC

# Line 12 | Line 12 | import java.util.*;
12   * for the deque to become non-empty when retrieving an element, and wait for
13   * space to become available in the deque when storing an element.
14   *
15 < * <p><tt>BlockingDeque</tt> methods come in four forms, with different ways
15 > * <p>{@code BlockingDeque} methods come in four forms, with different ways
16   * of handling operations that cannot be satisfied immediately, but may be
17   * satisfied at some point in the future:
18   * one throws an exception, the second returns a special value (either
19 < * <tt>null</tt> or <tt>false</tt>, depending on the operation), the third
19 > * {@code null} or {@code false}, depending on the operation), the third
20   * blocks the current thread indefinitely until the operation can succeed,
21   * and the fourth blocks for only a given maximum time limit before giving
22   * up.  These methods are summarized in the following table:
# Line 87 | Line 87 | import java.util.*;
87   *  </tr>
88   * </table>
89   *
90 < * <p>Like any {@link BlockingQueue}, a <tt>BlockingDeque</tt> is thread safe,
90 > * <p>Like any {@link BlockingQueue}, a {@code BlockingDeque} is thread safe,
91   * does not permit null elements, and may (or may not) be
92   * capacity-constrained.
93   *
94 < * <p>A <tt>BlockingDeque</tt> implementation may be used directly as a FIFO
95 < * <tt>BlockingQueue</tt>. The methods inherited from the
96 < * <tt>BlockingQueue</tt> interface are precisely equivalent to
97 < * <tt>BlockingDeque</tt> methods as indicated in the following table:
94 > * <p>A {@code BlockingDeque} implementation may be used directly as a FIFO
95 > * {@code BlockingQueue}. The methods inherited from the
96 > * {@code BlockingQueue} interface are precisely equivalent to
97 > * {@code BlockingDeque} methods as indicated in the following table:
98   *
99   * <p>
100   * <table BORDER CELLPADDING=3 CELLSPACING=1>
101   *  <tr>
102 < *    <td ALIGN=CENTER> <b><tt>BlockingQueue</tt> Method</b></td>
103 < *    <td ALIGN=CENTER> <b>Equivalent <tt>BlockingDeque</tt> Method</b></td>
102 > *    <td ALIGN=CENTER> <b>{@code BlockingQueue} Method</b></td>
103 > *    <td ALIGN=CENTER> <b>Equivalent {@code BlockingDeque} Method</b></td>
104   *  </tr>
105   *  <tr>
106   *    <td ALIGN=CENTER COLSPAN = 2> <b>Insert</b></td>
# Line 179 | Line 179 | public interface BlockingDeque<E> extend
179      /**
180       * Inserts the specified element at the front of this deque if it is
181       * possible to do so immediately without violating capacity restrictions,
182 <     * throwing an <tt>IllegalStateException</tt> if no space is currently
182 >     * throwing an {@code IllegalStateException} if no space is currently
183       * available.  When using a capacity-restricted deque, it is generally
184       * preferable to use {@link #offerFirst(Object) offerFirst}.
185       *
# Line 194 | Line 194 | public interface BlockingDeque<E> extend
194      /**
195       * Inserts the specified element at the end of this deque if it is
196       * possible to do so immediately without violating capacity restrictions,
197 <     * throwing an <tt>IllegalStateException</tt> if no space is currently
197 >     * throwing an {@code IllegalStateException} if no space is currently
198       * available.  When using a capacity-restricted deque, it is generally
199       * preferable to use {@link #offerLast(Object) offerLast}.
200       *
# Line 209 | Line 209 | public interface BlockingDeque<E> extend
209      /**
210       * Inserts the specified element at the front of this deque if it is
211       * possible to do so immediately without violating capacity restrictions,
212 <     * returning <tt>true</tt> upon success and <tt>false</tt> if no space is
212 >     * returning {@code true} upon success and {@code false} if no space is
213       * currently available.
214       * When using a capacity-restricted deque, this method is generally
215       * preferable to the {@link #addFirst(Object) addFirst} method, which can
# Line 225 | Line 225 | public interface BlockingDeque<E> extend
225      /**
226       * Inserts the specified element at the end of this deque if it is
227       * possible to do so immediately without violating capacity restrictions,
228 <     * returning <tt>true</tt> upon success and <tt>false</tt> if no space is
228 >     * returning {@code true} upon success and {@code false} if no space is
229       * currently available.
230       * When using a capacity-restricted deque, this method is generally
231       * preferable to the {@link #addLast(Object) addLast} method, which can
# Line 273 | Line 273 | public interface BlockingDeque<E> extend
273       *
274       * @param e the element to add
275       * @param timeout how long to wait before giving up, in units of
276 <     *        <tt>unit</tt>
277 <     * @param unit a <tt>TimeUnit</tt> determining how to interpret the
278 <     *        <tt>timeout</tt> parameter
279 <     * @return <tt>true</tt> if successful, or <tt>false</tt> if
276 >     *        {@code unit}
277 >     * @param unit a {@code TimeUnit} determining how to interpret the
278 >     *        {@code timeout} parameter
279 >     * @return {@code true} if successful, or {@code false} if
280       *         the specified waiting time elapses before space is available
281       * @throws InterruptedException if interrupted while waiting
282       * @throws ClassCastException if the class of the specified element
# Line 295 | Line 295 | public interface BlockingDeque<E> extend
295       *
296       * @param e the element to add
297       * @param timeout how long to wait before giving up, in units of
298 <     *        <tt>unit</tt>
299 <     * @param unit a <tt>TimeUnit</tt> determining how to interpret the
300 <     *        <tt>timeout</tt> parameter
301 <     * @return <tt>true</tt> if successful, or <tt>false</tt> if
298 >     *        {@code unit}
299 >     * @param unit a {@code TimeUnit} determining how to interpret the
300 >     *        {@code timeout} parameter
301 >     * @return {@code true} if successful, or {@code false} if
302       *         the specified waiting time elapses before space is available
303       * @throws InterruptedException if interrupted while waiting
304       * @throws ClassCastException if the class of the specified element
# Line 334 | Line 334 | public interface BlockingDeque<E> extend
334       * become available.
335       *
336       * @param timeout how long to wait before giving up, in units of
337 <     *        <tt>unit</tt>
338 <     * @param unit a <tt>TimeUnit</tt> determining how to interpret the
339 <     *        <tt>timeout</tt> parameter
340 <     * @return the head of this deque, or <tt>null</tt> if the specified
337 >     *        {@code unit}
338 >     * @param unit a {@code TimeUnit} determining how to interpret the
339 >     *        {@code timeout} parameter
340 >     * @return the head of this deque, or {@code null} if the specified
341       *         waiting time elapses before an element is available
342       * @throws InterruptedException if interrupted while waiting
343       */
# Line 350 | Line 350 | public interface BlockingDeque<E> extend
350       * become available.
351       *
352       * @param timeout how long to wait before giving up, in units of
353 <     *        <tt>unit</tt>
354 <     * @param unit a <tt>TimeUnit</tt> determining how to interpret the
355 <     *        <tt>timeout</tt> parameter
356 <     * @return the tail of this deque, or <tt>null</tt> if the specified
353 >     *        {@code unit}
354 >     * @param unit a {@code TimeUnit} determining how to interpret the
355 >     *        {@code timeout} parameter
356 >     * @return the tail of this deque, or {@code null} if the specified
357       *         waiting time elapses before an element is available
358       * @throws InterruptedException if interrupted while waiting
359       */
# Line 363 | Line 363 | public interface BlockingDeque<E> extend
363      /**
364       * Removes the first occurrence of the specified element from this deque.
365       * If the deque does not contain the element, it is unchanged.
366 <     * More formally, removes the first element <tt>e</tt> such that
367 <     * <tt>o.equals(e)</tt> (if such an element exists).
368 <     * Returns <tt>true</tt> if this deque contained the specified element
366 >     * More formally, removes the first element {@code e} such that
367 >     * {@code o.equals(e)} (if such an element exists).
368 >     * Returns {@code true} if this deque contained the specified element
369       * (or equivalently, if this deque changed as a result of the call).
370       *
371       * @param o element to be removed from this deque, if present
372 <     * @return <tt>true</tt> if an element was removed as a result of this call
372 >     * @return {@code true} if an element was removed as a result of this call
373       * @throws ClassCastException if the class of the specified element
374       *         is incompatible with this deque
375       *         (<a href="../Collection.html#optional-restrictions">optional</a>)
# Line 381 | Line 381 | public interface BlockingDeque<E> extend
381      /**
382       * Removes the last occurrence of the specified element from this deque.
383       * If the deque does not contain the element, it is unchanged.
384 <     * More formally, removes the last element <tt>e</tt> such that
385 <     * <tt>o.equals(e)</tt> (if such an element exists).
386 <     * Returns <tt>true</tt> if this deque contained the specified element
384 >     * More formally, removes the last element {@code e} such that
385 >     * {@code o.equals(e)} (if such an element exists).
386 >     * Returns {@code true} if this deque contained the specified element
387       * (or equivalently, if this deque changed as a result of the call).
388       *
389       * @param o element to be removed from this deque, if present
390 <     * @return <tt>true</tt> if an element was removed as a result of this call
390 >     * @return {@code true} if an element was removed as a result of this call
391       * @throws ClassCastException if the class of the specified element
392       *         is incompatible with this deque
393       *         (<a href="../Collection.html#optional-restrictions">optional</a>)
# Line 402 | Line 402 | public interface BlockingDeque<E> extend
402       * Inserts the specified element into the queue represented by this deque
403       * (in other words, at the tail of this deque) if it is possible to do so
404       * immediately without violating capacity restrictions, returning
405 <     * <tt>true</tt> upon success and throwing an
406 <     * <tt>IllegalStateException</tt> if no space is currently available.
405 >     * {@code true} upon success and throwing an
406 >     * {@code IllegalStateException} if no space is currently available.
407       * When using a capacity-restricted deque, it is generally preferable to
408       * use {@link #offer(Object) offer}.
409       *
# Line 423 | Line 423 | public interface BlockingDeque<E> extend
423       * Inserts the specified element into the queue represented by this deque
424       * (in other words, at the tail of this deque) if it is possible to do so
425       * immediately without violating capacity restrictions, returning
426 <     * <tt>true</tt> upon success and <tt>false</tt> if no space is currently
426 >     * {@code true} upon success and {@code false} if no space is currently
427       * available.  When using a capacity-restricted deque, this method is
428       * generally preferable to the {@link #add} method, which can fail to
429       * insert an element only by throwing an exception.
# Line 465 | Line 465 | public interface BlockingDeque<E> extend
465       * {@link #offerLast(Object,long,TimeUnit) offerLast}.
466       *
467       * @param e the element to add
468 <     * @return <tt>true</tt> if the element was added to this deque, else
469 <     *         <tt>false</tt>
468 >     * @return {@code true} if the element was added to this deque, else
469 >     *         {@code false}
470       * @throws InterruptedException {@inheritDoc}
471       * @throws ClassCastException if the class of the specified element
472       *         prevents it from being added to this deque
# Line 493 | Line 493 | public interface BlockingDeque<E> extend
493      /**
494       * Retrieves and removes the head of the queue represented by this deque
495       * (in other words, the first element of this deque), or returns
496 <     * <tt>null</tt> if this deque is empty.
496 >     * {@code null} if this deque is empty.
497       *
498       * <p>This method is equivalent to {@link #pollFirst()}.
499       *
500 <     * @return the head of this deque, or <tt>null</tt> if this deque is empty
500 >     * @return the head of this deque, or {@code null} if this deque is empty
501       */
502      E poll();
503  
# Line 521 | Line 521 | public interface BlockingDeque<E> extend
521       * <p>This method is equivalent to
522       * {@link #pollFirst(long,TimeUnit) pollFirst}.
523       *
524 <     * @return the head of this deque, or <tt>null</tt> if the
524 >     * @return the head of this deque, or {@code null} if the
525       *         specified waiting time elapses before an element is available
526       * @throws InterruptedException if interrupted while waiting
527       */
# Line 544 | Line 544 | public interface BlockingDeque<E> extend
544      /**
545       * Retrieves, but does not remove, the head of the queue represented by
546       * this deque (in other words, the first element of this deque), or
547 <     * returns <tt>null</tt> if this deque is empty.
547 >     * returns {@code null} if this deque is empty.
548       *
549       * <p>This method is equivalent to {@link #peekFirst() peekFirst}.
550       *
551 <     * @return the head of this deque, or <tt>null</tt> if this deque is empty
551 >     * @return the head of this deque, or {@code null} if this deque is empty
552       */
553      E peek();
554  
555      /**
556       * Removes the first occurrence of the specified element from this deque.
557       * If the deque does not contain the element, it is unchanged.
558 <     * More formally, removes the first element <tt>e</tt> such that
559 <     * <tt>o.equals(e)</tt> (if such an element exists).
560 <     * Returns <tt>true</tt> if this deque contained the specified element
558 >     * More formally, removes the first element {@code e} such that
559 >     * {@code o.equals(e)} (if such an element exists).
560 >     * Returns {@code true} if this deque contained the specified element
561       * (or equivalently, if this deque changed as a result of the call).
562       *
563       * <p>This method is equivalent to
564       * {@link #removeFirstOccurrence(Object) removeFirstOccurrence}.
565       *
566       * @param o element to be removed from this deque, if present
567 <     * @return <tt>true</tt> if this deque changed as a result of the call
567 >     * @return {@code true} if this deque changed as a result of the call
568       * @throws ClassCastException if the class of the specified element
569       *         is incompatible with this deque
570       *         (<a href="../Collection.html#optional-restrictions">optional</a>)
# Line 574 | Line 574 | public interface BlockingDeque<E> extend
574      boolean remove(Object o);
575  
576      /**
577 <     * Returns <tt>true</tt> if this deque contains the specified element.
578 <     * More formally, returns <tt>true</tt> if and only if this deque contains
579 <     * at least one element <tt>e</tt> such that <tt>o.equals(e)</tt>.
577 >     * Returns {@code true} if this deque contains the specified element.
578 >     * More formally, returns {@code true} if and only if this deque contains
579 >     * at least one element {@code e} such that {@code o.equals(e)}.
580       *
581       * @param o object to be checked for containment in this deque
582 <     * @return <tt>true</tt> if this deque contains the specified element
582 >     * @return {@code true} if this deque contains the specified element
583       * @throws ClassCastException if the class of the specified element
584       *         is incompatible with this deque
585       *         (<a href="../Collection.html#optional-restrictions">optional</a>)

Diff Legend

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