Question

类型参数：

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

所有超级接口：

Collection<E>, Iterable<E>, Queue<E>

所有已知实现类：

ArrayBlockingQueue, DelayQueue, LinkedBlockingQueue, PriorityBlockingQueue, SynchronousQueue

---

public interface BlockingQueue<E>

extends Queue<E>

支持两个附加操作的 Queue ，这两个操作是：检索元素时等待队列变为非空，以及存储元素时等待空间变得可用。

BlockingQueue 不接受 null 元素。试图 add 、 put 或 offer 一个 null 元素时，某些实现会抛出 NullPointerException 。 null 被用作指示 poll 操作失败的警戒值。

BlockingQueue 可以是限定容量的。它在任意给定时间都可以有一个 remainingCapacity ，超出此容量，便无法无阻塞地 put 额外的元素。没有任何内部容量约束的 BlockingQueue 总是报告 Integer.MAX_VALUE 的剩余容量。

BlockingQueue 实现主要用于生产者-使用者队列，但它另外还支持 Collection 接口。因此，举例来说，使用 remove(x) 从队列中移除任意一个元素是有可能的。然而，这种操作通常不 会有效执行，只能有计划地偶尔使用，比如在取消排队信息时。

BlockingQueue 实现是线程安全的。所有排队方法都可以使用内部锁定或其他形式的并发控制来自动达到它们的目的。然而，大量的 Collection 操作（ addAll 、 containsAll 、 retainAll 和 removeAll ）没有 必要自动执行，除非在实现中特别说明。因此，举例来说，在只添加了 c 中的一些元素后， addAll(c) 有可能失败（抛出一个异常）。

BlockingQueue 实质上不 支持使用任何一种“close”或“shutdown”操作来指示不再添加任何项。这种功能的需求和使用有依赖于实现的倾向。例如，一种常用的策略是：对于生产者，插入特殊的 end-of-stream 或 poison 对象，并根据使用者获取这些对象的时间来对它们进行解释。

以下是基于典型的生产者-使用者场景的一个用例。注意， 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();
   }
 }

此接口是 Java Collections Framework 的成员。

从以下版本开始：

1.5

---

方法摘要
boolean	add(Eo) 将指定的元素添加到此队列中（如果立即可行），在成功时返回 true ，其他情况则抛出 IllegalStateException。
int	drainTo(Collection<? super E>c) 移除此队列中所有可用的元素，并将它们添加到给定 collection 中。
int	drainTo(Collection<? super E>c, intmaxElements) 最多从此队列中移除给定数量的可用元素，并将这些元素添加到给定 collection 中。
boolean	offer(Eo) 如果可能的话，将指定元素插入此队列中。
boolean	offer(Eo, longtimeout, TimeUnitunit) 将指定的元素插入此队列中，如果没有可用空间，将等待指定的等待时间（如果有必要）。
E	poll(longtimeout, TimeUnitunit) 检索并移除此队列的头部，如果此队列中没有任何元素，则等待指定等待的时间（如果有必要）。
void	put(Eo) 将指定元素添加到此队列中，如果没有可用空间，将一直等待（如果有必要）。
int	remainingCapacity() 返回在无阻塞的理想情况下（不存在内存或资源约束）此队列能接受的元素数量；如果没有内部限制，则返回 Integer.MAX_VALUE 。
E	take() 检索并移除此队列的头部，如果此队列不存在任何元素，则一直等待。

从接口 java.util.Queue 继承的方法
element, peek, poll, remove

从接口 java.util.Collection 继承的方法
addAll, clear, contains, containsAll, equals, hashCode, isEmpty, iterator, remove, removeAll, retainAll, size, toArray, toArray

方法详细信息

offer

boolean offer(Eo)

如果可能的话，将指定元素插入此队列中。当使用那些可能会强行使用插入限制（例如容量限制）的队列时， offer 方法通常要优于 Collection.add(E) 方法，后者可能无法插入元素，而只是抛出一个异常。

指定者：

接口 Queue<E> 中的 offer

参数：

o - 要添加的元素。

返回：

如果可以将元素添加到此队列中，则返回 true ，其他情况则返回 false

抛出：

NullPointerException - 如果指定的元素为 null

---

offer

boolean offer(Eo,
              longtimeout,
              TimeUnitunit)
              throws InterruptedException

将指定的元素插入此队列中，如果没有可用空间，将等待指定的等待时间（如果有必要）。

参数：

o - 要添加的元素

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

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

返回：

如果成功，则返回 true ；如果在空间可用前超过了指定的等待时间，则返回 false 。

抛出：

InterruptedException - 如果在等待时被中断。

NullPointerException - 如果指定的元素为 null 。

---

poll

E poll(longtimeout,
       TimeUnitunit)
       throws InterruptedException

检索并移除此队列的头部，如果此队列中没有任何元素，则等待指定等待的时间（如果有必要）。

参数：

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

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

返回：

此队列的头部；如果在元素出现前超过了指定的等待时间，则返回 null 。

抛出：

InterruptedException - 如果在等待时被中断。

---

take

E take()
       throws InterruptedException

检索并移除此队列的头部，如果此队列不存在任何元素，则一直等待。

返回：

此队列的头部

抛出：

InterruptedException - 如果在等待时被中断。

---

put

void put(Eo)
         throws InterruptedException

将指定元素添加到此队列中，如果没有可用空间，将一直等待（如果有必要）。

参数：

o - 要添加的元素

抛出：

InterruptedException - 如果在等待时被中断。

NullPointerException - 如果指定的元素为 null 。

---

remainingCapacity

int remainingCapacity()

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

注意，不能 总是通过检查 remainingCapacity 来判断尝试 add 元素是否成功，因为可能出现这样的情况：其他线程即将 put 或 take 一个元素。

返回：

剩余容量

---

add

boolean add(Eo)

将指定的元素添加到此队列中（如果立即可行），在成功时返回 true ，其他情况则抛出 IllegalStateException。

指定者：

接口 Collection<E> 中的 add

参数：

o - 元素

返回：

true （按照 Collection.add 的常规协定）。

抛出：

NullPointerException - 如果指定元素为 null

IllegalStateException - 如果无法添加元素

---

drainTo

int drainTo(Collection<? super E>c)

移除此队列中所有可用的元素，并将它们添加到给定 collection 中。此操作可能比反复轮询此队列更有效。在试图向 c 集合中 add 元素没有成功时，可能导致在抛出相关异常时，元素会同时在两个 collection 中出现，或者在其中一个 collection 中出现，也可能在两个 collection 中都不出现。如果试图将一个队列放入自身队列中，则会导致 IllegalArgumentException 异常。此外，如果正在进行此操作时修改指定的 collection，则此操作行为是不确定的。

参数：

c - 接收传输元素的 collection

返回：

传输元素的数量。

抛出：

NullPointerException - 如果 c 为 null

IllegalArgumentException - 如果 c 为此队列

---

drainTo

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

最多从此队列中移除给定数量的可用元素，并将这些元素添加到给定 collection 中。在试图向 c 集合中 add 元素没有成功时，可能导致在抛出相关异常时，元素会同时在两个 collection 中出现，或者在其中一个 collection 中出现，也可能在两个 collection 中都不出现。如果试图将一个队列放入自身队列中，则会导致 IllegalArgumentException 异常。此外，如果正在进行此操作时修改指定的 collection，则此操作行为是不确定的。

参数：

c - 接收传输元素的 collection

maxElements - 传输元素的最大数量

返回：

传输元素的数量。

抛出：

NullPointerException - 如果 c 为 null

IllegalArgumentException - 如果 c 为此队列