ArrayBlockingQueue

java.util.concurrent
类 ArrayBlockingQueue<E>

java.lang.Object
   　　java.util.AbstractCollection<E>
　　　　　　java.util.AbstractQueue<E>
　　　　　　　　java.util.concurrent.ArrayBlockingQueue<E>

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

 一个由数组支持的有界阻塞队列。此队列按 FIFO（先进先出）原则对元素进行排序。队列的头部 是在队列中存在时间最长的元素。

队列的尾部 是在队列中存在时间最短的元素。新元素插入到队列的尾部，队列获取操作则是从队列头部开始获得元素。

这是一个典型的“有界缓存区”，固定大小的数组在其中保持生产者插入的元素和使用者提取的元素。

一旦创建了这样的缓存区，就不能再增加其容量。试图向已满队列中放入元素会导致操作受阻塞；试图从空队列中提取元素将导致类似阻塞。

此类支持对等待的生产者线程和使用者线程进行排序的可选公平策略。

默认情况下，不保证是这种排序。然而，通过将公平性 (fairness) 设置为 true 而构造的队列允许按照 FIFO 顺序访问线程。

公平性通常会降低吞吐量，但也减少了可变性和避免了“不平衡性”。  

构造方法摘要

ArrayBlockingQueue(int capacity)
          创建一个带有给定的（固定）容量和默认访问策略的 ArrayBlockingQueue。

ArrayBlockingQueue(int capacity, boolean fair)
          创建一个具有给定的（固定）容量和指定访问策略的 ArrayBlockingQueue。

ArrayBlockingQueue(int capacity, boolean fair, Collection<? extends E> c)
          创建一个具有给定的（固定）容量和指定访问策略的 ArrayBlockingQueue，它最初包含给定 collection 的元素，并以 collection 迭代器的遍历顺序添加元素。

方法摘要
boolean	add(E e)           将指定的元素插入到此队列的尾部（如果立即可行且不会超过该队列的容量），在成功时返回 true，如果此队列已满，则抛出 IllegalStateException。
void	clear()           自动移除此队列中的所有元素。
boolean	contains(Object o)           如果此队列包含指定的元素，则返回 true。
int	drainTo(Collection<? super E> c)           移除此队列中所有可用的元素，并将它们添加到给定 collection 中。
int	drainTo(Collection<? super E> c, int maxElements)           最多从此队列中移除给定数量的可用元素，并将这些元素添加到给定 collection 中。
Iterator<E>	iterator()           返回在此队列中的元素上按适当顺序进行迭代的迭代器。
boolean	offer(E e)           将指定的元素插入到此队列的尾部（如果立即可行且不会超过该队列的容量），在成功时返回 true，如果此队列已满，则返回 false。
boolean	offer(E e, long timeout, TimeUnit unit)           将指定的元素插入此队列的尾部，如果该队列已满，则在到达指定的等待时间之前等待可用的空间。
E	peek()           获取但不移除此队列的头；如果此队列为空，则返回 null。
E	poll()           获取并移除此队列的头，如果此队列为空，则返回 null。
E	poll(long timeout, TimeUnit unit)           获取并移除此队列的头部，在指定的等待时间前等待可用的元素（如果有必要）。
void	put(E e)           将指定的元素插入此队列的尾部，如果该队列已满，则等待可用的空间。
int	remainingCapacity()           返回在无阻塞的理想情况下（不存在内存或资源约束）此队列能接受的其他元素数量。
boolean	remove(Object o)           从此队列中移除指定元素的单个实例（如果存在）。
int	size()           返回此队列中元素的数量。
E	take()           获取并移除此队列的头部，在元素变得可用之前一直等待（如果有必要）。
Object[]	toArray()           返回一个按适当顺序包含此队列中所有元素的数组。
<T> T[]	toArray(T[] a)           返回一个按适当顺序包含此队列中所有元素的数组；返回数组的运行时类型是指定数组的运行时类型。
String	toString()           返回此 collection 的字符串表示形式。

 

public ArrayBlockingQueue(int capacity) 　　创建一个带有给定的（固定）容量和默认访问策略的 ArrayBlockingQueue。
　　参数：
　　　　capacity - 此队列的容量
　　抛出：
　　　　IllegalArgumentException - 如果 capacity 小于 1

public ArrayBlockingQueue(int capacity,boolean fair)　　创建一个具有给定的（固定）容量和指定访问策略的 ArrayBlockingQueue。
　　参数：
　　　　capacity - 此队列的容量
　　　　fair - 如果为 true，则按照 FIFO 顺序访问插入或移除时受阻塞线程的队列；如果为 false，则访问顺序是不确定的。
　　抛出：
　　　　IllegalArgumentException - 如果 capacity 小于 1

