模块 java.base
包 java.util.concurrent

类 ArrayBlockingQueue<E>

java.lang.Object
java.util.AbstractCollection <E>
java.util.AbstractQueue <E>
java.util.concurrent.ArrayBlockingQueue<E>
类型参数：
E - 此队列中保存的元素类型
所有已实现的接口：
Serializable , Iterable<E> , Collection<E> , BlockingQueue<E> , Queue<E>
public class ArrayBlockingQueue<E> extends AbstractQueue <E> implements BlockingQueue <E>, Serializable
由数组支持的有界 阻塞队列。该队列对元素进行 FIFO（先进先出）排序。队列的 head 是队列中时间最长的元素。队列的 tail 是在队列中时间最短的元素。新元素插入队列尾部，队列检索操作获取队列头部元素。

这是一个经典的“有界缓冲区”，其中固定大小的数组保存生产者插入和消费者提取的元素。容量一旦创建，便无法更改。尝试将 put 元素放入已满队列将导致操作阻塞；尝试take空队列中的元素将类似地阻塞。

此类支持用于排序等待生产者和消费者线程的可选公平策略。默认情况下，不保证此顺序。但是，公平性设置为 true 的队列以 FIFO 顺序授予线程访问权限。公平通常会降低吞吐量，但会减少可变性并避免饥饿。

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

此类是 Java 集合框架 的成员。

