java.util.concurrent
接口 BlockingDeque<E>

类型参数：

E - 保存在此 collection 中的元素类型

所有超级接口：

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

所有已知实现类：

LinkedBlockingDeque

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

支持两个附加操作的 Queue，这两个操作是：获取元素时等待双端队列变为非空；存储元素时等待双端队列中的空间变得可用。

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

第一个元素（头部）
	抛出异常	特殊值	阻塞	超时期
插入	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 是线程安全的，但不允许 null 元素，并且可能有（也可能没有）容量限制。

BlockingDeque 实现可以直接用作 FIFO BlockingQueue。继承自 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()

内存一致性效果：当存在其他并发 collection 时，将对象放入 BlockingDeque 之前的线程中的操作 happen-before 随后通过另一线程从 BlockingDeque 中访问或移除该元素的操作。

此接口是 Java Collections Framework 的成员。

从以下版本开始：

1.6

方法摘要

boolean	add(E e) Inserts the 如果立即可行且不违反容量限制，则将指定的元素插入此双端队列表示的队列中（即此双端队列的尾部），并在成功时返回 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) 将元素推入此双端队列表示的栈。
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.Deque 继承的方法

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

从接口 java.util.Collection 继承的方法

addAll, clear, containsAll, equals, hashCode, isEmpty, removeAll, retainAll, toArray, toArray

方法详细信息

addFirst

void addFirst(E e)

如果立即可行且不违反容量限制，则将指定的元素插入此双端队列的开头；如果当前没有空间可用，则抛出 IllegalStateException。当使用有容量限制的双端队列时，通常首选 offerFirst。

指定者：

接口 Deque<E> 中的 addFirst

参数：

e - 要添加的元素

抛出：

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

ClassCastException - 如果指定元素的类不允许将它添加此双端队列

NullPointerException - 如果指定的元素为 null

IllegalArgumentException - 如果指定元素的某些属性不允许将它添加到此双端队列

addLast

void addLast(E e)

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

指定者：

接口 Deque<E> 中的 addLast

参数：

e - 要添加的元素

抛出：

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

ClassCastException - 如果指定元素的类不允许将它添加此双端队列

NullPointerException - 如果指定的元素为 null

IllegalArgumentException - 如果指定元素的某些属性不允许将它添加到此双端队列

offerFirst

boolean offerFirst(E e)

如果立即可行且不违反容量限制，则将指定的元素插入此双端队列的开头，并在成功时返回 true；如果当前没有空间可用，则返回 false。当使用有容量限制的双端队列时，此方法通常优于 addFirst 方法，后者可能无法插入元素，而只是抛出一个异常。

指定者：

接口 Deque<E> 中的 offerFirst

参数：

e - 要添加的元素

返回：

如果元素被添加到此双端队列，则返回 true，否则返回 false

抛出：

ClassCastException - 如果指定元素的类不允许将它添加到此双端队列

NullPointerException - 如果指定的元素为 null

IllegalArgumentException - 如果指定元素的某些属性不允许将它添加到此双端队列

offerLast

boolean offerLast(E e)

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

指定者：

接口 Deque<E> 中的 offerLast

参数：

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)

从此双端队列移除第一次出现的指定元素。如果此双端队列不包含该元素，则不作更改。更确切地讲，移除第一个满足 o.equals(e) 的元素 e（如果存在这样的元素）。如果此双端队列包含指定的元素（或者此双端队列由于调用而发生了更改），则返回 true。

指定者：

接口 Deque<E> 中的 removeFirstOccurrence

参数：

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

返回：

如果由于此调用而移除了一个元素，则返回 true

抛出：

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

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

removeLastOccurrence

boolean removeLastOccurrence(Object o)

从此双端队列移除最后一次出现的指定元素。如果此双端队列不包含该元素，则不作更改。更确切地讲，移除最后一个满足 o.equals(e) 的元素 e（如果存在这样的元素）。如果此双端队列包含指定的元素（或者此双端队列由于调用而发生了更改），则返回 true。

