Module java.base
Package java.util.concurrent

Class 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（先进先出）顺序排列元素。队列的头部是在队列中时间最长的元素。队列的尾部是在队列中时间最短的元素。新元素被插入到队列的尾部，队列检索操作获取队列头部的元素。

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

此类支持对等待的生产者和消费者线程进行排序的可选公平策略。默认情况下，此排序不被保证。然而，使用公平性设置为true构造的队列按FIFO顺序授予线程访问。公平性通常会降低吞吐量，但减少了变异性并避免了饥饿。

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

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

自 JDK 版本:
1.5
参见:

  • Constructor Summary

    Constructors
    Constructor
    Description
    ArrayBlockingQueue(int capacity)
    使用给定的（固定）容量和默认访问策略创建一个ArrayBlockingQueue。
    ArrayBlockingQueue(int capacity, boolean fair)
    使用给定的（固定）容量和指定的访问策略创建一个ArrayBlockingQueue。
    ArrayBlockingQueue(int capacity, boolean fair, Collection<? extends E> c)
    使用给定的（固定）容量、指定的访问策略和最初包含给定集合中元素的ArrayBlockingQueue，按照集合迭代器的遍历顺序添加。

  • Method Summary

    Modifier and Type
    Method
    Description
    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)
    返回一个包含此队列中所有元素的数组，以正确的顺序；返回数组的运行时类型与指定数组的类型相同。

    Methods declared in class java.util.AbstractQueue

    addAll, element, remove

    Methods declared in class java.util.AbstractCollection

    containsAll, isEmpty, toString

    Methods declared in class java.lang.Object

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

    Methods declared in interface java.util.Collection

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

    Methods declared in interface java.util.Queue

    element, remove

  • Constructor Details

    • 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 - 如果指定的集合或其任何元素为null

  • Method Details

    • 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 - 如果指定的元素为null

    • offer

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

    • put

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

    • 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 - 如果指定的元素为null

    • 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。

      请注意，您不能总是通过检查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。更正式地说，如果此队列包含至少一个元素e，使得o.equals(e)，则返回true。
      指定者:
      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 - 如果指定数组为null

    • 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 - 如果指定集合为null
      IllegalArgumentException - 如果指定集合为此队列，或者此队列的某个元素的某个属性阻止将其添加到指定集合中

    • drainTo

      public int drainTo(Collection<? super E> c, int maxElements)
      从接口中复制的描述： BlockingQueue
      从此队列中最多移除给定数量的可用元素，并将它们添加到给定的集合中。在尝试将元素添加到集合c时遇到失败可能导致相关异常抛出时，元素可能既不在集合中，也不在队列中，或者同时在两个集合中。尝试将队列排空到自身会导致IllegalArgumentException。此外，如果在操作进行中修改了指定集合，则此操作的行为是未定义的。
      指定者：
      drainTo 在接口 BlockingQueue<E>
      参数：
      c - 要传输元素的集合
      maxElements - 要传输的最大元素数量
      返回：
      传输的元素数量
      抛出：
      UnsupportedOperationException - 如果指定集合不支持添加元素
      ClassCastException - 如果此队列的元素的类阻止将其添加到指定集合中
      NullPointerException - 如果指定集合为null
      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 以允许有限的并行性。
      返回:
      此队列中元素的 Spliterator
      自 JDK 版本:
      1.8

    • forEach

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

      如果操作执行会修改元素的底层来源并产生副作用，则此方法的行为是未指定的，除非覆盖类已指定了并发修改策略。

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

    • removeIf

      public boolean removeIf(Predicate<? super E> filter)
      从接口复制的描述: Collection
      删除满足给定断言的此集合的所有元素。在迭代期间或由断言引发的错误或运行时异常将传递给调用者。
      指定者:
      removeIf 在接口 Collection<E>中
      参数:
      filter - 一个断言，对于要删除的元素返回 true
      返回:
      如果有任何元素被删除，则返回 true
      抛出:
      NullPointerException - 如果指定的过滤器为 null

    • removeAll

      public boolean removeAll(Collection<?> c)
      从类复制的描述: AbstractCollection
      删除此集合中也包含在指定集合中的所有元素（可选操作）。调用返回后，此集合将不包含与指定集合中的元素相同的任何元素。
      指定者:
      removeAll 在接口 Collection<E>中
      覆盖:
      removeAll 在类 AbstractCollection<E>中
      参数:
      c - 包含要从此集合中删除的元素的集合
      返回:
      如果此调用导致此集合发生更改，则返回 true
      抛出:
      NullPointerException - 如果此集合包含一个或多个 null 元素，且指定的集合不支持 null 元素（可选），或者指定的集合为 null
      参见:

    • retainAll

      public boolean retainAll(Collection<?> c)
      从类复制的描述: AbstractCollection
      仅保留此集合中包含在指定集合中的元素（可选操作）。换句话说，从此集合中删除不包含在指定集合中的所有元素。
      指定者:
      retainAll 在接口 Collection<E>中
      覆盖:
      retainAll 在类 AbstractCollection<E>中
      参数:
      c - 包含要在此集合中保留的元素的集合
      返回:
      如果此调用导致此集合发生更改，则返回 true
      抛出:
      NullPointerException - 如果此集合包含一个或多个 null 元素，且指定的集合不允许 null 元素（可选），或者指定的集合为 null
      参见: