BlockingQueue (Java Platform SE 8 )

参数类型

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>
```
A 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 。 A null用作哨兵值以指示poll操作失败。

A BlockingQueue可能是容量有限的。在任何给定的时间它可能有一个remainingCapacity超过其中没有额外的元素可以put没有阻止。没有任何内在容量限制的A BlockingQueue总是报告剩余容量为Integer.MAX_VALUE 。

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

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

A 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 happen-before到该元素的从访问或移除后续动作BlockingQueue在另一个线程。

此接口是成员Java Collections Framework 。
从以下版本开始：

1.5

方法摘要

所有方法接口方法抽象方法
Modifier and Type	Method and Description
`boolean`	`add(E e)` 将指定的元素插入到此队列中，如果可以立即执行此操作而不违反容量限制， `true`在成功后返回 `IllegalStateException`如果当前没有可用空间，则抛出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`如果当前没有可用空间，则返回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()` 检索并删除此队列的头，如有必要，等待元素可用。

Methods inherited from interface java.util.Queue
element, peek, poll, remove

Methods inherited from interface java.util.Collection
addAll, clear, containsAll, equals, hashCode, isEmpty, iterator, parallelStream, removeAll, removeIf, retainAll, size, spliterator, stream, toArray, toArray

Methods inherited from interface java.lang.Iterable
forEach

- 方法详细信息
  - 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 - 如果指定的元素为空
    
    IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此队列中
  - offer
```
boolean offer(E e)
```
    将指定的元素插入此队列中，如果它是立即可行且不会违反容量限制，返回true在成功和false ，如果当前没有空间可用。当使用容量限制队列时，此方法通常优于add(E) ，这可能无法仅通过抛出异常来插入元素。
    
    Specified by:
    
    offer在界面 Queue<E>
    
    参数
    
    e - 要添加的元素
    
    结果
    
    true如果元素被添加到此队列，否则 false
    
    异常
    
    ClassCastException - 如果指定元素的类阻止将其添加到此队列中
    
    NullPointerException - 如果指定的元素为空
    
    IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此队列
  - put
```
void put(E e)
  throws InterruptedException
```
    将指定的元素插入到此队列中，等待空格可用。
    
    参数
    
    e - 要添加的元素
    
    异常
    
    InterruptedException - 如果在等待时中断
    
    ClassCastException - 如果指定元素的类阻止将其添加到此队列中
    
    NullPointerException - 如果指定的元素为空
    
    IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此队列中
  - offer
```
boolean offer(E e,
              long timeout,
              TimeUnit unit)
       throws InterruptedException
```
    将指定的元素插入到此队列中，等待指定的等待时间（如有必要）才能使空间变得可用。
    
    参数
    
    e - 要添加的元素
    
    timeout - 放弃之前等待多久，以 unit为单位
    
    unit - a TimeUnit确定如何解释 timeout参数
    
    结果
    
    true如果成功，或 false如果在空间可用之前经过指定的等待时间
    
    异常
    
    InterruptedException - 如果在等待时中断
    
    ClassCastException - 如果指定元素的类阻止将其添加到此队列中
    
    NullPointerException - 如果指定的元素为空
    
    IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此队列中
  - take
```
E take()
throws InterruptedException
```
    检索并删除此队列的头，如有必要，等待元素可用。
    
    结果
    
    这个队列的头
    
    异常
    
    InterruptedException - 如果在等待时中断
  - poll
```
E poll(long timeout,
       TimeUnit unit)
throws InterruptedException
```
    检索并删除此队列的头，等待指定的等待时间（如有必要）使元素变为可用。
    
    参数
    
    timeout - 放弃等待多久，以 unit为单位
    
    unit - a 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 - 如果指定的元素为空（ optional ）
  - contains
```
boolean contains(Object o)
```
    如果此队列包含指定的元素，则返回true 。更正式地，返回true如果且仅当这个队列至少包含一个元素e ，使得o.equals(e) 。
    
    Specified by:
    
    contains在界面 Collection<E>
    
    参数
    
    o - 要检查此队列中的遏制的对象
    
    结果
    
    true如果此队列包含指定的元素
    
    异常
    
    ClassCastException - 如果指定元素的类与此队列不兼容（ optional ）
    
    NullPointerException - 如果指定的元素为空（ optional ）
  - drainTo
```
int drainTo(Collection<? super E> c)
```
    从该队列中删除所有可用的元素，并将它们添加到给定的集合中。此操作可能比重复轮询此队列更有效。尝试向集合c添加元素时遇到的c可能会导致在抛出关联的异常时，元素既不在两个集合中，也可能不是两个集合。尝试将队列排入自身会导致IllegalArgumentException 。此外，如果在操作进行中修改了指定的集合，则此操作的行为是未定义的。
    
    参数
    
    c - 传输元素的集合
    
    结果
    
    转移的元素数量
    
    异常
    
    UnsupportedOperationException - 如果指定集合不支持元素的添加
    
    ClassCastException - 如果此队列的元素的类阻止将其添加到指定的集合
    
    NullPointerException - 如果指定的集合为空
    
    IllegalArgumentException - 如果指定的集合是此队列，或此队列的某个元素的某些属性会阻止将其添加到指定的集合
  - drainTo
```
int drainTo(Collection<? super E> c,
            int maxElements)
```
    最多从该队列中删除给定数量的可用元素，并将它们添加到给定的集合中。尝试向集合c添加元素时遇到的c可能会导致在抛出关联的异常时，元素既不在两个集合中，也可能不是两个集合。尝试将队列排入自身导致IllegalArgumentException 。此外，如果在操作进行中修改了指定的集合，则此操作的行为是未定义的。
    
    参数
    
    c - 传输元素的集合
    
    maxElements - 要传输的元素的最大数量
    
    结果
    
    转移的元素数量
    
    异常
    
    UnsupportedOperationException - 如果指定集合不支持元素的添加
    
    ClassCastException - 如果此队列的元素的类阻止将其添加到指定的集合
    
    NullPointerException - 如果指定的集合为空
    
    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

Interface BlockingQueue<E>

方法摘要

Methods inherited from interface java.util.Queue

Methods inherited from interface java.util.Collection

Methods inherited from interface java.lang.Iterable

方法详细信息

add

offer

put

offer

take

poll

remainingCapacity

remove

contains

drainTo

drainTo