BlockingQueue

public interface BlockingQueue
implements Queue<E>

Known Indirect Subclasses ArrayBlockingQueue<E>, BlockingDeque<E>, DelayQueue<E extends  Delayed>, LinkedBlockingDeque<E>, LinkedBlockingQueue<E>, LinkedTransferQueue<E>, PriorityBlockingQueue<E>, SynchronousQueue<E>, TransferQueue<E> ArrayBlockingQueue<E> 一个由数组支持的有界的 blocking queue 。 BlockingDeque<E> Deque还支持在检索元素时等待deque变为非空的阻塞操作，并在存储元素时等待空间在deque中可用。 DelayQueue<E extends Delayed> 无界 blocking queue的 Delayed元件，其中，当其延迟已到期的元素只能采取。 LinkedBlockingDeque<E> 基于链接节点的可选范围 blocking deque 。 LinkedBlockingQueue<E> 基于链接节点的可选范围 blocking queue 。 LinkedTransferQueue<E> 基于链接节点的无限制 TransferQueue 。 PriorityBlockingQueue<E> 一个无界的 blocking queue ，使用与 PriorityQueue类相同的排序规则，并提供阻止检索操作。 SynchronousQueue<E> 一个 blocking queue其中每个插入操作必须等待另一个线程的相应删除操作，反之亦然。 TransferQueue<E> 一个 BlockingQueue ，其中生产者可能会等待消费者接收元素。

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

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

A BlockingQueue不接受null元素。 NullPointerException尝试执行put或offer和add ， put实施投掷null 。 使用null作为null值来指示poll操作失败。

A BlockingQueue可能是有限的容量。 在任何给定时间可以有一个remainingCapacity超过该无额外元件可以是put无阻塞。 一个BlockingQueue没有任何内部容量约束始终报告的剩余容量Integer.MAX_VALUE 。

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

BlockingQueue实现是线程安全的。 所有排队方法都使用内部锁或其他形式的并发控制自动实现其效果。 然而， 大量的Collection操作addAll ， containsAll ， retainAll和removeAll 不一定原子除非在实现中另有规定执行。 因此，例如，添加c一些元素后， addAll(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在另一个线程。

Summary

Inherited methods
From interface java.util.Queue abstract boolean add(E e) 将指定的元素插入此队列中，如果它是立即可行且不会违反容量限制，返回 true在成功和抛出 IllegalStateException ，如果当前没有空间可用。 abstract E element() 检索但不删除此队列的头部。 abstract boolean offer(E e) 如果可以立即执行而不违反容量限制，则将指定的元素插入此队列中。 abstract E peek() 检索但不移除此队列的头部，或者如果此队列为空，则返回 null 。 abstract E poll() 检索并删除此队列的头部，或者如果此队列为空，则返回 null 。 abstract E remove() 检索并删除此队列的头部。
From interface java.util.Collection abstract boolean add(E e) 确保此集合包含指定的元素（可选操作）。 abstract boolean addAll(Collection<? extends E> c) 将指定集合中的所有元素添加到此集合（可选操作）。 abstract void clear() 从该集合中删除所有元素（可选操作）。 abstract boolean contains(Object o) 如果此集合包含指定的元素，则返回 true 。 abstract boolean containsAll(Collection<?> c) 如果此集合包含指定集合中的所有元素，则返回 true 。 abstract boolean equals(Object o) 将指定的对象与此集合进行比较以获得相等性。 abstract int hashCode() 返回此集合的哈希码值。 abstract boolean isEmpty() 如果此集合不包含元素，则返回 true 。 abstract Iterator<E> iterator() 返回此集合中元素的迭代器。 default Stream<E> parallelStream() 返回一个可能与此集合并行的 Stream作为其源。 abstract boolean remove(Object o) 从该集合中移除指定元素的单个实例（如果存在）（可选操作）。 abstract boolean removeAll(Collection<?> c) 删除指定集合中包含的所有此集合的元素（可选操作）。 default boolean removeIf(Predicate<? super E> filter) 删除此集合中满足给定谓词的所有元素。 abstract boolean retainAll(Collection<?> c) 仅保留包含在指定集合中的此集合中的元素（可选操作）。 abstract int size() 返回此集合中的元素数量。 default Spliterator<E> spliterator() 在此集合中的元素上创建一个 Spliterator 。 default Stream<E> stream() 以此集合作为源返回顺序 Stream 。 abstract <T> T[] toArray(T[] a) 返回包含此集合中所有元素的数组; 返回数组的运行时类型是指定数组的运行时类型。 abstract Object[] toArray() 返回包含此集合中所有元素的数组。
From interface java.lang.Iterable default void forEach(Consumer<? super T> action) 对 Iterable每个元素执行给定操作，直到处理 Iterable所有元素或操作抛出异常。 abstract Iterator<E> iterator() 返回类型为 T元素的迭代器。 default Spliterator<E> spliterator() 创建 Spliterator覆盖此 Iterable描述的元素。

Public methods

boolean add (E e)

boolean contains (Object o)

int drainTo (Collection<? super E> c)

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

boolean offer (E e)

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

E poll (long timeout, 
                TimeUnit unit)

void put (E e)

int remainingCapacity ()

boolean remove (Object o)

E take ()