自从：
1.5
参见：

  • 构造方法总结

    构造方法
    构造方法
    描述
    ArrayBlockingQueue(int capacity)
    创建具有给定（固定）容量和默认访问策略的ArrayBlockingQueue。
    ArrayBlockingQueue(int capacity, boolean fair)
    创建具有给定（固定）容量和指定访问策略的 ArrayBlockingQueue。
    ArrayBlockingQueue(int capacity, boolean fair, Collection<? extends E> c)
    创建具有给定（固定）容量、指定访问策略并最初包含给定集合元素的ArrayBlockingQueue，按集合迭代器的遍历顺序添加。

  • 方法总结

    修饰符和类型
    方法
    描述
    boolean
    add(E e)
    如果可以在不超过队列容量的情况下立即插入指定元素，则将指定元素插入此队列的尾部，成功时返回 true，如果此队列已满则抛出 IllegalStateException。
    void
    clear()
    以原子方式从此队列中删除所有元素。
    boolean
    contains(Object o)
    如果此队列包含指定元素，则返回 true。
    int
    drainTo(Collection<? super E> c)
    从此队列中删除所有可用元素并将它们添加到给定集合中。
    int
    drainTo(Collection<? super E> c, int maxElements)
    从此队列中最多移除给定数量的可用元素，并将它们添加到给定的集合中。
    void
    forEach(Consumer<? super E> action)
    对 Iterable 的每个元素执行给定的操作，直到处理完所有元素或操作引发异常。
    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)
    从此队列中移除指定元素的单个实例（如果存在）。
    boolean
    removeAll(Collection<?> c)
    删除此集合的所有也包含在指定集合中的元素（可选操作）。
    boolean
    removeIf(Predicate<? super E> filter)
    移除此集合中满足给定谓词的所有元素。
    boolean
    retainAll(Collection<?> c)
    仅保留此集合中包含在指定集合中的元素（可选操作）。
    int
    size()
    返回此队列中的元素数。
    Spliterator<E>
    spliterator()
    在此队列中的元素上返回一个 Spliterator 。
    E
    take()
    检索并删除此队列的头部，必要时等待直到元素可用。
    Object[]
    toArray()
    以正确的顺序返回包含此队列中所有元素的数组。
    <T> T[]
    toArray(T[] a)
    以适当的顺序返回一个包含此队列中所有元素的数组；返回数组的运行时类型是指定数组的类型。

    在类 java.util.AbstractQueue 中声明的方法

    addAll, element, remove

    在类 java.util.AbstractCollection 中声明的方法

    containsAll, isEmpty, toString

    在类 java.lang.Object 中声明的方法

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

    在接口 java.util.Collection 中声明的方法

    addAll, containsAll, equals, hashCode, isEmpty, parallelStream, stream, toArray

    在接口 java.util.Queue 中声明的方法

    element, remove

  • 构造方法详细信息

    • 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，按集合迭代器的遍历顺序添加。
      参数：
      capacity - 这个队列的容量
      fair - 如果 true 那么在插入或移除时阻塞的线程的队列访问将按 FIFO 顺序处理；如果 false 未指定访问顺序。
      c - 最初包含的元素集合
      抛出：
      IllegalArgumentException - 如果 capacity 小于 c.size() 或小于 1。
      NullPointerException - 如果指定的集合或其任何元素为空

  • 方法详情

    • add

      public boolean add(E  e)
      如果可以在不超过队列容量的情况下立即插入指定元素，则将指定元素插入此队列的尾部，成功时返回 true，如果此队列已满则抛出 IllegalStateException。
      指定者：
      add 在接口 BlockingQueue<E> 中
      指定者：
      add 在接口 Collection<E> 中
      指定者：
      add 在接口 Queue<E> 中
      重写：
      add 在类 AbstractQueue<E> 中
      参数：
      e - 要添加的元素
      返回：
      true（由 Collection.add(E) 指定）
      抛出：
      IllegalStateException - 如果这个队列已满
      NullPointerException - 如果指定元素为空

    • offer

      public boolean offer(E  e)
      如果可以在不超过队列容量的情况下立即插入指定元素，则将指定元素插入此队列的尾部，成功时返回 true，如果此队列已满则返回 false。此方法通常优于方法 add(E) ，后者仅通过抛出异常才能插入元素失败。
      指定者：
      offer 在接口 BlockingQueue<E> 中
      指定者：
      offer 在接口 Queue<E> 中
      参数：
      e - 要添加的元素
      返回：
      true 如果元素被添加到这个队列，否则 false
      抛出：
      NullPointerException - 如果指定元素为空

    • put

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

    • offer

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

    • poll

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

    • take

      public E  take() throws InterruptedException
      从接口 BlockingQueue 复制的描述
      检索并删除此队列的头部，必要时等待直到元素可用。
      指定者：
      take 在接口 BlockingQueue<E> 中
      返回：
      这个队列的头
      抛出：
      InterruptedException - 如果在等待时被打断

    • poll

      public E  poll(long timeout, TimeUnit  unit) throws InterruptedException
      从接口 BlockingQueue 复制的描述
      检索并删除此队列的头部，如有必要，等待指定的等待时间以使元素可用。
      指定者：
      poll 在接口 BlockingQueue<E> 中
      参数：
      timeout - 放弃前等待多长时间，以 unit 为单位
      unit - 一个 TimeUnit 决定如何解释 timeout 参数
      返回：
      此队列的头部，或者 null 如果指定的等待时间在元素可用之前过去
      抛出：
      InterruptedException - 如果在等待时被打断

    • peek

      public E  peek()
      从接口 Queue 复制的描述
      检索但不删除此队列的头部，如果此队列为空，则返回 null。
      指定者：
      peek 在接口 Queue<E> 中
      返回：
      此队列的头部，或 null 如果此队列为空

    • size

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

    • remainingCapacity

      public int remainingCapacity()
      返回此队列可以理想地（在没有内存或资源限制的情况下）无阻塞地接受的附加元素的数量。这始终等于此队列的初始容量减去此队列的当前size。

      请注意，您 cannot 总是通过检查 remainingCapacity 来判断插入元素的尝试是否会成功，因为可能是另一个线程即将插入或删除元素的情况。

      指定者：
      remainingCapacity 在接口 BlockingQueue<E> 中
      返回：
      剩余容量

    • remove

      public boolean remove(Object  o)
      从此队列中移除指定元素的单个实例（如果存在）。更正式地说，如果此队列包含一个或多个此类元素，则删除一个元素 e 使得 o.equals(e) 。如果此队列包含指定元素，则返回 true（或者等效地，如果此队列因调用而更改）。

      删除基于循环数组的队列中的内部元素本质上是一种缓慢且具有破坏性的操作，因此应仅在特殊情况下进行，理想情况下仅在已知其他线程无法访问该队列时才进行。

      指定者：
      remove 在接口 BlockingQueue<E> 中
      指定者：
      remove 在接口 Collection<E> 中
      重写：
      remove 在类 AbstractCollection<E> 中
      参数：
      o - 要从此队列中删除的元素（如果存在）
      返回：
      true 如果此队列因调用而更改

    • contains

      public boolean contains(Object  o)
      如果此队列包含指定元素，则返回 true。更正式地说，返回 true 当且仅当此队列包含至少一个元素 e 使得 o.equals(e) 。
      指定者：
      contains 在接口 BlockingQueue<E> 中
      指定者：
      contains 在接口 Collection<E> 中
      重写：
      contains 在类 AbstractCollection<E> 中
      参数：
      o - 要检查此队列中包含的对象
      返回：
      true 如果此队列包含指定元素

    • toArray

      public Object [] toArray()
      以正确的顺序返回包含此队列中所有元素的数组。

      返回的数组将是“安全的”，因为此队列不维护对它的引用。 （换句话说，这个方法必须分配一个新数组）。调用者因此可以自由修改返回的数组。

      此方法充当基于数组和基于集合的 API 之间的桥梁。

      指定者：
      toArray 在接口 Collection<E> 中
      重写：
      toArray 在类 AbstractCollection<E> 中
      返回：
      包含此队列中所有元素的数组

    • toArray

      public <T> T[] toArray(T[] a)
      以适当的顺序返回一个包含此队列中所有元素的数组；返回数组的运行时类型是指定数组的类型。如果队列适合指定的数组，则在其中返回。否则，将分配一个新数组，其中包含指定数组的运行时类型和此队列的大小。

      如果此队列适合指定的数组并有剩余空间（即，数组的元素多于此队列），则紧接队列末尾的数组中的元素设置为 null 。

      与 toArray() 方法一样，此方法充当基于数组和基于集合的 API 之间的桥梁。此外，此方法允许精确控制输出数组的运行时类型，并且在某些情况下可用于节省分配成本。

      假设 x 是已知仅包含字符串的队列。以下代码可用于将队列转储到新分配的 String 数组中：

       String[] y = x.toArray(new String[0]);
      请注意，toArray(new Object[0]) 在功能上与 toArray() 相同。
      指定者：
      toArray 在接口 Collection<E> 中
      重写：
      toArray 在类 AbstractCollection<E> 中
      类型参数：
      T - 包含集合的数组的组件类型
      参数：
      a - 要存储队列元素的数组，如果它足够大的话；否则，为此分配一个相同运行时类型的新数组
      返回：
      包含此队列中所有元素的数组
      抛出：
      ArrayStoreException - 如果指定数组的运行时类型不是此队列中每个元素的运行时类型的超类型
      NullPointerException - 如果指定数组为空

    • clear

      public void clear()
      以原子方式从此队列中删除所有元素。此调用返回后队列将为空。
      指定者：
      clear 在接口 Collection<E> 中
      重写：
      clear 在类 AbstractQueue<E> 中

    • drainTo

      public int drainTo(Collection <? super E > c)
      从接口 BlockingQueue 复制的描述
      从此队列中删除所有可用元素并将它们添加到给定集合中。此操作可能比重复轮询此队列更有效。尝试将元素添加到集合 c 时遇到的失败可能会导致在抛出相关异常时元素不在任何一个或两个集合中。尝试将队列排空到自身会导致 IllegalArgumentException 。此外，如果指定的集合在操作过程中被修改，则此操作的行为是未定义的。
      指定者：
      drainTo 在接口 BlockingQueue<E> 中
      参数：
      c - 将元素转移到的集合
      返回：
      转移的元素数量
      抛出：
      UnsupportedOperationException - 如果指定集合不支持添加元素
      ClassCastException - 如果此队列元素的类阻止将其添加到指定集合
      NullPointerException - 如果指定的集合为空
      IllegalArgumentException - 如果指定的集合是这个队列，或者这个队列元素的某些属性阻止它被添加到指定的集合

    • drainTo

      public int drainTo(Collection <? super E > c, int maxElements)
      从接口 BlockingQueue 复制的描述
      从此队列中最多移除给定数量的可用元素，并将它们添加到给定的集合中。尝试将元素添加到集合 c 时遇到的失败可能会导致在抛出相关异常时元素不在任何一个或两个集合中。尝试将队列排空到自身会导致 IllegalArgumentException 。此外，如果指定的集合在操作过程中被修改，则此操作的行为是未定义的。
      指定者：
      drainTo 在接口 BlockingQueue<E> 中
      参数：
      c - 将元素转移到的集合
      maxElements - 要传输的最大元素数
      返回：
      转移的元素数量
      抛出：
      UnsupportedOperationException - 如果指定集合不支持添加元素
      ClassCastException - 如果此队列元素的类阻止将其添加到指定集合
      NullPointerException - 如果指定的集合为空
      IllegalArgumentException - 如果指定的集合是这个队列，或者这个队列元素的某些属性阻止它被添加到指定的集合

    • iterator

      public Iterator <E > iterator()
      按正确顺序返回此队列中元素的迭代器。元素将按从第一个（头）到最后一个（尾）的顺序返回。

      返回的迭代器是 弱一致 。

      指定者：
      iterator 在接口 Collection<E> 中
      指定者：
      iterator 在接口 Iterable<E> 中
      指定者：
      iterator 在类 AbstractCollection<E> 中
      返回：
      以适当顺序对该队列中的元素进行迭代

    • spliterator

      public Spliterator <E > spliterator()
      在此队列中的元素上返回一个 Spliterator 。

      返回的拆分器是 弱一致 。

      Spliterator 报告 Spliterator.CONCURRENT 、Spliterator.ORDERED 和 Spliterator.NONNULL 。

      指定者：
      spliterator 在接口 Collection<E> 中
      指定者：
      spliterator 在接口 Iterable<E> 中
      实现注意事项：
      Spliterator 实现 trySplit 以允许有限的并行性。
      返回：
      a Spliterator 遍历此队列中的元素
      自从：
      1.8

    • forEach

      public void forEach(Consumer <? super E > action)
      从接口 Iterable 复制的描述
      对 Iterable 的每个元素执行给定的操作，直到处理完所有元素或操作引发异常。如果指定了迭代顺序，则将按迭代顺序执行操作。操作抛出的异常被转发给调用者。

      如果操作执行修改元素的底层源的副作用，则此方法的行为是未指定的，除非重写类已指定并发修改策略。

      指定者：
      forEach 在接口 Iterable<E> 中
      参数：
      action - 对每个元素执行的操作
      抛出：
      NullPointerException - 如果指定的操作为空

    • removeIf

      public boolean removeIf(Predicate <? super E > filter)
      从接口 Collection 复制的描述
      移除此集合中满足给定谓词的所有元素。迭代期间或由谓词抛出的错误或运行时异常将传递给调用者。
      指定者：
      removeIf 在接口 Collection<E> 中
      参数：
      filter - 为要删除的元素返回 true 的谓词
      返回：
      true 如果删除了任何元素
      抛出：
      NullPointerException - 如果指定的过滤器为空

    • removeAll

      public boolean removeAll(Collection <?> c)
      从类复制的描述：AbstractCollection
      删除此集合的所有也包含在指定集合中的元素（可选操作）。此调用返回后，此集合将不包含与指定集合共有的元素。
      指定者：
      removeAll 在接口 Collection<E> 中
      重写：
      removeAll 在类 AbstractCollection<E> 中
      参数：
      c - 包含要从此集合中删除的元素的集合
      返回：
      true 如果此集合因调用而更改
      抛出：
      NullPointerException - 如果此集合包含一个或多个空元素并且指定的集合不支持空元素 (optional)，或者如果指定的集合为空
      参见：

    • retainAll

      public boolean retainAll(Collection <?> c)
      从类复制的描述：AbstractCollection
      仅保留此集合中包含在指定集合中的元素（可选操作）。换句话说，从该集合中移除所有未包含在指定集合中的元素。
      指定者：
      retainAll 在接口 Collection<E> 中
      重写：
      retainAll 在类 AbstractCollection<E> 中
      参数：
      c - 包含要保留在此集合中的元素的集合
      返回：
      true 如果此集合因调用而更改
      抛出：
      NullPointerException - 如果此集合包含一个或多个空元素并且指定的集合不允许空元素 (optional)，或者如果指定的集合为空
      参见：