public ArrayBlockingQueue(int capacity,boolean fair,Collection<? extends E> c)
创建一个具有给定的（固定）容量和指定访问策略的 ArrayBlockingQueue，它最初包含给定 collection 的元素，并以 collection 迭代器的遍历顺序添加元素。
　　参数：
　　　　capacity - 此队列的容量
　　　　fair - 如果为 true，则按照 FIFO 顺序访问插入或移除时受阻塞线程的队列；如果为 false，则访问顺序是不确定的。
　　　　c - 最初要包含的元素的 collection
　　抛出：
　　　　IllegalArgumentException - 如果 capacity 小于 c.size()，或者小于 1
　　　　NullPointerException - 如果指定 collection 或任何其元素为 null

add
public boolean add(E e)
　　　　将指定的元素插入到此队列的尾部（如果立即可行且不会超过该队列的容量），在成功时返回 true，如果此队列已满，则抛出 IllegalStateException。
　　　　指定者：
　　　　　　接口 Collection<E> 中的 add
　　　　指定者：
　　　　　　接口 BlockingQueue<E> 中的 add
　　　　指定者：
　　　　　　接口 Queue<E> 中的 add
　　　　覆盖：
　　　　　　类 AbstractQueue<E> 中的 add
　　　　参数：
　　　　　　e - 要添加的元素
　　　　返回：
　　　　　　true（根据 Collection.add(E) 的规定）
　　　　抛出：
　　　　　　IllegalStateException - 如果此队列已满
　　　　　　NullPointerException - 如果指定的元素为 null

offer
public boolean offer(E e)
　　　　将指定的元素插入到此队列的尾部（如果立即可行且不会超过该队列的容量），在成功时返回 true，如果此队列已满，则返回 false。

　　　　此方法通常要优于 add(E) 方法，后者可能无法插入元素，而只是抛出一个异常。
　　　　指定者：
　　　　　　接口 BlockingQueue<E> 中的 offer
　　　　指定者：
　　　　　　接口 Queue<E> 中的 offer
　　　　参数：
　　　　　　e - 要添加的元素
　　　　返回：
　　　　　　如果该元素已添加到此队列，则返回 true；否则返回 false
　　　　抛出：
　　　　　　NullPointerException - 如果指定的元素为 null

put
public void put(E e) throws InterruptedException
　　　　将指定的元素插入此队列的尾部，如果该队列已满，则等待可用的空间。
　　　　指定者：
　　　　　　接口 BlockingQueue<E> 中的 put
　　　　参数：
　　　　　　e - 要添加的元素
　　　　抛出：
　　　　　　InterruptedException - 如果在等待时被中断
　　　　　　NullPointerException - 如果指定元素为 null

offer
public boolean offer(E e,long timeout,TimeUnit unit) throws InterruptedException
　　　　将指定的元素插入此队列的尾部，如果该队列已满，则在到达指定的等待时间之前等待可用的空间。
　　　　指定者：
　　　　　　接口 BlockingQueue<E> 中的 offer
　　　　参数：
　　　　　　e - 要添加的元素
　　　　　　timeout - 放弃之前等待的时间长度，以 unit 为时间单位
　　　　　　unit - 确定如何解释 timeout 参数的 TimeUnit
　　　　返回：
　　　　　　如果成功，则返回 true；如果在空间可用前超过了指定的等待时间，则返回 false
　　　　抛出：
　　　　　　InterruptedException - 如果在等待时被中断
　　　　　　NullPointerException - 如果指定元素为 null

poll
public E poll()
　　　　从接口 Queue 复制的描述
　　　　获取并移除此队列的头，如果此队列为空，则返回 null。
　　　　指定者：
　　　　　　接口 Queue<E> 中的 poll

　　　　返回：
　　　　　　队列的头，如果此队列为空，则返回 null

take
public E take() throws InterruptedException
　　　　从接口 BlockingQueue 复制的描述
　　　　获取并移除此队列的头部，在元素变得可用之前一直等待（如果有必要）。
　　　　指定者：
　　　　　　接口 BlockingQueue<E> 中的 take
　　　　返回：
　　　　　　此队列的头部
　　　　抛出：
　　　　　　InterruptedException - 如果在等待时被中断

poll
public E poll(long timeout,TimeUnit unit) throws InterruptedException
　　　　从接口 BlockingQueue 复制的描述
　　　　获取并移除此队列的头部，在指定的等待时间前等待可用的元素（如果有必要）。
　　　　指定者：
　　　　　　接口 BlockingQueue<E> 中的 poll
　　　　参数：
　　　　　　timeout - 放弃之前要等待的时间长度，用 unit 的时间单位表示
　　　　　　unit - 确定如何解释 timeout 参数的 TimeUnit
　　　　返回：
　　　　　　此队列的头部；如果在元素可用前超过了指定的等待时间，则返回 null
　　　　抛出：
　　　　　　InterruptedException - 如果在等待时被中断

