模块 java.base

软件包 java.util.concurrent

Interface BlockingDeque<E>

参数类型

E - 此双端队列中保留的元素类型

All Superinterfaces:

BlockingQueue<E> ， Collection<E> ， Deque<E> ， Iterable<E> ， Queue<E>

所有已知实现类：

LinkedBlockingDeque

public interface BlockingDeque<E>
extends BlockingQueue<E>, Deque<E>

Deque还支持阻塞操作，这些阻塞操作在检索元素时等待deque变为非空，并在存储元素时等待deque中的空间可用。

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

Summary of BlockingDeque methods 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

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

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

Comparison of BlockingQueue and BlockingDeque methods 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()

内存一致性影响：与其他并发集合一样，在将对象放入另一个线程中的BlockingDeque中的该元素后，将对象放入BlockingDeque happen-before之前的操作。

此界面是Java Collections Framework的成员。

从以下版本开始：

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到此双端队列表示的堆栈（换句话说，在此双端队列的头部），如果当前没有可用空间则抛出 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 。

Specified by:

addFirst在界面 Deque<E>

参数

e - 要添加的元素

异常

IllegalStateException - 如果由于容量限制而无法在此时添加元素

ClassCastException - 如果指定元素的类阻止将其添加到此双端队列中

NullPointerException - 如果指定的元素为null

IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此双端队列中

addLast

void addLast(E e)

如果可以在不违反容量限制的情况下立即插入指定元素，则在此双端队列的末尾插入指定元素，如果当前没有可用空间，则抛出IllegalStateException 。 当使用容量限制的双端队列时，通常优选使用offerLast 。

Specified by:

addLast in interface Deque<E>

参数

e - 要添加的元素

异常

IllegalStateException - 如果由于容量限制，此时无法添加元素

ClassCastException - 如果指定元素的类阻止将其添加到此双端队列中

NullPointerException - 如果指定的元素为null

IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此双端队列中

offerFirst

boolean offerFirst(E e)

插入此双端队列的前面，如果它是立即可行且不会违反容量限制，返回指定的元素true在成功和false ，如果当前没有空间可用。 使用容量限制的双端队列时，此方法通常优于addFirst方法，该方法只能通过抛出异常来插入元素。

Specified by:

offerFirst在界面 Deque<E>

参数

e - 要添加的元素

结果

true如果元素已添加到此双端队列， false

异常

ClassCastException - 如果指定元素的类阻止将其添加到此双端队列中

NullPointerException - 如果指定的元素为null

IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此双端队列中

offerLast

boolean offerLast(E e)

插入此双端队列的末尾，如果它是立即可行且不会违反容量限制，返回指定的元素true在成功和false ，如果当前没有空间可用。 使用容量限制的双端队列时，此方法通常优于addLast方法，该方法只能通过抛出异常来插入元素。

Specified by:

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 -一个 TimeUnit确定如何解释 timeout参数

结果

true如果成功，或 false如果在空间可用之前经过了指定的等待时间

异常

InterruptedException - 如果在等待时中断

ClassCastException - 如果指定元素的类阻止将其添加到此双端队列中

NullPointerException - 如果指定的元素为null

IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此双端队列中

offerLast

boolean offerLast(E e,
                  long timeout,
                  TimeUnit unit)
           throws InterruptedException

在此双端队列的末尾插入指定的元素，如果需要空间可用，则等待指定的等待时间。

参数

e - 要添加的元素

timeout - 放弃前等待多长时间，单位为 unit

unit -一个 TimeUnit确定如何解释 timeout参数

结果

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 -一个 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 （或等效地，如果此双端队列因调用而更改）。

Specified by:

removeFirstOccurrence在界面 Deque<E>

参数

o - 要从此双端队列中删除的元素（如果存在）

结果

true如果由于此调用而删除了某个元素

异常

ClassCastException - 如果指定元素的类与此双端队列不兼容（ optional ）

NullPointerException - 如果指定的元素为null（ optional ）

removeLastOccurrence

boolean removeLastOccurrence(Object o)

从此双端队列中删除最后一次出现的指定元素。 如果双端队列不包含该元素，则不会更改。 更正式地，删除最后一个元素e ，使得o.equals(e) （如果存在这样的元素）。 如果此双端队列包含指定的元素，则返回true （或等效地，如果此双端队列因调用而更改）。

Specified by:

removeLastOccurrence在界面 Deque<E>

参数

o - 要从此双端队列中删除的元素（如果存在）

结果

true如果由于此调用而删除了某个元素

异常

ClassCastException - 如果指定元素的类与此双端队列不兼容（ optional ）

NullPointerException - 如果指定的元素为null（ optional ）

add

boolean add(E e)

如果可以在不违反容量限制的情况下立即执行此操作，则将指定的元素插入此双端队列表示的队列（换句话说，在此双端队列的尾部），成功时返回true ，如果当前没有可用空间，则抛出IllegalStateException 。 当使用容量限制的双端队列时，通常优选使用offer 。

此方法相当于addLast 。

Specified by:

add在界面 BlockingQueue<E>

Specified by:

add ，界面 Collection<E>

Specified by:

add在界面 Deque<E>

Specified by:

add在界面 Queue<E>

参数

e - 要添加的元素

结果

true （由 Collection.add(E)指定）

异常

IllegalStateException - 如果由于容量限制，此时无法添加元素

ClassCastException - 如果指定元素的类阻止将其添加到此双端队列中

NullPointerException - 如果指定的元素为null

IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此双端队列中

offer

boolean offer(E e)

将指定的元素插入此双端队列表示的队列中（换句话说，在此双端队列的尾部），如果它是立即可行且不会违反容量限制，返回true在成功和false如果当前没有空间可用。 当使用容量限制的双端队列时，此方法通常优于add(E)方法，该方法仅通过抛出异常而无法插入元素。

