java.util.concurrent
类 ArrayBlockingQueue<E>

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

类型参数：

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

所有已实现的接口：

Serializable, Iterable<E>, Collection<E>, BlockingQueue<E>, Queue<E>

public class ArrayBlockingQueue<E>
extends AbstractQueue<E>
implements BlockingQueue<E>, Serializable

一个由数组支持的有界阻塞队列。此队列按 FIFO（先进先出）原则对元素进行排序。队列的头部 是在队列中存在时间最长的元素。队列的尾部 是在队列中存在时间最短的元素。新元素插入到队列的尾部，队列检索操作则是从队列头部开始获得元素。

这是一个典型的“有界缓存区”，固定大小的数组在其中保持生产者插入的元素和使用者提取的元素。一旦创建了这样的缓存区，就不能再增加其容量。试图向已满队列中放入元素会导致放入操作受阻塞；试图从空队列中检索元素将导致类似阻塞。

此类支持对等待的生产者线程和使用者线程进行排序的可选公平策略。默认情况下，不保证是这种排序。然而，通过将公平性 (fairness) 设置为 true 而构造的队列允许按照 FIFO 顺序访问线程。公平性通常会降低吞吐量，但也减少了可变性和避免了“不平衡性”。

此类及其迭代器实现了 Collection 和 Iterator 接口的所有可选 方法。

此类是 Java Collections Framework 的成员。

从以下版本开始：

1.5

另请参见：

序列化表格

构造方法摘要

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

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

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

方法摘要

void	clear() 自动移除此队列中的所有元素。
boolean	contains(Object o) 如果此 collection 包含指定的元素，则返回 true。
int	drainTo(Collection<? super E> c) 移除此队列中所有可用的元素，并将它们添加到给定 collection 中。
int	drainTo(Collection<? super E> c, int maxElements) 最多从此队列中移除给定数量的可用元素，并将这些元素添加到给定 collection 中。
Iterator<E>	iterator() 返回在此队列中的元素上以正确顺序进行迭代的迭代器。
boolean	offer(E o) 将指定的元素插入到此队列的尾部（如果可能），如果此队列已满，则立即返回。
boolean	offer(E o, long timeout, TimeUnit unit) 将指定的元素插入到此队列的尾部，如果没有可用空间，将等待指定的等待时间（如果有必要）。
E	peek() 检索，但是不移除此队列的头，如果此队列为空，则返回 null。
E	poll() 检索并移除此队列的头，如果此队列为空，则返回 null。
E	poll(long timeout, TimeUnit unit) 检索并移除此队列的头部，如果此队列中没有任何元素，则等待指定等待的时间（如果有必要）。
void	put(E o) 将指定的元素添加到此队列的尾部，如果必要，将等待可用的空间。
int	remainingCapacity() 返回在无阻塞的理想情况下（不存在内存或资源约束）此队列能接受的元素数量。
boolean	remove(Object o) 从此队列中移除指定元素的一个实例（如果存在）。
int	size() 返回此队列中元素的数量。
E	take() 检索并移除此队列的头部，如果此队列不存在任何元素，则一直等待。
Object[]	toArray() 返回包含此 collection 中所有元素的数组。
<T> T[]	toArray(T[] a) 返回包含此 collection 中所有元素的数组；返回数组的运行时类型是指定数组的类型。
String	toString() 返回此 collection 的字符串表示形式。

从类 java.util.AbstractQueue 继承的方法

add, addAll, element, remove

从类 java.util.AbstractCollection 继承的方法

containsAll, isEmpty, removeAll, retainAll

从类 java.lang.Object 继承的方法

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

从接口 java.util.concurrent.BlockingQueue 继承的方法

add

从接口 java.util.Queue 继承的方法

element, remove

从接口 java.util.Collection 继承的方法

addAll, containsAll, equals, hashCode, isEmpty, removeAll, retainAll

构造方法详细信息

ArrayBlockingQueue

public ArrayBlockingQueue(int capacity)

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

参数：

capacity - 此队列的容量

抛出：

IllegalArgumentException - 如果 capacity 小于 1