指定者：

接口 Deque<E> 中的 removeLastOccurrence

参数：

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

返回：

如果由于此调用而移除了一个元素，则返回 true

抛出：

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

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

add

boolean add(E e)

Inserts the 如果立即可行且不违反容量限制，则将指定的元素插入此双端队列表示的队列中（即此双端队列的尾部），并在成功时返回 true；如果当前没有空间可用，则抛出 IllegalStateException。当使用有容量限制的双端队列时，通常首选 offer。

此方法等效于 addLast。

指定者：

接口 BlockingQueue<E> 中的 add

指定者：

接口 Collection<E> 中的 add

指定者：

接口 Deque<E> 中的 add

指定者：

接口 Queue<E> 中的 add

参数：

e - 要添加的元素

返回：

true（根据 Collection.add(E) 的规定）

抛出：

IllegalStateException - 如果由于容量限制此时不能添加该元素

ClassCastException - 如果指定元素的类不允许它被添加到此双端队列

NullPointerException - 如果指定的元素为 null

IllegalArgumentException - 如果指定元素的某个属性不允许它被添加到此双端队列

offer

boolean offer(E e)

如果立即可行且不违反容量限制，则将指定的元素插入此双端队列表示的队列中（即此双端队列的尾部），并在成功时返回 true；如果当前没有空间可用，则返回 false。当使用有容量限制的双端队列时，此方法通常优于 add(E) 方法，后者可能无法插入元素，而只是抛出一个异常。

此方法等效于 offerLast。

指定者：

接口 BlockingQueue<E> 中的 offer

指定者：

接口 Deque<E> 中的 offer

指定者：

接口 Queue<E> 中的 offer

参数：

e - 要添加的元素

返回：

如果该元素已添加到此队列，则返回 true；否则返回 false

抛出：

ClassCastException - 如果指定元素的类不允许它被添加到此双端队列

NullPointerException - 如果指定的元素为 null

IllegalArgumentException - 如果指定元素的某个属性不允许它被添加到此双端队列

put

void put(E e)
         throws InterruptedException

将指定的元素插入此双端队列表示的队列中（即此双端队列的尾部），必要时将一直等待可用空间。

此方法等效于 putLast。

指定者：

接口 BlockingQueue<E> 中的 put

参数：

e - 要添加的元素

抛出：

InterruptedException - 如果在等待时被中断

ClassCastException - 如果指定元素的类不允许它被添加到此双端队列

NullPointerException - 如果指定的元素为 null

IllegalArgumentException - 如果指定元素的某个属性不允许它被添加到此双端队列

offer

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

将指定的元素插入此双端队列表示的队列中（即此双端队列的尾部），必要时将在指定的等待时间内一直等待可用空间。

此方法等效于 offerLast。

指定者：

接口 BlockingQueue<E> 中的 offer

参数：

e - 要添加的元素

timeout - 放弃之前等待的时间长度，以 unit 为时间单位

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

返回：

如果元素被添加到此双端队列，则返回 true，否则返回 false

抛出：

InterruptedException - 如果在等待时被中断

ClassCastException - 如果指定元素的类不允许它被添加到此双端队列

NullPointerException - 如果指定的元素为 null

IllegalArgumentException - 如果指定元素的某个属性不允许它被添加到此双端队列

remove

E remove()

获取并移除此双端队列表示的队列的头部（即此双端队列的第一个元素）。此方法与 poll 的不同之处在于：如果此双端队列为空，它会抛出一个异常。

此方法等效于 removeFirst。

指定者：

接口 Deque<E> 中的 remove

指定者：

接口 Queue<E> 中的 remove

返回：

此双端队列表示的队列的头部

抛出：

NoSuchElementException - 如果此双端队列为空

poll

E poll()

