compact1, compact2, compact3

java.util.concurrent

Interface BlockingQueue<E>

参数类型

E -元素举行此集合中的类型

All Superinterfaces:

Collection ， Iterable ， Queue

All Known Subinterfaces:

BlockingDeque ， TransferQueue

所有已知实现类：

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

一个BlockingQueue不接受null元素。实现把NullPointerException试图add，put或offer一null。一个null作为指示操作失败poll sentinel值。

一个BlockingQueue可能能力有限。在任何给定的时间，它可能有一个remainingCapacity之外没有其他的元素可以put无阻塞。一个没有任何内在的约束能力BlockingQueue总报告的剩余容量Integer.MAX_VALUE。

BlockingQueue实现设计主要用于生产者消费者队列，但同时支持Collection接口。因此，例如，可以从队列中删除任意一个元素使用remove(x)。然而，这样的操作一般不执行非常有效，并且只用于临时使用，例如当一个队列消息被取消时。

BlockingQueue实现是线程安全的。所有的排队方法实现原子级采用的并发控制内部锁或其他形式的影响。然而，大量收集操作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 happen-before行动从另一个线程的BlockingQueue元素的访问和去除之前的线程的行为。

该接口的 Java Collections Framework成员。

从以下版本开始：

一点五

方法摘要

Modifier and Type	Method and Description
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() 检索并移除此队列的头，在必要时等待，直到一个元素可用。

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 -如果指定元素为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如果此队列包含指定的元素。更正式地说，返回 true当且仅当该队列包含至少一个元素 e这样 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 -如果指定集合为空

IllegalArgumentException -如果指定集合的队列，该队列或一个元素的一些特性可以防止它被添加到指定的集合

drainTo

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

从这个队列中移除给定数量的可用元素，并将它们添加到给定的集合中。一个在试图收集 c添加元素可能会导致元素在没有遭遇过失败，或集合时相关的异常被抛出。试图排队列本身造成 IllegalArgumentException。此外，当操作正在进行中时，此操作的行为是不确定的，如果指定的集合被修改了。

参数

c -收集传递元素

maxElements -元素的最大数量的转移

结果

传输的元素数

异常

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

ClassCastException -如果该队列的元素类型阻止其加入指定集合

NullPointerException -如果指定集合为空

IllegalArgumentException -如果指定集合的队列，该队列或一个元素的一些特性可以防止它被添加到指定的集合