peek
public E peek()
　　　　从接口 Queue 复制的描述
　　　　获取但不移除此队列的头；如果此队列为空，则返回 null。
　　　　指定者：
　　　　　　接口 Queue<E> 中的 peek
　　　　返回：
　　　　　　此队列的头；如果此队列为空，则返回 null

size
public int size()
　　　　返回此队列中元素的数量。
　　　　指定者：
　　　　　　接口 Collection<E> 中的 size
　　　　指定者：
　　　　　　类 AbstractCollection<E> 中的 size
　　　　返回：
　　　　　　返回此队列中元素的数量

remainingCapacity
public int remainingCapacity()
　　　　返回在无阻塞的理想情况下（不存在内存或资源约束）此队列能接受的其他元素数量。它总是等于此队列初始容量，但小于此队列当前的 size。
　　　　注意，不能 总是通过检查 remainingCapacity 来判断尝试插入元素能否成功，因为可能出现这样的情况：另一个线程将插入或移除一个元素。
　　　　指定者：
　　　　　　接口 BlockingQueue<E> 中的 remainingCapacity
　　　　返回：
　　　　　　剩余容量

remove
public boolean remove(Object o)
　　　　从此队列中移除指定元素的单个实例（如果存在）。
　　　　更确切地讲，如果此队列包含一个或多个满足 o.equals(e) 的元素 e，则移除该元素。如果此队列包含指定的元素（或者此队列由于调用而发生更改），则返回 true。
　　　　指定者：
　　　　　　接口 Collection<E> 中的 remove
　　　　指定者：
　　　　　　接口 BlockingQueue<E> 中的 remove
　　　　覆盖：
　　　　　　类 AbstractCollection<E> 中的 remove
　　　　参数：
　　　　　　o - 要从此队列中移除的元素（如果存在）
　　　　返回：
　　　　　　如果此队列由于调用而发生更改，则返回 true

contains
public boolean contains(Object o)
　　　　如果此队列包含指定的元素，则返回 true。更确切地讲，当且仅当此队列至少包含一个满足 o.equals(e) 的元素 e 时，返回 true。
　　　　指定者：
　　　　　　接口 Collection<E> 中的 contains
　　　　指定者：
　　　　　　接口 BlockingQueue<E> 中的 contains
　　　　覆盖：
　　　　　　类 AbstractCollection<E> 中的 contains
　　　　参数：
　　　　　　o - 检查是否包含在此队列中的对象
　　　　返回：
　　　　　　如果此队列包含指定的元素，则返回 true

toArray
public Object[] toArray()
　　　　返回一个按适当顺序包含此队列中所有元素的数组。
　　　　由于此队列不维护对返回数组的任何引用，因而它是“安全的”。（换句话说，此方法必须分配一个新数组）。因此，调用者可以随意修改返回的数组。
　　　　此方法充当基于数组的 API 与基于 collection 的 API 之间的桥梁。
　　　　指定者：
　　　　　　接口 Collection<E> 中的 toArray
　　　　覆盖：
　　　　　　类 AbstractCollection<E> 中的 toArray
　　　　返回：
　　　　　　包含此队列所有元素的数组

toArray
public <T> T[] toArray(T[] a)
　　　　返回一个按适当顺序包含此队列中所有元素的数组；返回数组的运行时类型是指定数组的运行时类型。
　　　　如果指定的数组能容纳该队列，则将该队列返回此处。否则，将分配一个具有指定数组的运行时类型和此队列大小的新数组。
　　　　如果指定的数组能容纳此队列，并有剩余空间（即数组的元素比此队列的多），则将数组中紧接队列末尾的元素设置为 null。
　　　　像 toArray() 方法一样，此方法充当基于数组的 API 与基于 collection 的 API 之间的桥梁。

　　　　更进一步地说，此方法允许对输出数组的运行时类型进行精确控制，在某些情况下，可以用来节省分配开销。
　　　　假定 x 是只包含字符串的一个已知队列。以下代码用来将该队列转储到一个新分配的 String 数组：
　　　　String[] y = x.toArray(new String[0]);
　　　　注意，toArray(new Object[0]) 和 toArray() 在功能上是相同的。