获取并移除此双端队列表示的队列的头部（即此双端队列的第一个元素）；如果此双端队列为空，则返回 null。

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

指定者：

接口 Deque<E> 中的 poll

指定者：

接口 Queue<E> 中的 poll

返回：

此双端队列的头部；如果此双端队列为空，则返回 null

take

E take()
       throws InterruptedException

获取并移除此双端队列表示的队列的头部（即此双端队列的第一个元素），必要时将一直等待可用元素。

此方法等效于 takeFirst。

指定者：

接口 BlockingQueue<E> 中的 take

返回：

此双端队列的头部

抛出：

InterruptedException - 如果在等待时被中断

poll

E poll(long timeout,
       TimeUnit unit)
       throws InterruptedException

获取并移除此双端队列表示的队列的头部（即此双端队列的第一个元素），如有必要将在指定的等待时间内等待可用元素。

此方法等效于 pollFirst。

指定者：

接口 BlockingQueue<E> 中的 poll

参数：

timeout - 放弃之前要等待的时间长度，用 unit 的时间单位表示

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

返回：

此双端队列的头部；如果在元素可用前超过了指定的等待时间，则返回 null

抛出：

InterruptedException - 如果在等待时被中断

element

E element()

获取但不移除此双端队列表示的队列的头部（即此双端队列的第一个元素）。此方法与 peek 的不同之处在于：如果此双端队列为空，它会抛出一个异常。

此方法等效于 getFirst。

指定者：

接口 Deque<E> 中的 element

指定者：

接口 Queue<E> 中的 element

返回：

此双端队列的头部

抛出：

NoSuchElementException - 如果此双端队列为空

peek

E peek()

获取但不移除此双端队列表示的队列的头部（即此双端队列的第一个元素）；如果此双端队列为空，则返回 null。

此方法等效于 peekFirst。

指定者：

接口 Deque<E> 中的 peek

指定者：

接口 Queue<E> 中的 peek

返回：

此双端队列的头部；如果此双端队列为空，则返回 null

remove

boolean remove(Object o)

从此双端队列移除第一次出现的指定元素。如果此双端队列不包含该元素，则不作更改。更确切地讲，移除第一个满足 o.equals(e) 的元素 e（如果存在这样的元素）。如果此双端队列包含指定的元素（或者此双端队列由于调用而发生了更改），则返回 true。

此方法等效于 removeFirstOccurrence。

指定者：

接口 BlockingQueue<E> 中的 remove

指定者：

接口 Collection<E> 中的 remove

指定者：

接口 Deque<E> 中的 remove

参数：

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

返回：

如果此双端队列由于调用而发生更改，则返回 true

抛出：

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

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

contains

boolean contains(Object o)

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

指定者：

接口 BlockingQueue<E> 中的 contains

指定者：

接口 Collection<E> 中的 contains

指定者：

接口 Deque<E> 中的 contains

参数：

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

返回：

如果此双端队列包含指定的元素，则返回 true

抛出：

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

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

size

int size()

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

指定者：

接口 Collection<E> 中的 size

指定者：

接口 Deque<E> 中的 size

返回：

此双端队列中的元素数

iterator

Iterator<E> iterator()

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

指定者：

接口 Collection<E> 中的 iterator

指定者：

接口 Deque<E> 中的 iterator

指定者：

接口 Iterable<E> 中的 iterator

返回：

按恰当顺序在此双端队列中的元素上进行迭代的迭代器

push

void push(E e)

将元素推入此双端队列表示的栈。换句话说，在不违反容量限制的情况下，将元素插入双端队列的开头。

此方法等效于 addFirst。

指定者：

接口 Deque<E> 中的 push

参数：

e - 要推入的元素

抛出：

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

ClassCastException - 如果指定元素的类不允许将它添加此双端队列

NullPointerException - 如果指定的元素为 null

IllegalArgumentException - 如果指定元素的某些属性不允许将它添加到此双端队列