Java java.util.concurrent 接口 BlockingQueue<E>（JDK5）

所有类

java.util.concurrent
接口 BlockingQueue<E>

类型参数：

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

offer

boolean offer(E o)

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

指定者：

接口 Queue<E> 中的 offer

参数：

o - 要添加的元素。

返回：

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

抛出：

NullPointerException - 如果指定的元素为 null

offer

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

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

参数：

o - 要添加的元素

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

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

返回：

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

抛出：

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

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

poll

E poll(long timeout,
       TimeUnit unit)
       throws InterruptedException

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

参数：

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

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

返回：

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

抛出：

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

take

E take()
       throws InterruptedException

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

返回：

此队列的头部

抛出：

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

put

void put(E o)
         throws InterruptedException

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

参数：

o - 要添加的元素

抛出：

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

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

remainingCapacity

int remainingCapacity()

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

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

返回：

剩余容量

add

boolean add(E o)

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

指定者：

接口 Collection<E> 中的 add

参数：

o - 元素

返回：

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

抛出：

NullPointerException - 如果指定元素为 null

IllegalStateException - 如果无法添加元素