模块 java.base
包 java.util.concurrent

接口 BlockingDeque<E>

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

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 发生在之前 之前线程中的操作是在另一个线程中从 BlockingDeque 访问或删除该元素之后的操作。

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

自从：
1.6

  • 方法总结

    修饰符和类型
    方法
    描述
    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()
    检索并删除此双端队列的最后一个元素，必要时等待元素可用。

    在接口 java.util.concurrent.BlockingQueue 中声明的方法

    drainTo, drainTo, remainingCapacity

    在接口 java.util.Collection 中声明的方法

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

    在接口 java.util.Deque 中声明的方法

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

    在接口 java.lang.Iterable 中声明的方法

    forEach

  • 方法详情

    • addFirst

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

    • addLast

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

    • offerFirst

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

    • offerLast

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

    • putFirst

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

    • putLast

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

    • offerFirst

      boolean offerFirst(E  e, long timeout, TimeUnit  unit) throws InterruptedException
      将指定的元素插入此双端队列的前面，如有必要，等待指定的等待时间以使空间可用。
      参数：
      e - 要添加的元素
      timeout - 放弃前等待多长时间，以 unit 为单位
      unit - 一个 TimeUnit 决定如何解释 timeout 参数
      返回：
      true 如果成功，或者 false 如果指定的等待时间在空间可用之前过去
      抛出：
      InterruptedException - 如果在等待时被打断
      ClassCastException - 如果指定元素的类阻止将其添加到此双端队列
      NullPointerException - 如果指定元素为空
      IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此双端队列

    • offerLast

      boolean offerLast(E  e, long timeout, TimeUnit  unit) throws InterruptedException
      在此双端队列的末尾插入指定的元素，如有必要，等待指定的等待时间以使空间可用。
      参数：
      e - 要添加的元素
      timeout - 放弃前等待多长时间，以 unit 为单位
      unit - 一个 TimeUnit 决定如何解释 timeout 参数
      返回：
      true 如果成功，或者 false 如果指定的等待时间在空间可用之前过去
      抛出：
      InterruptedException - 如果在等待时被打断
      ClassCastException - 如果指定元素的类阻止将其添加到此双端队列
      NullPointerException - 如果指定元素为空
      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 - 一个 TimeUnit 决定如何解释 timeout 参数
      返回：
      此双端队列的头部，或者 null 如果指定的等待时间在元素可用之前过去
      抛出：
      InterruptedException - 如果在等待时被打断

    • pollLast

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

    • removeFirstOccurrence

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

    • removeLastOccurrence

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

    • 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 - 如果指定元素为空
      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 - 如果指定元素为空
      IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此双端队列

    • put

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

      此方法等效于 putLast 。

      指定者：
      put 在接口 BlockingQueue<E> 中
      参数：
      e - 要添加的元素
      抛出：
      InterruptedException - 如果在等待时被打断
      ClassCastException - 如果指定元素的类阻止将其添加到此双端队列
      NullPointerException - 如果指定元素为空
      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 - 如果指定元素为空
      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 - 一个 TimeUnit 决定如何解释 timeout 参数
      返回：
      此双端队列的头部，或者 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（或者等效地，如果此双端队列因调用而更改）。

      此方法等效于 removeFirstOccurrence 。

      指定者：
      remove 在接口 BlockingQueue<E> 中
      指定者：
      remove 在接口 Collection<E> 中
      指定者：
      remove 在接口 Deque<E> 中
      参数：
      o - 要从此双端队列中删除的元素（如果存在）
      返回：
      true 如果此双端队列因调用而改变
      抛出：
      ClassCastException - 如果指定元素的类与此双端队列不兼容 (optional)
      NullPointerException - 如果指定元素为空 (optional)

    • contains

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

    • 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 - 如果指定元素为空
      IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此双端队列