Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## edu.emory.mathcs.backport.java.util.concurrent
Interface BlockingDeque

All Superinterfaces:
  BlockingQueue, java.util.Collection, Deque, Queue

All Known Implementing Classes:
  LinkedBlockingDeque

public interface BlockingDeque
extends BlockingQueue, Deque

A `Deque` that additionally supports blocking operations that wait for the deque to become non-empty when retrieving an element, and wait for space to become available in the deque when storing an element.

`BlockingDeque` methods come in four forms, with different ways of handling operations that cannot be satisfied immediately, but may be satisfied at some point in the future: one throws an exception, the second returns a special value (either `null` or `false`, depending on the operation), the third blocks the current thread indefinitely until the operation can succeed, and the fourth blocks for only a given maximum time limit before giving up. These methods are summarized in the following table:

First Element (Head)
| Throws exception | Special value | Blocks | Times out
Insert | `addFirst(e)` | `offerFirst(e)` | `putFirst(e)` | `offerFirst(e, time, unit)`
Remove | `removeFirst()` | `pollFirst()` | `takeFirst()` | `pollFirst(time, unit)`
Examine | `getFirst()` | `peekFirst()` | not applicable | not applicable
Last Element (Tail)
| Throws exception | Special value | Blocks | Times out
Insert | `addLast(e)` | `offerLast(e)` | `putLast(e)` | `offerLast(e, time, unit)`
Remove | `removeLast()` | `pollLast()` | `takeLast()` | `pollLast(time, unit)`
Examine | `getLast()` | `peekLast()` | not applicable | not applicable

Like any `BlockingQueue`, a `BlockingDeque` is thread safe, does not permit null elements, and may (or may not) be capacity-constrained.

A `BlockingDeque` implementation may be used directly as a FIFO `BlockingQueue`. The methods inherited from the `BlockingQueue` interface are precisely equivalent to `BlockingDeque` methods as indicated in the following table:

`BlockingQueue` Method | Equivalent `BlockingDeque` Method
Insert
`add(e)` | `addLast(e)`
`offer(e)` | `offerLast(e)`
`put(e)` | `putLast(e)`
`offer(e, time, unit)` | `offerLast(e, time, unit)`
Remove
`remove()` | `removeFirst()`
`poll()` | `pollFirst()`
`take()` | `takeFirst()`
`poll(time, unit)` | `pollFirst(time, unit)`
Examine
`element()` | `getFirst()`
`peek()` | `peekFirst()`

Memory consistency effects: As with other concurrent collections, actions in a thread prior to placing an object into a happen-before actions subsequent to the access or removal of that element from the in another thread.

This interface is a member of the Java Collections Framework.

Since:
  1.6
Author:
  Doug Lea

