模块 java.base

软件包 java.util.concurrent

Interface BlockingQueue<E>

参数类型

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

All Superinterfaces:

Collection<E> ， Iterable<E> ， Queue<E>

All Known Subinterfaces:

BlockingDeque<E> ， TransferQueue<E>

所有已知实现类：

ArrayBlockingQueue ， DelayQueue ， LinkedBlockingDeque ， LinkedBlockingQueue ， LinkedTransferQueue ， PriorityBlockingQueue ， SynchronousQueue

public interface BlockingQueue<E>extends Queue<E>

Queue还支持在检索元素时等待队列变为非空的操作，并在存储元素时等待队列中的空间可用。

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

Summary of BlockingQueue methods Throws exception Special value Blocks Times out Insert add(e) offer(e) put(e) offer(e, time, unit) Remove remove() poll() take() poll(time, unit) Examine element() peek() not applicable not applicable

A BlockingQueue不接受null元素。 实现抛出NullPointerException上尝试add ， put或offer一个null 。 null用作null值以指示poll操作失败。

BlockingQueue可以是容量限制的。 在任何给定时间它可能有一个remainingCapacity超过该put没有阻止的附加元素可以是put 。 一个BlockingQueue没有任何内部容量约束始终报告的剩余容量Integer.MAX_VALUE 。

BlockingQueue实现主要用于生产者 - 消费者队列，但另外支持Collection接口。 因此，例如，可以使用remove(x)从队列中删除任意元素。 然而，这些操作通常不是非常有效地执行，并且仅用于偶尔使用，例如当排队的消息被取消时。

BlockingQueue实现是线程安全的。 所有排队方法都使用内部锁或其他形式的并发控制以原子方式实现其效果。 然而， 大量的Collection操作addAll ， containsAll ， retainAll和removeAll 不一定原子除非在实现中另有规定执行。 因此，例如， addAll(c)可能在仅添加c一些元素后失败（抛出异常）。

BlockingQueue本质上不支持任何类型的“关闭”或“关闭”操作，以指示不再添加任何项目。 这些功能的需求和使用倾向于依赖于实现。 例如，一种常见的策略是生产者插入特殊的流末端或毒物对象，这些对象在被消费者采用时会相应地进行解释。

用法示例，基于典型的生产者 - 消费者场景。 请注意， BlockingQueue可以安全地与多个生产者和多个消费者一起使用。

   class Producer implements Runnable { private final BlockingQueue queue; Producer(BlockingQueue q) { queue = q; } public void run() { try { while (true) { queue.put(produce()); } } catch (InterruptedException ex) { ... handle ...} } Object produce() { ... } } class Consumer implements Runnable { private final BlockingQueue queue; Consumer(BlockingQueue q) { queue = q; } public void run() { try { while (true) { consume(queue.take()); } } catch (InterruptedException ex) { ... handle ...} } void consume(Object x) { ... } } class Setup { void main() { BlockingQueue q = new SomeQueueImplementation(); Producer p = new Producer(q); Consumer c1 = new Consumer(q); Consumer c2 = new Consumer(q); new Thread(p).start(); new Thread(c1).start(); new Thread(c2).start(); } } 

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

此界面是Java Collections Framework的成员。

从以下版本开始：

1.5

方法摘要

变量和类型	方法	描述
boolean	add(E e)	如果可以在不违反容量限制的情况下立即执行此操作，则将指定的元素插入此队列，成功时返回 true ，如果当前没有空间，则抛出 IllegalStateException 。
boolean	contains(Object o)	如果此队列包含指定的元素，则返回 true 。
int	drainTo(Collection<? super E> c)	从此队列中删除所有可用元素，并将它们添加到给定集合中。
int	drainTo(Collection<? super E> c, int maxElements)	从该队列中删除最多给定数量的可用元素，并将它们添加到给定集合中。
boolean	offer(E e)	将指定的元素插入此队列中，如果它是立即可行且不会违反容量限制，返回 true在成功和 false ，如果当前没有空间可用。
boolean	offer(E e, long timeout, TimeUnit unit)	将指定的元素插入此队列，如果需要空间可用，则等待指定的等待时间。
E	poll(long timeout, TimeUnit unit)	检索并删除此队列的头部，如果元素可用，则等待指定的等待时间。
void	put(E e)	将指定的元素插入此队列，等待空间变为可用。
int	remainingCapacity()	返回理想情况下（在没有内存或资源限制的情况下）此队列可以无阻塞地接受的其他元素的数量，如果没有内部限制，则 Integer.MAX_VALUE 。
boolean	remove(Object o)	从此队列中删除指定元素的单个实例（如果存在）。
E	take()	检索并删除此队列的头部，必要时等待，直到元素可用。

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

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

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