此方法相当于offerLast 。

Specified by:

offer ，界面 BlockingQueue<E>

Specified by:

offer在界面 Deque<E>

Specified by:

offer在界面 Queue<E>

参数

e - 要添加的元素

结果

true如果元素已添加到此队列， false

异常

ClassCastException - 如果指定元素的类阻止将其添加到此双端队列中

NullPointerException - 如果指定的元素为null

IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此双端队列中

put

void put(E e)
  throws InterruptedException

将指定的元素插入此双端队列表示的队列中（换句话说，在此双端队列的尾部），等待空间变得可用。

此方法相当于putLast 。

Specified by:

put在接口 BlockingQueue<E>

参数

e - 要添加的元素

异常

InterruptedException - 等待时中断

ClassCastException - 如果指定元素的类阻止将其添加到此双端队列中

NullPointerException - 如果指定的元素为null

IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此双端队列中

offer

boolean offer(E e,
              long timeout,
              TimeUnit unit)
       throws InterruptedException

将指定的元素插入此双端队列表示的队列中（换句话说，在此双端队列的尾部），如果需要空间可用，则等待指定的等待时间。

此方法相当于offerLast 。

Specified by:

offer在界面 BlockingQueue<E>

参数

e - 要添加的元素

timeout - 放弃前等待多长时间，单位为 unit

unit -一个 TimeUnit确定如何解释 timeout参数

结果

true如果元素已添加到此双端队列， false

异常

InterruptedException - 如果在等待时中断

ClassCastException - 如果指定元素的类阻止将其添加到此双端队列中

NullPointerException - 如果指定的元素为null

IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此双端队列中

remove

E remove()

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

此方法相当于removeFirst 。

Specified by:

remove在界面 Deque<E>

Specified by:

remove ，界面 Queue<E>

结果

这个双端队列所代表的队列的头部

异常

NoSuchElementException - 如果此双端队列是空的

poll

E poll()

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

此方法相当于Deque.pollFirst() 。

Specified by:

poll在界面 Deque<E>

Specified by:

poll在界面 Queue<E>

结果

这个双端队列的头部，或 null如果这个双端队列是空的

take

E take()
throws InterruptedException

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

此方法相当于takeFirst 。

Specified by:

take在界面 BlockingQueue<E>

结果

这个双端队长

异常

InterruptedException - 如果在等待时被打断

poll

E poll(long timeout,
       TimeUnit unit)
throws InterruptedException

检索并移除此双端队列表示的队列的头部（换句话说，此双端队列的第一个元素），等待指定的等待时间（如果需要，则元素变为可用）。

此方法相当于pollFirst 。

Specified by:

poll在界面 BlockingQueue<E>

参数

timeout - 放弃前等待多长时间，单位为 unit

unit -一个 TimeUnit确定如何解释 timeout参数

结果

此双端队列的头部，或 null如果在元素可用之前经过了指定的等待时间

异常

InterruptedException - 等待时中断

element

E element()

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

此方法相当于getFirst 。

Specified by:

element在界面 Deque<E>

Specified by:

element在界面 Queue<E>

结果

这个双端队长

异常

NoSuchElementException - 如果此双端队列为空

peek

E peek()

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

此方法相当于peekFirst 。

Specified by:

peek在接口 Deque<E>

Specified by:

peek在界面 Queue<E>

结果

这个双端队列的头部，或 null如果这个双端队列是空的

remove

boolean remove(Object o)

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

此方法相当于removeFirstOccurrence 。

Specified by:

remove in interface BlockingQueue<E>

Specified by:

remove在界面 Collection<E>

Specified by:

remove在界面 Deque<E>

参数

o - 要从此双端队列中删除的元素（如果存在）

结果

true如果此deque因呼叫而改变

异常

ClassCastException - 如果指定元素的类与此双端队列不兼容（ optional ）

NullPointerException - 如果指定的元素为null（ optional ）

contains

boolean contains(Object o)

如果此双端队列包含指定的元素，则返回true 。 更正式地，返回true当且仅当此双端队列包含至少一个元素e o.equals(e) 。

Specified by:

contains ，界面 BlockingQueue<E>

Specified by:

contains在界面 Collection<E>

Specified by:

contains在界面 Deque<E>

参数

o - 要在此双端队列中检查包含的对象

结果

true如果此双端队列包含指定的元素

异常

ClassCastException - 如果指定元素的类与此双端队列不兼容（ optional ）

NullPointerException - 如果指定的元素为null（ optional ）

size

int size()

返回此双端队列中的元素数。

Specified by:

size在界面 Collection<E>

Specified by:

size在界面 Deque<E>

结果

此双端队列中的元素数量

iterator

Iterator<E> iterator()

以适当的顺序返回此双端队列中元素的迭代器。 元素将从第一个（头部）到最后一个（尾部）按顺序返回。

Specified by:

iterator在界面 Collection<E>

Specified by:

iterator在界面 Deque<E>

Specified by:

iterator在界面 Iterable<E>

结果

以适当的顺序在此双端队列中的元素上的迭代器

push

void push(E e)

如果可以在不违反容量限制的情况下立即执行此操作， IllegalStateException到此双端队列表示的堆栈（换句话说，在此双端队列的头部），如果当前没有可用空间则抛出IllegalStateException 。

此方法相当于addFirst 。

Specified by:

push在界面 Deque<E>

参数

e - 要推送的元素

异常

IllegalStateException - 如果由于容量限制，此时无法添加元素

ClassCastException - 如果指定元素的类阻止将其添加到此双端队列中

NullPointerException - 如果指定的元素为null

IllegalArgumentException - if some property of the specified element prevents it from being added to this deque