/**
//
* A {@link java.util.Queue} that additionally supports operations that
wait for the queue to become non-empty when retrieving an element,
and wait for space to become available in the queue when storing an element.
*
//4种不同方式,在不满足时的处理操作
* <p>{@code BlockingQueue} methods come in four forms, with different ways
* of handling operations that cannot be satisfied immediately, but may be
* satisfied at some point in the future:
one throws an exception, //抛异常
the second returns a special value (either {@code null} or {@code false}, depending n the operation), //返回特殊值null或者false
the third blocks the current thread indefinitely until the operation can succeed, //等待,直到成功
the fourth blocks for only a given maximum time limit before giving up. //最多等待,然后放弃
//a-o-p add -offer-put
//r-p-t remove-poll-take
//e-p element-peek
---------------------------------------------------------------------------------
>>>>>> 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() -- --
---------------------------------------------------------------------------------
These methods are summarized in the following table:
* <table BORDER CELLPADDING=3 CELLSPACING=1>
* <caption>Summary of BlockingQueue methods</caption>
* <tr>
* <td></td>
* <td ALIGN=CENTER><em>Throws exception</em></td>
* <td ALIGN=CENTER><em>Special value</em></td>
* <td ALIGN=CENTER><em>Blocks</em></td>
* <td ALIGN=CENTER><em>Times out</em></td>
* </tr>
* <tr>
* <td><b>Insert</b></td>
* <td>{@link #add add(e)}</td>
* <td>{@link #offer offer(e)}</td>
* <td>{@link #put put(e)}</td>
* <td>{@link #offer(Object, long, TimeUnit) offer(e, time, unit)}</td>
* </tr>
* <tr>
* <td><b>Remove</b></td>
* <td>{@link #remove remove()}</td>
* <td>{@link #poll poll()}</td>
* <td>{@link #take take()}</td>
* <td>{@link #poll(long, TimeUnit) poll(time, unit)}</td>
* </tr>
* <tr>
* <td><b>Examine</b></td>
* <td>{@link #element element()}</td>
* <td>{@link #peek peek()}</td>
* <td><em>not applicable</em></td>
* <td><em>not applicable</em></td>
* </tr>
* </table>
//阻塞队列不接受null元素,当准备插入null元素的时候,报错NullPointerException
* <p>A {@code BlockingQueue} does not accept {@code null} elements.
* Implementations throw {@code NullPointerException} on attempts
* to {@code add}, {@code put} or {@code offer} a {@code null}.
//null作为一个哨兵值,表示poll操作失败
A {@code null} is used as a sentinel value to indicate failure of
* {@code poll} operations.
//阻塞队列可能是有界的,,remainingCapacity表示在阻塞之前,还能put多少元素
* <p>A {@code BlockingQueue} may be capacity bounded. At any given
* time it may have a {@code remainingCapacity} beyond which no
* additional elements can be {@code put} without blocking.
//一个阻塞队列,如果内部没有容量限制的话,总是返回Integer.MAX_VALUE}作为剩余容量
* A {@code BlockingQueue} without any intrinsic capacity constraints always
* reports a remaining capacity of {@code Integer.MAX_VALUE}.
//一个阻塞队列,主要被设计用来生产-消费 队列
* <p>{@code BlockingQueue} implementations are designed to be used
* primarily for producer-consumer queues, but additionally support
* the {@link java.util.Collection} interface.
So, for example, it is
* possible to remove an arbitrary element from a queue using
* {@code remove(x)}. However, such operations are in general
* <em>not</em> performed very efficiently, and are intended for only
* occasional use, such as when a queued message is cancelled.
//阻塞队列时线程安全的
* <p>{@code BlockingQueue} implementations are thread-safe.
//所有队列方法通过内部锁或者其他并发控制机制,保证效果
All queuing methods achieve their effects atomically using internal
* locks or other forms of concurrency control.
//批量的集合操作,不需要保证原子性
// addAll containsAll retainAll removeAll
However, the <em>bulk</em> Collection operations {@code addAll},
* {@code containsAll}, {@code retainAll} and {@code removeAll} are
* <em>not</em> necessarily performed atomically unless specified
* otherwise in an implementation.
//因此,当addAll抛出异常的时候,可能只保存了一部分元素
So it is possible, for example, for
* {@code addAll(c)} to fail (throwing an exception) after adding
* only some of the elements in {@code c}.
//阻塞队列内在不支持 close 和 shutdown 方法,表示没有元素将会被新增
* <p>A {@code BlockingQueue} does <em>not</em> intrinsically support
* any kind of "close" or "shutdown" operation to
* indicate that no more items will be added.
//这些特性的需求和使用往往依赖于实现。
The needs and usage of such features tend to be implementation-dependent.
//例如,生产者插入结束符或者有毒对象,消费者基于这个中断消费
For example, a common tactic is for producers to insert special
* <em>end-of-stream</em> or <em>poison</em> objects, that are
* interpreted accordingly when taken by consumers.
//典型的生产-消费场景
* <p>
* Usage example, based on a typical producer-consumer scenario.
* Note that a {@code BlockingQueue} can safely be used with multiple
* producers and multiple consumers.
* <pre> {@code
* 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();
* }
* }}</pre>
*
* <p>Memory consistency effects:
As with other concurrent collections, actions in a thread prior to placing an object into a
* {@code BlockingQueue}
* <a href="package-summary.html#MemoryVisibility"><i>happen-before</i></a>
* actions subsequent to the access or removal of that element from
* the {@code BlockingQueue} in another thread.
*
* <p>This interface is a member of the
* <a href="{@docRoot}/../technotes/guides/collections/index.html">
* Java Collections Framework</a>.
*
* @since 1.5
* @author Doug Lea
* @param <E> the type of elements held in this collection
*/