forEach

声明方法的接口 java.util.Queue

element, peek, poll, remove

方法详细信息

add

boolean add(E e)

如果可以在不违反容量限制的情况下立即执行此操作，则将指定的元素插入此队列，成功时返回true ，如果当前没有空间，则抛出IllegalStateException 。 使用容量限制队列时，通常最好使用offer 。

Specified by:

add在界面 Collection<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) ，它只能通过抛出异常来插入元素。

Specified by:

offer ，界面 Queue<E>

参数

e - 要添加的元素

结果

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

异常

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

NullPointerException - 如果指定的元素为null

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

put

void put(E e)  throws InterruptedException

将指定的元素插入此队列，等待空间变为可用。

参数

e - 要添加的元素

异常

InterruptedException - 如果在等待时中断

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

NullPointerException - 如果指定的元素为null

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

offer

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

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

参数

e - 要添加的元素

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

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

结果

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

异常

InterruptedException - 如果在等待时中断

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

NullPointerException - 如果指定的元素为null

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

take

E take()throws InterruptedException

检索并删除此队列的头部，必要时等待，直到元素可用。

结果

这个队列的头

异常

InterruptedException - 如果在等待时中断

poll

E poll(long timeout,       TimeUnit unit)throws InterruptedException

检索并删除此队列的头部，如果元素可用，则等待指定的等待时间。

参数

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

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

结果

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

异常

InterruptedException - 等待时中断

remainingCapacity

int remainingCapacity()

返回理想情况下（在没有内存或资源限制的情况下）此队列可以无阻塞地接受的其他元素的数量，如果没有内部限制，则Integer.MAX_VALUE 。

请注意，您不能总是通过检查remainingCapacity来判断插入元素的尝试是否成功，因为可能是另一个线程即将插入或删除元素的情况。

结果

剩余的容量

remove

boolean remove(Object o)

从此队列中删除指定元素的单个实例（如果存在）。 更正式地，如果此队列包含一个或多个这样的元素，则移除元素e ，使得o.equals(e) 。 如果此队列包含指定的元素，则返回true （或等效地，如果此队列因调用而更改）。

Specified by:

remove在界面 Collection<E>

参数

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

结果

true如果此队列因调用而更改

异常

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

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

contains

boolean contains(Object o)

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

Specified by:

contains在界面 Collection<E>

参数

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

结果

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

异常

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

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

drainTo

int drainTo(Collection<? super E> c)

从此队列中删除所有可用元素，并将它们添加到给定集合中。 此操作可能比重复轮询此队列更有效。 尝试将元素添加到集合c遇到的故障可能导致在抛出关联的异常时元素既不在集合中，也不在集合中。 尝试将队列排入自身会导致IllegalArgumentException 。 此外，如果在操作正在进行时修改了指定的集合，则此操作的行为是不确定的。

参数

c - 将元素转换为的集合

结果

转移的元素数量

异常

UnsupportedOperationException - 如果指定集合不支持添加元素

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

NullPointerException - 如果指定的集合为null

IllegalArgumentException - 如果指定的集合是此队列，或此队列的某个元素的某些属性阻止将其添加到指定的集合

drainTo

int drainTo(Collection<? super E> c,            int maxElements)

从该队列中删除最多给定数量的可用元素，并将它们添加到给定集合中。 尝试将元素添加到集合c遇到的故障可能导致在抛出关联的异常时元素既不在集合中，也不在集合中。 尝试将队列排入自身会导致IllegalArgumentException 。 此外，如果在操作正在进行时修改了指定的集合，则此操作的行为是不确定的。

参数

c - 将元素转换为的集合

maxElements - 要传输的最大元素数

结果

转移的元素数量

异常

UnsupportedOperationException - 如果指定集合不支持添加元素

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

NullPointerException - 如果指定的集合为null

IllegalArgumentException - if the specified collection is this queue, or some property of an element of this queue prevents it from being added to the specified collection