Method Summary
`boolean` | `add(java.lang.Object e)` Inserts the specified element into the queue represented by this deque (in other words, at the tail of this deque) if it is possible to do so immediately without violating capacity restrictions, returning `true` upon success and throwing an `IllegalStateException` if no space is currently available.
`void` | `addFirst(java.lang.Object e)` Inserts the specified element at the front of this deque if it is possible to do so immediately without violating capacity restrictions, throwing an `IllegalStateException` if no space is currently available.
`void` | `addLast(java.lang.Object e)` Inserts the specified element at the end of this deque if it is possible to do so immediately without violating capacity restrictions, throwing an `IllegalStateException` if no space is currently available.
`boolean` | `contains(java.lang.Object o)` Returns `true` if this deque contains the specified element.
`java.lang.Object` | `element()` Retrieves, but does not remove, the head of the queue represented by this deque (in other words, the first element of this deque).
`java.util.Iterator` | `iterator()` Returns an iterator over the elements in this deque in proper sequence.
`boolean` | `offer(java.lang.Object e)` Inserts the specified element into the queue represented by this deque (in other words, at the tail of this deque) if it is possible to do so immediately without violating capacity restrictions, returning `true` upon success and `false` if no space is currently available.
`boolean` | `offer(java.lang.Object e, long timeout, TimeUnit unit)` Inserts the specified element into the queue represented by this deque (in other words, at the tail of this deque), waiting up to the specified wait time if necessary for space to become available.
`boolean` | `offerFirst(java.lang.Object e)` Inserts the specified element at the front of this deque if it is possible to do so immediately without violating capacity restrictions, returning `true` upon success and `false` if no space is currently available.
`boolean` | `offerFirst(java.lang.Object e, long timeout, TimeUnit unit)` Inserts the specified element at the front of this deque, waiting up to the specified wait time if necessary for space to become available.
`boolean` | `offerLast(java.lang.Object e)` Inserts the specified element at the end of this deque if it is possible to do so immediately without violating capacity restrictions, returning `true` upon success and `false` if no space is currently available.
`boolean` | `offerLast(java.lang.Object e, long timeout, TimeUnit unit)` Inserts the specified element at the end of this deque, waiting up to the specified wait time if necessary for space to become available.
`java.lang.Object` | `peek()` Retrieves, but does not remove, the head of the queue represented by this deque (in other words, the first element of this deque), or returns `null` if this deque is empty.
`java.lang.Object` | `poll()` Retrieves and removes the head of the queue represented by this deque (in other words, the first element of this deque), or returns `null` if this deque is empty.
`java.lang.Object` | `poll(long timeout, TimeUnit unit)` Retrieves and removes the head of the queue represented by this deque (in other words, the first element of this deque), waiting up to the specified wait time if necessary for an element to become available.
`java.lang.Object` | `pollFirst(long timeout, TimeUnit unit)` Retrieves and removes the first element of this deque, waiting up to the specified wait time if necessary for an element to become available.
`java.lang.Object` | `pollLast(long timeout, TimeUnit unit)` Retrieves and removes the last element of this deque, waiting up to the specified wait time if necessary for an element to become available.
`void` | `push(java.lang.Object e)` Pushes an element onto the stack represented by this deque.
`void` | `put(java.lang.Object e)` Inserts the specified element into the queue represented by this deque (in other words, at the tail of this deque), waiting if necessary for space to become available.
`void` | `putFirst(java.lang.Object e)` Inserts the specified element at the front of this deque, waiting if necessary for space to become available.
`void` | `putLast(java.lang.Object e)` Inserts the specified element at the end of this deque, waiting if necessary for space to become available.
`java.lang.Object` | `remove()` Retrieves and removes the head of the queue represented by this deque (in other words, the first element of this deque).
`boolean` | `remove(java.lang.Object o)` Removes the first occurrence of the specified element from this deque.
`boolean` | `removeFirstOccurrence(java.lang.Object o)` Removes the first occurrence of the specified element from this deque.
`boolean` | `removeLastOccurrence(java.lang.Object o)` Removes the last occurrence of the specified element from this deque.
`int` | `size()` Returns the number of elements in this deque.
`java.lang.Object` | `take()` Retrieves and removes the head of the queue represented by this deque (in other words, the first element of this deque), waiting if necessary until an element becomes available.
`java.lang.Object` | `takeFirst()` Retrieves and removes the first element of this deque, waiting if necessary until an element becomes available.
`java.lang.Object` | `takeLast()` Retrieves and removes the last element of this deque, waiting if necessary until an element becomes available.

Methods inherited from interface edu.emory.mathcs.backport.java.util.concurrent.BlockingQueue
`drainTo, drainTo, remainingCapacity`

Methods inherited from interface java.util.Collection
`addAll, clear, containsAll, equals, hashCode, isEmpty, removeAll, retainAll, toArray, toArray`

Methods inherited from interface edu.emory.mathcs.backport.java.util.Deque
`descendingIterator, getFirst, getLast, peekFirst, peekLast, pollFirst, pollLast, pop, removeFirst, removeLast`

Method Detail

### addFirst

    public void addFirst(java.lang.Object e)

  Inserts the specified element at the front of this deque if it is possible to do so immediately without violating capacity restrictions, throwing an `IllegalStateException` if no space is currently available. When using a capacity-restricted deque, it is generally preferable to use `offerFirst`.

  Specified by:
    `addFirst` in interface `Deque`
  Parameters:
    `e` - the element to add
  Throws:
    `java.lang.IllegalStateException` - if the element cannot be added at this time due to capacity restrictions
    `java.lang.ClassCastException` - if the class of the specified element prevents it from being added to this deque
    `java.lang.NullPointerException` - if the specified element is null
    `java.lang.IllegalArgumentException` - if some property of the specified element prevents it from being added to this deque