ArrayBlockingQueue

public ArrayBlockingQueue(int capacity,
                          boolean fair)

创建一个具有给定的（固定）容量和指定访问策略的 ArrayBlockingQueue。

参数：

capacity - 此队列的容量

fair - 如果为 true，则按照 FIFO 顺序访问插入或移除时受阻塞线程的队列；如果为 false，则访问顺序是不确定的。

抛出：

IllegalArgumentException - 如果 capacity 小于 1

ArrayBlockingQueue

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 - 如果 c 或其中任何元素为 null

方法详细信息

offer

public boolean offer(E o)

将指定的元素插入到此队列的尾部（如果可能），如果此队列已满，则立即返回。

指定者：

接口 BlockingQueue<E> 中的 offer

指定者：

接口 Queue<E> 中的 offer

参数：

o - 要添加的元素。

返回：

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

抛出：

NullPointerException - 如果指定的元素为 null

offer

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

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

指定者：

接口 BlockingQueue<E> 中的 offer

参数：

o - 要添加的元素

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

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

返回：

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

抛出：

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

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

poll

public E poll()

从接口 Queue 复制的描述

检索并移除此队列的头，如果此队列为空，则返回 null。

指定者：

接口 Queue<E> 中的 poll

返回：

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

poll

public E poll(long timeout,
              TimeUnit unit)
       throws InterruptedException

从接口 BlockingQueue 复制的描述

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

指定者：

接口 BlockingQueue<E> 中的 poll

参数：

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

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

返回：

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

抛出：

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

remove

public boolean remove(Object o)

从此队列中移除指定元素的一个实例（如果存在）。

指定者：

接口 Collection<E> 中的 remove

覆盖：

类 AbstractCollection<E> 中的 remove

参数：

o - 要从此 collection 中移除的元素（如果存在）。

返回：

如果该 collection 包含指定的元素,则返回 true。

peek

public E peek()

从接口 Queue 复制的描述

检索，但是不移除此队列的头，如果此队列为空，则返回 null。

指定者：

接口 Queue<E> 中的 peek

返回：

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

take

public E take()
       throws InterruptedException

从接口 BlockingQueue 复制的描述

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

指定者：

接口 BlockingQueue<E> 中的 take

返回：

此队列的头部

抛出：

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

put

public void put(E o)
         throws InterruptedException

将指定的元素添加到此队列的尾部，如果必要，将等待可用的空间。

指定者：

接口 BlockingQueue<E> 中的 put

参数：

o - 要添加的元素

抛出：

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

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

size

public int size()

返回此队列中元素的数量。

指定者：

接口 Collection<E> 中的 size

指定者：

类 AbstractCollection<E> 中的 size

返回：

返回此队列中元素的数量。

remainingCapacity

public int remainingCapacity()

返回在无阻塞的理想情况下（不存在内存或资源约束）此队列能接受的元素数量。它总是等于此队列初始容量，但小于此队列当前的 size。

注意，不能 总是通过检查 remainingCapacity 来判断尝试 add 元素能否成功，因为可能出现这样的情况：一个等待中的使用者已经准备好从其他已满的队列中 take 一个元素。

指定者：

接口 BlockingQueue<E> 中的 remainingCapacity

返回：

剩余容量

contains

public boolean contains(Object o)

从类 AbstractCollection 复制的描述

如果此 collection 包含指定的元素，则返回 true。更正式地说，当且仅当此 collection 至少包含一个满足以下条件的元素 e 时才返回 true：(o==null ? e==null : o.equals(e))。

此实现迭代该 collection 中的元素，并依次检查每个元素以确定其是否与指定的元素相等。

指定者：

接口 Collection<E> 中的 contains

覆盖：

类 AbstractCollection<E> 中的 contains

参数：

o - 要检查的对象，以确定其是否包含在此 collection 中。

返回：

如果此 collection 包含指定的元素，则返回 true。

toArray

public Object[] toArray()

从类 AbstractCollection 复制的描述