　　　　指定者：
　　　　　　接口 Collection<E> 中的 toArray
　　　　覆盖：
　　　　　　类 AbstractCollection<E> 中的 toArray
　　　　参数：
　　　　　　a - 要在其中存储队列元素的数组（如果它足够大）；否则，将为此分配一个具有相同运行时类型的新数组。
　　　　返回：
　　　　　　包含此队列中所有元素的数组
　　　　抛出：
　　　　　　ArrayStoreException - 如果指定数组的运行时类型不是此队列中每个元素的运行时类型的超类型
　　　　　　NullPointerException - 如果指定数组为 null

toString
public String toString()
　　　　从类 AbstractCollection 复制的描述
　　　　返回此 collection 的字符串表示形式。该字符串表示形式由 collection 元素的列表组成，这些元素按其迭代器返回的顺序排列，

　　　　并用方括号 ("[]") 括起来。相邻元素由字符 ", "（逗号加空格）分隔。通过 String.valueOf(Object) 可以将元素转换成字符串。
　　　　覆盖：
　　　　　　类 AbstractCollection<E> 中的 toString
　　　　返回：
　　　　　　此 collection 的字符串表示形式

clear
public void clear()
　　　　自动移除此队列中的所有元素。在此调用返回之后，队列将为空。
　　　　指定者：
　　　　　　接口 Collection<E> 中的 clear
　　　　覆盖：
　　　　　　类 AbstractQueue<E> 中的 clear

drainTo
public int drainTo(Collection<? super E> c)
　　　　从接口 BlockingQueue 复制的描述
　　　　移除此队列中所有可用的元素，并将它们添加到给定 collection 中。
　　　　此操作可能比反复轮询此队列更有效。在试图向 collection c 中添加元素没有成功时，可能导致在抛出相关异常时，

　　　　元素会同时在两个 collection 中出现，或者在其中一个 collection 中出现，也可能在两个 collection 中都不出现。
　　　　如果试图将一个队列放入自身队列中，则会导致 IllegalArgumentException 异常。

　　　　此外，如果正在进行此操作时修改指定的 collection，则此操作行为是不确定的。

　　　　指定者：
　　　　　　接口 BlockingQueue<E> 中的 drainTo
　　　　参数：
　　　　　　c - 接收传输元素的 collection
　　　　返回：
　　　　　　传输元素的数量
　　　　抛出：
　　　　　　UnsupportedOperationException - 如果指定 collection 不支持添加元素
　　　　　　ClassCastException - 如果此队列元素的类不允许将其添加到指定 collection
　　　　　　NullPointerException - 如果指定 collection 为 null
　　　　　　IllegalArgumentException - 如果指定 collection 是此队列，或者此队列元素的某些属性不允许将其添加到指定 collection

drainTo
public int drainTo(Collection<? super E> c,int maxElements)
　　　　从接口 BlockingQueue 复制的描述
　　　　最多从此队列中移除给定数量的可用元素，并将这些元素添加到给定 collection 中。
　　　　在试图向 collection c 中添加元素没有成功时，可能导致在抛出相关异常时，元素会同时在两个 collection 中出现，

　　　　或者在其中一个 collection 中出现，也可能在两个 collection 中都不出现。
　　　　如果试图将一个队列放入自身队列中，则会导致 IllegalArgumentException 异常。此外，如果正在进行此操作时修改指定的 collection，则此操作行为是不确定的。
　　　　指定者：
　　　　　　接口 BlockingQueue<E> 中的 drainTo
　　　　参数：
　　　　　　c - 接收传输元素的 collection
　　　　　　maxElements - 传输元素的最大数量
　　　　返回：
　　　　　　传输元素的数量
　　　　抛出：
　　　　　　UnsupportedOperationException - 如果指定 collection 不支持添加元素
　　　　　　ClassCastException - 如果此队列元素的类不允许将其添加到指定 collection
　　　　　　NullPointerException - 如果指定 collection 为 null
　　　　　　IllegalArgumentException - 如果指定 collection 是此队列，或者此队列元素的某些属性不允许将其添加到指定 collection

iterator
public Iterator<E> iterator()
　　　　返回在此队列中的元素上按适当顺序进行迭代的迭代器。
　　　　返回的 Iterator 是一个“弱一致”的迭代器，从不抛出 ConcurrentModificationException，

　　　　并且确保可遍历迭代器构造时存在的元素，此外还可能（但并不保证）反映构造后的所有修改。
　　　　指定者：
　　　　　　接口 Iterable<E> 中的 iterator
　　　　指定者：
　　　　　　接口 Collection<E> 中的 iterator
　　　　指定者：
　　　　　　类 AbstractCollection<E> 中的 iterator

　　　　返回：
　　　　　　在队列中的元素上按适当顺序进行迭代的迭代器