### addLast

    public void addLast(java.lang.Object e)

  Inserts the specified element at the end of this deque if it is possible to do so immediately without violating capacity restrictions, throwing an `IllegalStateException` if no space is currently available. When using a capacity-restricted deque, it is generally preferable to use `offerLast`.

  Specified by:
    `addLast` in interface `Deque`
  Parameters:
    `e` - the element to add
  Throws:
    `java.lang.IllegalStateException` - if the element cannot be added at this time due to capacity restrictions
    `java.lang.ClassCastException` - if the class of the specified element prevents it from being added to this deque
    `java.lang.NullPointerException` - if the specified element is null
    `java.lang.IllegalArgumentException` - if some property of the specified element prevents it from being added to this deque

### offerFirst

    public boolean offerFirst(java.lang.Object e)

  Inserts the specified element at the front of this deque if it is possible to do so immediately without violating capacity restrictions, returning `true` upon success and `false` if no space is currently available. When using a capacity-restricted deque, this method is generally preferable to the `addFirst` method, which can fail to insert an element only by throwing an exception.

  Specified by:
    `offerFirst` in interface `Deque`
  Parameters:
    `e` - the element to add
  Returns:
    `true` if the element was added to this deque, else `false`
  Throws:
    `java.lang.ClassCastException` - if the class of the specified element prevents it from being added to this deque
    `java.lang.NullPointerException` - if the specified element is null
    `java.lang.IllegalArgumentException` - if some property of the specified element prevents it from being added to this deque

### offerLast

    public boolean offerLast(java.lang.Object e)

  Inserts the specified element at the end of this deque if it is possible to do so immediately without violating capacity restrictions, returning `true` upon success and `false` if no space is currently available. When using a capacity-restricted deque, this method is generally preferable to the `addLast` method, which can fail to insert an element only by throwing an exception.

  Specified by:
    `offerLast` in interface `Deque`
  Parameters:
    `e` - the element to add
  Returns:
    `true` if the element was added to this deque, else `false`
  Throws:
    `java.lang.ClassCastException` - if the class of the specified element prevents it from being added to this deque
    `java.lang.NullPointerException` - if the specified element is null
    `java.lang.IllegalArgumentException` - if some property of the specified element prevents it from being added to this deque

### putFirst

    public void putFirst(java.lang.Object e)
                  throws java.lang.InterruptedException

  Inserts the specified element at the front of this deque, waiting if necessary for space to become available.

  Parameters:
    `e` - the element to add
  Throws:
    `java.lang.InterruptedException` - if interrupted while waiting
    `java.lang.ClassCastException` - if the class of the specified element prevents it from being added to this deque
    `java.lang.NullPointerException` - if the specified element is null
    `java.lang.IllegalArgumentException` - if some property of the specified element prevents it from being added to this deque

### putLast

    public void putLast(java.lang.Object e)
                 throws java.lang.InterruptedException

  Inserts the specified element at the end of this deque, waiting if necessary for space to become available.

  Parameters:
    `e` - the element to add
  Throws:
    `java.lang.InterruptedException` - if interrupted while waiting
    `java.lang.ClassCastException` - if the class of the specified element prevents it from being added to this deque
    `java.lang.NullPointerException` - if the specified element is null
    `java.lang.IllegalArgumentException` - if some property of the specified element prevents it from being added to this deque

### offerFirst

    public boolean offerFirst(java.lang.Object e,
                              long timeout,
                              TimeUnit unit)
                       throws java.lang.InterruptedException

  Inserts the specified element at the front of this deque, waiting up to the specified wait time if necessary for space to become available.

  Parameters:
    `e` - the element to add
    `timeout` - how long to wait before giving up, in units of `unit`
    `unit` - a `TimeUnit` determining how to interpret the `timeout` parameter
  Returns:
    `true` if successful, or `false` if the specified waiting time elapses before space is available
  Throws:
    `java.lang.InterruptedException` - if interrupted while waiting
    `java.lang.ClassCastException` - if the class of the specified element prevents it from being added to this deque
    `java.lang.NullPointerException` - if the specified element is null
    `java.lang.IllegalArgumentException` - if some property of the specified element prevents it from being added to this deque

### offerLast

    public boolean offerLast(java.lang.Object e,
                             long timeout,
                             TimeUnit unit)
                      throws java.lang.InterruptedException

  Inserts the specified element at the end of this deque, waiting up to the specified wait time if necessary for space to become available.

  Parameters:
    `e` - the element to add
    `timeout` - how long to wait before giving up, in units of `unit`
    `unit` - a `TimeUnit` determining how to interpret the `timeout` parameter
  Returns:
    `true` if successful, or `false` if the specified waiting time elapses before space is available
  Throws:
    `java.lang.InterruptedException` - if interrupted while waiting
    `java.lang.ClassCastException` - if the class of the specified element prevents it from being added to this deque
    `java.lang.NullPointerException` - if the specified element is null
    `java.lang.IllegalArgumentException` - if some property of the specified element prevents it from being added to this deque

### takeFirst

    public java.lang.Object takeFirst()
                               throws java.lang.InterruptedException

  Retrieves and removes the first element of this deque, waiting if necessary until an element becomes available.

  Returns:
    the head of this deque
  Throws:
    `java.lang.InterruptedException` - if interrupted while waiting

### takeLast

    public java.lang.Object takeLast()
                              throws java.lang.InterruptedException

  Retrieves and removes the last element of this deque, waiting if necessary until an element becomes available.

  Returns:
    the tail of this deque
  Throws:
    `java.lang.InterruptedException` - if interrupted while waiting

### pollFirst

    public java.lang.Object pollFirst(long timeout,
                                      TimeUnit unit)
                               throws java.lang.InterruptedException

  Retrieves and removes the first element of this deque, waiting up to the specified wait time if necessary for an element to become available.

  Parameters:
    `timeout` - how long to wait before giving up, in units of `unit`
    `unit` - a `TimeUnit` determining how to interpret the `timeout` parameter
  Returns:
    the head of this deque, or `null` if the specified waiting time elapses before an element is available
  Throws:
    `java.lang.InterruptedException` - if interrupted while waiting

### pollLast

    public java.lang.Object pollLast(long timeout,
                                     TimeUnit unit)
                              throws java.lang.InterruptedException

  Retrieves and removes the last element of this deque, waiting up to the specified wait time if necessary for an element to become available.

  Parameters:
    `timeout` - how long to wait before giving up, in units of `unit`
    `unit` - a `TimeUnit` determining how to interpret the `timeout` parameter
  Returns:
    the tail of this deque, or `null` if the specified waiting time elapses before an element is available
  Throws:
    `java.lang.InterruptedException` - if interrupted while waiting

### removeFirstOccurrence

    public boolean removeFirstOccurrence(java.lang.Object o)

  Removes the first occurrence of the specified element from this deque. If the deque does not contain the element, it is unchanged. More formally, removes the first element `e` such that `o.equals(e)` (if such an element exists). Returns `true` if this deque contained the specified element (or equivalently, if this deque changed as a result of the call).

  Specified by:
    `removeFirstOccurrence` in interface `Deque`
  Parameters:
    `o` - element to be removed from this deque, if present
  Returns:
    `true` if an element was removed as a result of this call
  Throws:
    `java.lang.ClassCastException` - if the class of the specified element is incompatible with this deque (optional)
    `java.lang.NullPointerException` - if the specified element is null (optional)

### removeLastOccurrence

    public boolean removeLastOccurrence(java.lang.Object o)

  Removes the last occurrence of the specified element from this deque. If the deque does not contain the element, it is unchanged. More formally, removes the last element `e` such that `o.equals(e)` (if such an element exists). Returns `true` if this deque contained the specified element (or equivalently, if this deque changed as a result of the call).

  Specified by:
    `removeLastOccurrence` in interface `Deque`
  Parameters:
    `o` - element to be removed from this deque, if present
  Returns:
    `true` if an element was removed as a result of this call
  Throws:
    `java.lang.ClassCastException` - if the class of the specified element is incompatible with this deque (optional)
    `java.lang.NullPointerException` - if the specified element is null (optional)

