Module java.base
Package java.util.concurrent

Interface BlockingDeque<E>

类型参数:
E - 此双端队列中保存的元素的类型
所有超接口:
BlockingQueue<E>, Collection<E>, Deque<E>, Iterable<E>, Queue<E>, SequencedCollection<E>
所有已知实现类:
LinkedBlockingDeque
public interface BlockingDeque<E> extends BlockingQueue<E>, Deque<E>
一个支持阻塞操作的双端队列，当检索元素时等待队列变为非空，并在存储元素时等待队列中有空间可用。

BlockingDeque 方法有四种形式，处理无法立即满足的操作，但可能在将来某个时刻满足：一种会抛出异常，第二种返回特殊值（null或false，取决于操作），第三种会无限期地阻塞当前线程，直到操作成功，第四种会在放弃之前在给定的最大时间限制内阻塞。这些方法总结在以下表中：

BlockingDeque 方法摘要
第一个元素（头部）
抛出异常 特殊值 阻塞 超时
插入 addFirst(e) offerFirst(e) putFirst(e) offerFirst(e, time, unit)
移除 removeFirst() pollFirst() takeFirst() pollFirst(time, unit)
检查 getFirst() peekFirst() 不适用 不适用
最后一个元素（尾部）
抛出异常 特殊值 阻塞 超时
插入 addLast(e) offerLast(e) putLast(e) offerLast(e, time, unit)
移除 removeLast() pollLast() takeLast() pollLast(time, unit)
检查 getLast() peekLast() 不适用 不适用

与任何BlockingQueue一样，BlockingDeque是线程安全的，不允许空元素，并且可能（或可能不）受到容量限制。

BlockingDeque 实现可以直接用作FIFO BlockingQueue。从BlockingQueue接口继承的方法与BlockingDeque方法完全等效，如下表所示：

BlockingQueue 和 BlockingDeque 方法比较
BlockingQueue 方法 等效的 BlockingDeque 方法
插入 add(e) addLast(e)
offer(e) offerLast(e)
put(e) putLast(e)
offer(e, time, unit) offerLast(e, time, unit)
移除 remove() removeFirst()
poll() pollFirst()
take() takeFirst()
poll(time, unit) pollFirst(time, unit)
检查 element() getFirst()
peek() peekFirst()

内存一致性效果: 与其他并发集合一样，在一个线程中将对象放入BlockingDeque之前的操作在另一个线程中访问或移除该元素之后的操作之前发生。

此接口是Java集合框架的成员。