返回包含此 collection 中所有元素的数组。如果此 collection 保证其迭代器按顺序返回其元素，那么此方法也必须按相同的顺序返回这些元素。返回的数组将是“安全的”，因为此 collection 并不维护对返回数组的任何引用。（换句话说，即使 collection 受到数组的支持，此方法也必须分配一个新的数组）。因此，调用方可以随意修改返回的数组。

此实现会分配返回的数组，并迭代 collection 中的元素，将每个对象引用存储在数组的下一个连续元素中，并从元素 0 开始。

指定者：

接口 Collection<E> 中的 toArray

覆盖：

类 AbstractCollection<E> 中的 toArray

返回：

包含此 collection 中所有元素的数组。

toArray

public <T> T[] toArray(T[] a)

从类 AbstractCollection 复制的描述

返回包含此 collection 中所有元素的数组；返回数组的运行时类型是指定数组的类型。如果指定的数组能容纳该 collection，则在此数组中返回 collection 的元素。否则，将根据指定数组的运行时类型和此 collection 的大小分配一个新数组。

如果指定的数组能容纳 collection，并且有剩余的空间（即数组的元素比 collection 多），那么会将紧挨着 collection 尾部的元素设置为 null（这对确定 collection 的长度很有用，但只有 在调用方知道 collection 不包含任何 null 元素时才可行）。

如果此 collection 保证其迭代器按顺序返回其元素，那么此方法也必须按相同的顺序返回这些元素。

此实现会检查该数组是否足够大，以包含该 collection 中的元素；如果不能包含，则将分配一个具有适当大小和类型的新数组（使用反射）。然后，在该 collection 上进行迭代，将每个对象引用存储在数组的下一个连续元素中，并从元素 0 开始。如果该数组比该 collection 大，则在该 collection 尾部后面的第一个位置存储 null。

指定者：

接口 Collection<E> 中的 toArray

覆盖：

类 AbstractCollection<E> 中的 toArray

参数：

a - 存储此 collection 的元素的数组（如果其足够大）；否则，将为此分配一个具有相同运行时类型的新数组。

返回：

包含此 collection 的元素的数组。

toString

public String toString()

从类 AbstractCollection 复制的描述

返回此 collection 的字符串表示形式。该字符串表示形式由 collection 元素的列表组成，这些元素按其迭代器返回的顺序排列，并用方括号 ("[]") 括起来。相邻元素由字符 ", "（逗号加空格）分隔。通过 String.valueOf(Object) 可以将元素转换成字符串。

此实现会创建一个空字符串缓冲区，追加一个左方括号，然后在 collection 上进行迭代，依次追加每个元素的字符串表示形式。每追加一个元素后（最后一个元素除外），将追加字符串 ", "。最后，追加一个右括号。从字符串缓冲区获取一个字符串并返回它。

覆盖：

类 AbstractCollection<E> 中的 toString

返回：

此 collection 的字符串表示形式。

clear

public void clear()

自动移除此队列中的所有元素。在此调用返回之后，队列将为空。

指定者：

接口 Collection<E> 中的 clear

覆盖：

类 AbstractQueue<E> 中的 clear

drainTo

public int drainTo(Collection<? super E> c)

从接口 BlockingQueue 复制的描述

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

指定者：

接口 BlockingQueue<E> 中的 drainTo

参数：

c - 接收传输元素的 collection

返回：

传输元素的数量。

drainTo

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

从接口 BlockingQueue 复制的描述

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

指定者：

接口 BlockingQueue<E> 中的 drainTo

参数：

c - 接收传输元素的 collection

maxElements - 传输元素的最大数量

返回：

传输元素的数量。

iterator

public Iterator<E> iterator()

返回在此队列中的元素上以正确顺序进行迭代的迭代器。返回的 Iterator 是一个“弱一致”的迭代器，从不抛出 ConcurrentModificationException，并且确保可遍历迭代器构造时存在的元素，此外还可能（但并不保证）反映构造后的所有修改。

指定者：

接口 Iterable<E> 中的 iterator

指定者：

接口 Collection<E> 中的 iterator

指定者：

类 AbstractCollection<E> 中的 iterator

返回：

在队列中的元素上以正确顺序进行迭代的迭代器。