### add

    public boolean add(java.lang.Object e)

  Inserts the specified element into the queue represented by this deque (in other words, at the tail of this deque) if it is possible to do so immediately without violating capacity restrictions, returning `true` upon success and throwing an `IllegalStateException` if no space is currently available. When using a capacity-restricted deque, it is generally preferable to use `offer`.

  This method is equivalent to `addLast`.

  Specified by:
    `add` in interface `BlockingQueue`
  Parameters:
    `e` - the element to add
  Returns:
    `true` (as specified by `Collection.add(java.lang.Object)`)
  Throws:
    `java.lang.IllegalStateException` - if the element cannot be added at this time due to capacity restrictions
    `java.lang.ClassCastException` - if the class of the specified element prevents it from being added to this deque
    `java.lang.NullPointerException` - if the specified element is null
    `java.lang.IllegalArgumentException` - if some property of the specified element prevents it from being added to this deque

### offer

    public boolean offer(java.lang.Object e)

  Inserts the specified element into the queue represented by this deque (in other words, at the tail of this deque) if it is possible to do so immediately without violating capacity restrictions, returning `true` upon success and `false` if no space is currently available. When using a capacity-restricted deque, this method is generally preferable to the `add(java.lang.Object)` method, which can fail to insert an element only by throwing an exception.

  This method is equivalent to `offerLast`.

  Specified by:
    `offer` in interface `BlockingQueue`
  Parameters:
    `e` - the element to add
  Returns:
    `true` if the element was added to this queue, else `false`
  Throws:
    `java.lang.ClassCastException` - if the class of the specified element prevents it from being added to this deque
    `java.lang.NullPointerException` - if the specified element is null
    `java.lang.IllegalArgumentException` - if some property of the specified element prevents it from being added to this deque

### put

    public void put(java.lang.Object e)
             throws java.lang.InterruptedException

  Inserts the specified element into the queue represented by this deque (in other words, at the tail of this deque), waiting if necessary for space to become available.

  This method is equivalent to `putLast`.

  Specified by:
    `put` in interface `BlockingQueue`
  Parameters:
    `e` - the element to add
  Throws:
    `java.lang.InterruptedException` - if interrupted while waiting
    `java.lang.ClassCastException` - if the class of the specified element prevents it from being added to this deque
    `java.lang.NullPointerException` - if the specified element is null
    `java.lang.IllegalArgumentException` - if some property of the specified element prevents it from being added to this deque

### offer

    public boolean offer(java.lang.Object e,
                         long timeout,
                         TimeUnit unit)
                  throws java.lang.InterruptedException

  Inserts the specified element into the queue represented by this deque (in other words, at the tail of this deque), waiting up to the specified wait time if necessary for space to become available.

  This method is equivalent to `offerLast`.

  Specified by:
    `offer` in interface `BlockingQueue`
  Parameters:
    `e` - the element to add
    `timeout` - how long to wait before giving up, in units of `unit`
    `unit` - a `TimeUnit` determining how to interpret the `timeout` parameter
  Returns:
    `true` if the element was added to this deque, else `false`
  Throws:
    `java.lang.InterruptedException` - if interrupted while waiting
    `java.lang.ClassCastException` - if the class of the specified element prevents it from being added to this deque
    `java.lang.NullPointerException` - if the specified element is null
    `java.lang.IllegalArgumentException` - if some property of the specified element prevents it from being added to this deque

### remove

    public java.lang.Object remove()

  Retrieves and removes the head of the queue represented by this deque (in other words, the first element of this deque). This method differs from `poll` only in that it throws an exception if this deque is empty.

  This method is equivalent to `removeFirst`.

  Specified by:
    `remove` in interface `Queue`
  Returns:
    the head of the queue represented by this deque
  Throws:
    `NoSuchElementException` - if this deque is empty

### poll

    public java.lang.Object poll()

  Retrieves and removes the head of the queue represented by this deque (in other words, the first element of this deque), or returns `null` if this deque is empty.

  This method is equivalent to `Deque.pollFirst()`.

  Specified by:
    `poll` in interface `Queue`
  Returns:
    the head of this deque, or `null` if this deque is empty