自 JDK 版本:
1.6

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    add(E e)
    如果可以立即在不违反容量限制的情况下将指定的元素插入此双端队列所表示的队列（换句话说，在此双端队列的尾部），则返回true表示成功，并在当前没有可用空间时抛出IllegalStateException。
    void
    addFirst(E e)
    如果可以立即在不违反容量限制的情况下将指定的元素插入此双端队列的前面，则抛出IllegalStateException，表示当前没有可用空间。
    void
    addLast(E e)
    如果可以立即在不违反容量限制的情况下将指定的元素插入此双端队列的末尾，则抛出IllegalStateException，表示当前没有可用空间。
    boolean
    contains(Object o)
    如果此双端队列包含指定的元素，则返回true。
    E
    element()
    检索但不移除由此双端队列表示的队列的头部（换句话说，此双端队列的第一个元素）。
    Iterator<E>
    iterator()
    返回此双端队列中元素的迭代器，按正确顺序。
    boolean
    offer(E e)
    如果可以立即在不违反容量限制的情况下将指定的元素插入此双端队列所表示的队列（换句话说，在此双端队列的尾部），则返回true表示成功，如果当前没有可用空间，则返回false。
    boolean
    offer(E e, long timeout, TimeUnit unit)
    如果可以立即在不违反容量限制的情况下将指定的元素插入此双端队列所表示的队列（换句话说，在此双端队列的尾部），则等待指定的等待时间，直到有空间可用为止。
    boolean
    offerFirst(E e)
    在不违反容量限制的情况下立即将指定的元素插入到此双端队列的前面，如果当前没有可用空间，则返回true成功，如果没有可用空间则返回false。
    boolean
    offerFirst(E e, long timeout, TimeUnit unit)
    在此双端队列的前面插入指定的元素，如果需要的话，等待指定的等待时间以便空间变得可用。
    boolean
    offerLast(E e)
    在不违反容量限制的情况下立即将指定的元素插入到此双端队列的末尾，如果当前没有可用空间，则返回true成功，如果没有可用空间则返回false。
    boolean
    offerLast(E e, long timeout, TimeUnit unit)
    在此双端队列的末尾插入指定的元素，如果需要的话，等待指定的等待时间以便空间变得可用。
    E
    peek()
    检索但不移除由此双端队列表示的队列的头部（换句话说，此双端队列的第一个元素），如果此双端队列为空，则返回null。
    E
    poll()
    检索并移除由此双端队列表示的队列的头部（换句话说，此双端队列的第一个元素），如果此双端队列为空，则返回null。
    E
    poll(long timeout, TimeUnit unit)
    检索并移除由此双端队列表示的队列的头部（换句话说，此双端队列的第一个元素），如果需要的话，等待指定的等待时间以便一个元素变得可用。
    E
    pollFirst(long timeout, TimeUnit unit)
    检索并移除此双端队列的第一个元素，如果需要的话，等待指定的等待时间以便一个元素变得可用。
    E
    pollLast(long timeout, TimeUnit unit)
    检索并移除此双端队列的最后一个元素，如果需要的话，等待指定的等待时间以便一个元素变得可用。
    void
    push(E e)
    如果可以立即在不违反容量限制的情况下将元素推送到此双端队列表示的堆栈（换句话说，在此双端队列的头部），则将元素推送到堆栈，如果当前没有可用空间，则抛出IllegalStateException。
    void
    put(E e)
    将指定的元素插入到此双端队列表示的队列中（换句话说，在此双端队列的尾部），如果需要的话等待空间变得可用。
    void
    putFirst(E e)
    在此双端队列的前面插入指定的元素，如果需要的话等待空间变得可用。
    void
    putLast(E e)
    在此双端队列的末尾插入指定的元素，如果需要的话等待空间变得可用。
    E
    remove()
    检索并移除由此双端队列表示的队列的头部（换句话说，此双端队列的第一个元素）。
    boolean
    remove(Object o)
    从此双端队列中删除指定元素的第一个出现。
    boolean
    removeFirstOccurrence(Object o)
    从此双端队列中删除指定元素的第一个出现。
    boolean
    removeLastOccurrence(Object o)
    从此双端队列中删除指定元素的最后一个出现。
    int
    size()
    返回此双端队列中的元素数量。
    E
    take()
    检索并移除由此双端队列表示的队列的头部（换句话说，此双端队列的第一个元素），如果需要的话一直等待直到一个元素变得可用。
    E
    takeFirst()
    检索并移除此双端队列的第一个元素，如果需要的话一直等待直到一个元素变得可用。
    E
    takeLast()
    检索并移除此双端队列的最后一个元素，如果需要的话一直等待直到一个元素变得可用。

    Methods declared in interface java.util.concurrent.BlockingQueue

    drainTo, drainTo, remainingCapacity

    Methods declared in interface java.util.Collection

    clear, containsAll, equals, hashCode, isEmpty, parallelStream, removeAll, removeIf, retainAll, spliterator, stream, toArray, toArray, toArray

    Methods declared in interface java.util.Deque

    addAll, descendingIterator, getFirst, getLast, peekFirst, peekLast, pollFirst, pollLast, pop, removeFirst, removeLast, reversed

    Methods declared in interface java.lang.Iterable

    forEach

  • Method Details

    • addFirst

      void addFirst(E e)
      如果可以立即在不违反容量限制的情况下将指定的元素插入到此双端队列的前面，则将元素插入到前面，如果当前没有可用空间，则抛出IllegalStateException。在使用容量受限制的双端队列时，通常最好使用offerFirst。
      指定者:
      addFirst 在接口 Deque<E>
      指定者:
      addFirst 在接口 SequencedCollection<E>
      参数:
      e - 要添加的元素
      抛出:
      IllegalStateException - 如果由于容量限制而此时无法添加元素
      ClassCastException - 如果指定元素的类别阻止将其添加到此双端队列中
      NullPointerException - 如果指定的元素为null
      IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此双端队列中

    • addLast

      void addLast(E e)
      如果可以立即在不违反容量限制的情况下将指定的元素插入到此双端队列的末尾，则将元素插入到末尾，如果当前没有可用空间，则抛出IllegalStateException。在使用容量受限制的双端队列时，通常最好使用offerLast。
      指定者:
      addLast 在接口 Deque<E>
      指定者:
      addLast 在接口 SequencedCollection<E>
      参数:
      e - 要添加的元素
      抛出:
      IllegalStateException - 如果由于容量限制而此时无法添加元素
      ClassCastException - 如果指定元素的类别阻止将其添加到此双端队列中
      NullPointerException - 如果指定的元素为null
      IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此双端队列中

    • offerFirst

      boolean offerFirst(E e)
      如果可以立即在不违反容量限制的情况下将指定的元素插入到此双端队列的前面，则将元素插入到前面，如果当前没有可用空间，则返回true成功，如果没有可用空间则返回false。在使用容量受限制的双端队列时，通常最好使用addFirst方法，该方法只通过抛出异常来失败地插入元素。
      指定者:
      offerFirst 在接口 Deque<E>
      参数:
      e - 要添加的元素
      返回:
      true如果元素已添加到此双端队列，否则false
      抛出:
      ClassCastException - 如果指定元素的类别阻止将其添加到此双端队列中
      NullPointerException - 如果指定的元素为null
      IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此双端队列中

    • offerLast

      boolean offerLast(E e)
      如果可以立即在不违反容量限制的情况下将指定的元素插入到此双端队列的末尾，则将元素插入到末尾，如果当前没有可用空间，则返回true成功，如果没有可用空间则返回false。在使用容量受限制的双端队列时，通常最好使用addLast方法，该方法只通过抛出异常来失败地插入元素。
      指定者:
      offerLast 在接口 Deque<E>
      参数:
      e - 要添加的元素
      返回:
      true如果元素已添加到此双端队列，否则false
      抛出:
      ClassCastException - 如果指定元素的类别阻止将其添加到此双端队列中
      NullPointerException - 如果指定的元素为null
      IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此双端队列中

    • putFirst

      void putFirst(E e) throws InterruptedException
      在此双端队列的前面插入指定的元素，如果需要的话等待空间变得可用。
      参数:
      e - 要添加的元素
      抛出:
      InterruptedException - 如果在等待时被中断
      ClassCastException - 如果指定元素的类别阻止将其添加到此双端队列中
      NullPointerException - 如果指定的元素为null
      IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此双端队列中

    • putLast

      void putLast(E e) throws InterruptedException
      在此双端队列的末尾插入指定的元素，如果需要的话等待空间变得可用。
      参数:
      e - 要添加的元素
      抛出:
      InterruptedException - 如果在等待时被中断
      ClassCastException - 如果指定元素的类别阻止将其添加到此双端队列中
      NullPointerException - 如果指定元素为null
      IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此双端队列中

    • offerFirst

      boolean offerFirst(E e, long timeout, TimeUnit unit) throws InterruptedException
      在此双端队列的前端插入指定的元素，如果需要等待空间变得可用，则最多等待指定的等待时间。
      参数:
      e - 要添加的元素
      timeout - 等待放弃之前等待的时间长度，以unit为单位
      unit - 用于解释timeout参数的TimeUnit
      返回:
      如果成功，则返回true，如果指定的等待时间在空间可用之前过去，则返回false
      抛出:
      InterruptedException - 如果在等待时被中断
      ClassCastException - 如果指定元素的类别阻止将其添加到此双端队列中
      NullPointerException - 如果指定元素为null
      IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此双端队列中

    • offerLast

      boolean offerLast(E e, long timeout, TimeUnit unit) throws InterruptedException
      在此双端队列的末尾插入指定的元素，如果需要等待空间变得可用，则最多等待指定的等待时间。
      参数:
      e - 要添加的元素
      timeout - 等待放弃之前等待的时间长度，以unit为单位
      unit - 用于解释timeout参数的TimeUnit
      返回:
      如果成功，则返回true，如果指定的等待时间在空间可用之前过去，则返回false
      抛出:
      InterruptedException - 如果在等待时被中断
      ClassCastException - 如果指定元素的类别阻止将其添加到此双端队列中
      NullPointerException - 如果指定元素为null
      IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此双端队列中

    • takeFirst

      E takeFirst() throws InterruptedException
      检索并移除此双端队列的第一个元素，如果需要，等待直到有元素可用。
      返回:
      此双端队列的头部
      抛出:
      InterruptedException - 如果在等待时被中断

    • takeLast

      E takeLast() throws InterruptedException
      检索并移除此双端队列的最后一个元素，如果需要，等待直到有元素可用。
      返回:
      此双端队列的尾部
      抛出:
      InterruptedException - 如果在等待时被中断

    • pollFirst

      E pollFirst(long timeout, TimeUnit unit) throws InterruptedException
      检索并移除此双端队列的第一个元素，如果需要，等待直到有元素可用，最多等待指定的等待时间。
      参数:
      timeout - 等待放弃之前等待的时间长度，以unit为单位
      unit - 用于解释timeout参数的TimeUnit
      返回:
      此双端队列的头部，如果指定的等待时间在元素可用之前过去，则返回null
      抛出:
      InterruptedException - 如果在等待时被中断

    • pollLast

      E pollLast(long timeout, TimeUnit unit) throws InterruptedException
      检索并移除此双端队列的最后一个元素，如果需要，等待直到有元素可用，最多等待指定的等待时间。
      参数:
      timeout - 等待放弃之前等待的时间长度，以unit为单位
      unit - 用于解释timeout参数的TimeUnit
      返回:
      此双端队列的尾部，如果指定的等待时间在元素可用之前过去，则返回null
      抛出:
      InterruptedException - 如果在等待时被中断

    • removeFirstOccurrence

      boolean removeFirstOccurrence(Object o)
      从此双端队列中移除指定元素的第一个出现。如果双端队列不包含该元素，则保持不变。更正式地说，删除第一个元素e，使得o.equals(e)（如果存在这样的元素）。如果此双端队列包含指定的元素，则返回true（或者等效地，如果此双端队列由于调用而更改）。
      指定者:
      removeFirstOccurrence 在接口 Deque<E>
      参数:
      o - 如果存在，则从此双端队列中移除的元素
      返回:
      如果作为此调用的结果移除了一个元素，则返回true
      抛出:
      ClassCastException - 如果指定元素的类别与此双端队列不兼容（可选）
      NullPointerException - 如果指定元素为null（可选）

    • removeLastOccurrence

      boolean removeLastOccurrence(Object o)
      从此双端队列中移除指定元素的最后一个出现。如果双端队列不包含该元素，则保持不变。更正式地说，删除最后一个元素e，使得o.equals(e)（如果存在这样的元素）。如果此双端队列包含指定的元素，则返回true（或者等效地，如果此双端队列由于调用而更改）。
      指定者:
      removeLastOccurrence 在接口 Deque<E>
      参数:
      o - 如果存在，则从此双端队列中移除的元素
      返回:
      如果作为此调用的结果移除了一个元素，则返回true
      抛出:
      ClassCastException - 如果指定元素的类别与此双端队列不兼容（可选）
      NullPointerException - 如果指定元素为null（可选）

    • add

      boolean add(E e)
      如果可以立即这样做而不违反容量限制，则将指定的元素插入到此双端队列表示的队列中（换句话说，在此双端队列的尾部），成功时返回true，如果当前没有空间可用则抛出IllegalStateException。在使用容量受限的双端队列时，通常最好使用offer。

      此方法等效于addLast。

      指定者:
      add 在接口 BlockingQueue<E>中
      指定者:
      add 在接口 Collection<E>中
      指定者:
      add 在接口 Deque<E>中
      指定者:
      add 在接口 Queue<E>中
      参数:
      e - 要添加的元素
      返回值:
      true (由Collection.add(E)指定)
      抛出:
      IllegalStateException - 如果由于容量限制而无法立即添加元素
      ClassCastException - 如果指定元素的类别阻止将其添加到此双端队列中
      NullPointerException - 如果指定元素为null
      IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此双端队列中

    • offer

      boolean offer(E e)
      将指定的元素插入到此双端队列表示的队列中（换句话说，在此双端队列的尾部），如果可以立即这样做而不违反容量限制，则在成功时返回true，如果当前没有可用空间则返回false。在使用容量受限的双端队列时，此方法通常优于add(E)方法，后者只能通过抛出异常来失败地插入元素。

      此方法等效于offerLast。

      指定者:
      offer 在接口 BlockingQueue<E>中
      指定者:
      offer 在接口 Deque<E>中
      指定者:
      offer 在接口 Queue<E>中
      参数:
      e - 要添加的元素
      返回值:
      如果元素已添加到此队列，则返回true，否则返回false
      抛出:
      ClassCastException - 如果指定元素的类别阻止将其添加到此双端队列中
      NullPointerException - 如果指定元素为null
      IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此双端队列中

    • put

      void put(E e) throws InterruptedException
      将指定的元素插入到此双端队列表示的队列中（换句话说，在此双端队列的尾部），如有必要，等待空间变得可用。

      此方法等效于putLast。

      指定者:
      put 在接口 BlockingQueue<E>中
      参数:
      e - 要添加的元素
      抛出:
      InterruptedException - 如果在等待时被中断
      ClassCastException - 如果指定元素的类别阻止将其添加到此双端队列中
      NullPointerException - 如果指定元素为null
      IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此双端队列中

    • offer

      boolean offer(E e, long timeout, TimeUnit unit) throws InterruptedException
      将指定的元素插入到此双端队列表示的队列中（换句话说，在此双端队列的尾部），如有必要，等待指定的等待时间以使空间变得可用。

      此方法等效于offerLast。

      指定者:
      offer 在接口 BlockingQueue<E>中
      参数:
      e - 要添加的元素
      timeout - 在unit单位内等待放弃的时间
      unit - 一个TimeUnit，用于解释timeout参数
      返回值:
      如果元素已添加到此双端队列，则返回true，否则返回false
      抛出:
      InterruptedException - 如果在等待时被中断
      ClassCastException - 如果指定元素的类别阻止将其添加到此双端队列中
      NullPointerException - 如果指定元素为null
      IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此双端队列中

    • remove

      E remove()
      检索并移除此双端队列表示的队列的头部（换句话说，此双端队列的第一个元素）。此方法与poll()的不同之处仅在于，如果此双端队列为空，则会抛出异常。

      此方法等效于removeFirst。

      指定者:
      remove 在接口 Deque<E>中
      指定者:
      remove 在接口 Queue<E>中
      返回值:
      此双端队列表示的队列的头部
      抛出:
      NoSuchElementException - 如果此双端队列为空

    • poll

      E poll()
      检索并移除此双端队列表示的队列的头部（换句话说，此双端队列的第一个元素），如果此双端队列为空则返回null。

      此方法等效于Deque.pollFirst()。

      指定者:
      poll 在接口 Deque<E>中
      指定者:
      poll 在接口 Queue<E>中
      返回值:
      此双端队列的头部，如果此双端队列为空则返回null

    • take

      E take() throws InterruptedException
      检索并移除此双端队列表示的队列的头部（换句话说，此双端队列的第一个元素），如有必要，等待直到有元素可用。

      此方法等效于takeFirst。

      指定者:
      take 在接口 BlockingQueue<E>中
      返回值:
      此双端队列的头部
      抛出:
      InterruptedException - 如果在等待时被中断

    • poll

      E poll(long timeout, TimeUnit unit) throws InterruptedException
      检索并移除此双端队列表示的队列的头部（换句话说，此双端队列的第一个元素），如有必要，等待指定的等待时间直到有元素可用。

      此方法等效于pollFirst。

      指定者:
      poll 在接口 BlockingQueue<E>中
      参数:
      timeout - 在单位unit中等待多长时间后放弃
      unit - 用于解释timeout参数的TimeUnit
      返回值:
      此双端队列的头部，如果在元素可用之前经过指定的等待时间，则返回null
      抛出:
      InterruptedException - 如果在等待时被中断

    • element

      E element()
      检索但不移除由此双端队列表示的队列的头部（换句话说，此双端队列的第一个元素）。此方法与peek的不同之处仅在于，如果此双端队列为空，则会抛出异常。

      此方法等效于getFirst。

      指定者:
      element 在接口 Deque<E>中
      指定者:
      element 在接口 Queue<E>中
      返回值:
      此双端队列的头部
      抛出:
      NoSuchElementException - 如果此双端队列为空

    • peek

      E peek()
      检索但不移除由此双端队列表示的队列的头部（换句话说，此双端队列的第一个元素），如果此双端队列为空，则返回null。

      此方法等效于peekFirst。

      指定者:
      peek 在接口 Deque<E>中
      指定者:
      peek 在接口 Queue<E>中
      返回值:
      此双端队列的头部，如果此双端队列为空，则返回null

    • remove

      boolean remove(Object o)
      从此双端队列中删除指定元素的第一个出现。如果双端队列不包含该元素，则保持不变。更正式地说，删除第一个元素e，使得o.equals(e)（如果存在这样的元素）。如果此双端队列包含指定的元素，则返回true（或者等效地，如果此双端队列由于调用而更改，则返回true）。

      此方法等效于removeFirstOccurrence。

      指定者:
      remove 在接口 BlockingQueue<E>中
      指定者:
      remove 在接口 Collection<E>中
      指定者:
      remove 在接口 Deque<E>中
      参数:
      o - 如果存在，则从此双端队列中删除的元素
      返回值:
      如果此双端队列由于调用而更改，则返回true
      抛出:
      ClassCastException - 如果指定元素的类与此双端队列不兼容（可选）
      NullPointerException - 如果指定元素为null（可选）

    • contains

      boolean contains(Object o)
      如果此双端队列包含指定元素，则返回true。更正式地说，如果此双端队列包含至少一个元素e，使得o.equals(e)，则返回true。
      指定者:
      contains 在接口 BlockingQueue<E>中
      指定者:
      contains 在接口 Collection<E>中
      指定者:
      contains 在接口 Deque<E>中
      参数:
      o - 要在此双端队列中检查包含性的对象
      返回值:
      如果此双端队列包含指定元素，则返回true
      抛出:
      ClassCastException - 如果指定元素的类与此双端队列不兼容（可选）
      NullPointerException - 如果指定元素为null（可选）

    • size

      int size()
      返回此双端队列中的元素数量。
      指定者:
      size 在接口 Collection<E>中
      指定者:
      size 在接口 Deque<E>中
      返回值:
      此双端队列中的元素数量

    • iterator

      Iterator<E> iterator()
      返回此双端队列中元素的迭代器，按正确顺序返回元素。元素将按从第一个（头部）到最后一个（尾部）的顺序返回。
      指定者:
      iterator 在接口 Collection<E>中
      指定者:
      iterator 在接口 Deque<E>中
      指定者:
      iterator 在接口 Iterable<E>中
      返回值:
      按正确顺序返回此双端队列中的元素的迭代器

    • push

      void push(E e)
      如果可能立即将元素推送到由此双端队列表示的堆栈（换句话说，在此双端队列的头部），则将元素推送到堆栈，如果当前没有空间可用，则抛出IllegalStateException。

      此方法等效于addFirst。

      指定者:
      push 在接口 Deque<E>中
      参数:
      e - 要推送的元素
      抛出:
      IllegalStateException - 如果由于容量限制，此时无法添加元素
      ClassCastException - 如果指定元素的类阻止将其添加到此双端队列
      NullPointerException - 如果指定元素为null
      IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此双端队列