### take

    public java.lang.Object take()
                          throws java.lang.InterruptedException

  Retrieves and removes the head of the queue represented by this deque (in other words, the first element of this deque), waiting if necessary until an element becomes available.

  This method is equivalent to `takeFirst`.

  Specified by:
    `take` in interface `BlockingQueue`
  Returns:
    the head of this deque
  Throws:
    `java.lang.InterruptedException` - if interrupted while waiting

### poll

    public java.lang.Object poll(long timeout,
                                 TimeUnit unit)
                          throws java.lang.InterruptedException

  Retrieves and removes the head of the queue represented by this deque (in other words, the first element of this deque), waiting up to the specified wait time if necessary for an element to become available.

  This method is equivalent to `pollFirst`.

  Specified by:
    `poll` in interface `BlockingQueue`
  Parameters:
    `timeout` - how long to wait before giving up, in units of `unit`
    `unit` - a `TimeUnit` determining how to interpret the `timeout` parameter
  Returns:
    the head of this deque, or `null` if the specified waiting time elapses before an element is available
  Throws:
    `java.lang.InterruptedException` - if interrupted while waiting

### element

    public java.lang.Object element()

  Retrieves, but does not remove, the head of the queue represented by this deque (in other words, the first element of this deque). This method differs from `peek` only in that it throws an exception if this deque is empty.

  This method is equivalent to `getFirst`.

  Specified by:
    `element` in interface `Queue`
  Returns:
    the head of this deque
  Throws:
    `NoSuchElementException` - if this deque is empty

### peek

    public java.lang.Object peek()

  Retrieves, but does not remove, the head of the queue represented by this deque (in other words, the first element of this deque), or returns `null` if this deque is empty.

  This method is equivalent to `peekFirst`.

  Specified by:
    `peek` in interface `Queue`
  Returns:
    the head of this deque, or `null` if this deque is empty

### remove

    public boolean remove(java.lang.Object o)

  Removes the first occurrence of the specified element from this deque. If the deque does not contain the element, it is unchanged. More formally, removes the first element `e` such that `o.equals(e)` (if such an element exists). Returns `true` if this deque contained the specified element (or equivalently, if this deque changed as a result of the call).

  This method is equivalent to `removeFirstOccurrence`.

  Specified by:
    `remove` in interface `BlockingQueue`
  Parameters:
    `o` - element to be removed from this deque, if present
  Returns:
    `true` if this deque changed as a result of the call
  Throws:
    `java.lang.ClassCastException` - if the class of the specified element is incompatible with this deque (optional)
    `java.lang.NullPointerException` - if the specified element is null (optional)

### contains

    public boolean contains(java.lang.Object o)

  Returns `true` if this deque contains the specified element. More formally, returns `true` if and only if this deque contains at least one element `e` such that `o.equals(e)`.

  Specified by:
    `contains` in interface `BlockingQueue`
  Parameters:
    `o` - object to be checked for containment in this deque
  Returns:
    `true` if this deque contains the specified element
  Throws:
    `java.lang.ClassCastException` - if the class of the specified element is incompatible with this deque (optional)
    `java.lang.NullPointerException` - if the specified element is null (optional)

### size

    public int size()

  Returns the number of elements in this deque.

  Specified by:
    `size` in interface `java.util.Collection`
  Returns:
    the number of elements in this deque

### iterator

    public java.util.Iterator iterator()

  Returns an iterator over the elements in this deque in proper sequence. The elements will be returned in order from first (head) to last (tail).

  Specified by:
    `iterator` in interface `java.util.Collection`
  Returns:
    an iterator over the elements in this deque in proper sequence

### push

    public void push(java.lang.Object e)

  Pushes an element onto the stack represented by this deque. In other words, inserts the element at the front of this deque unless it would violate capacity restrictions.

  This method is equivalent to `addFirst`.

  Specified by:
    `push` in interface `Deque`
  Parameters:
    `e` - the element to push
  Throws:
    `java.lang.IllegalStateException` - if the element cannot be added at this time due to capacity restrictions
    `java.lang.ClassCastException` - if the class of the specified element prevents it from being added to this deque
    `java.lang.NullPointerException` - if the specified element is null
    `java.lang.IllegalArgumentException` - if some property of the specified element prevents it from being added to this deque

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD