Module  java.base
软件包  java.util.concurrent

Class ArrayBlockingQueue<E>

  • 参数类型
    E - 保存在此队列中的元素的类型
    All Implemented Interfaces:
    Serializable ， Iterable<E> ， Collection<E> ， BlockingQueue<E> ， Queue<E> 

    public class ArrayBlockingQueue<E>
extends AbstractQueue<E>
implements BlockingQueue<E>, Serializable
    一个有限的blocking queue由数组支持。 这个队列排列元素FIFO（先进先出）。 队列的头部是队列中最长的元素。 队列的尾部是队列中最短时间的元素。 新元素插入队列的尾部，队列检索操作获取队列头部的元素。

    这是一个经典的“有界缓冲区”，其中固定大小的数组保存由生产者插入的元素并由消费者提取。 创建后，容量无法更改。 尝试将一个元素的put尝试到一个完整的队列中将导致操作阻塞; 尝试从一个空队列中的一个元素将同样地阻塞take 。

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

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

    这个类是Java Collections Framework的成员。

    从以下版本开始：
    1.5
    另请参见：
    Serialized Form

    • 构造方法摘要

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

    • 方法摘要

      所有方法  接口方法  具体的方法 
      Modifier and Type 方法 描述
      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)
      以适当的顺序返回包含此队列中所有元素的数组; 返回的数组的运行时类型是指定数组的运行时类型。
      String toString​()
      返回此集合的字符串表示形式。

    • 构造方法详细信息

      • ArrayBlockingQueue

        public ArrayBlockingQueue​(int capacity)
        创建具有给定（固定）容量和默认访问策略的 ArrayBlockingQueue 。
        参数
        capacity - 该队列的容量
        异常
        IllegalArgumentException - 如果是 capacity < 1

      • ArrayBlockingQueue

        public ArrayBlockingQueue​(int capacity,
                          boolean fair)
        创建具有给定（固定）容量和指定访问策略的 ArrayBlockingQueue 。
        参数
        capacity - 这个队列的容量
        fair - 如果true然后对插入或删除阻塞的线程进行队列访问， true FIFO顺序处理; 如果false访问顺序未指定。
        异常
        IllegalArgumentException - 如果是 capacity < 1

      • ArrayBlockingQueue

        public ArrayBlockingQueue​(int capacity,
                          boolean fair,
                          Collection<? extends E> c)
        创建具有给定（固定）容量的 ArrayBlockingQueue ，指定的访问策略，最初包含给定集合的元素，以集合的迭代器的遍历顺序添加。
        参数
        capacity - 这个队列的容量
        fair - 如果true然后对插入或删除阻塞的线程进行队列访问， true FIFO顺序处理; 如果false访问顺序是未指定的。
        c - 最初包含的元素的集合
        异常
        IllegalArgumentException - 如果 capacity小于 c.size() ，或小于1。
        NullPointerException - 如果指定的集合或其任何元素为空

    • 方法详细信息

      • offer

        public boolean offer​(E e)
        插入指定的元素在这个队列的尾部，如果有可能立即这样做不超过该队列的容量，返回true在成功和false如果此队列已满。 该方法通常优于方法add(E) ，其可以仅通过抛出异常来插入元素。
        Specified by:
        offer接口 BlockingQueue<E>
        Specified by:
        offer在接口 Queue<E>
        参数
        e - 要添加的元素
        结果
        true如果元素被添加到此队列，否则为 false
        异常
        NullPointerException - 如果指定的元素为空

      • offer

        public boolean offer​(E e,
                     long timeout,
                     TimeUnit unit)
              throws InterruptedException
        在该队列的尾部插入指定的元素，等待指定的等待时间，以使空间在队列已满时变为可用。
        Specified by:
        offer在接口 BlockingQueue<E>
        参数
        e - 要添加的元素
        timeout - 放弃之前等待多久，以 unit为单位
        unit - a TimeUnit确定如何解释 timeout参数
        结果
        true如果成功，或 false如果在空间可用之前经过指定的等待时间
        异常
        InterruptedException - 如果在等待时中断
        NullPointerException - 如果指定的元素为空

      • poll

        public E poll​()
        描述从接口Queue复制
        检索并删除此队列的头，如果此队列为空，则返回 null 。
        Specified by:
        poll在接口 Queue<E>
        结果
        这个队列的头，或 null如果这个队列是空的

      • poll

        public E poll​(long timeout,
              TimeUnit unit)
       throws InterruptedException
        描述从接口BlockingQueue复制
        检索并删除此队列的头，等待指定的等待时间（如有必要）使元素变为可用。
        Specified by:
        poll在接口 BlockingQueue<E>
        参数
        timeout - 放弃之前等待多长时间，以 unit为单位
        unit - a TimeUnit确定如何解释 timeout参数
        结果
        该队列的头部，或者如果在元素可用之前经过指定的等待时间， null
        异常
        InterruptedException - 如果中断等待

      • peek

        public E peek​()
        说明从接口Queue复制
        检索但不删除此队列的头，如果此队列为空，则返回 null 。
        Specified by:
        peek在接口 Queue<E>
        结果
        这个队列的头，或 null如果这个队列是空的

      • remainingCapacity

        public int remainingCapacity​()
        返回此队列可以理想地（在没有内存或资源限制）的情况下接受而不阻止的附加元素数。 这总是等于该队列的初始容量少于此队列的当前size 。

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

        Specified by:
        remainingCapacity接口 BlockingQueue<E>
        结果
        剩余容量

      • remove

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

        基于循环阵列的队列中的内部元素的删除是本质上缓慢和破坏性的操作，所以只应在特殊情况下进行，理想情况下只有当队列被其他线程知道时才能访问。

        Specified by:
        remove在接口 BlockingQueue<E>
        Specified by:
        remove在接口 Collection<E>
        重写：
        remove在 AbstractCollection<E>
        参数
        o - 要从此队列中删除的元素（如果存在）
        结果
        true如果此队列由于调用而更改

      • contains

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

      • toArray

        public Object[] toArray​()
        以适当的顺序返回一个包含此队列中所有元素的数组。

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

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

        Specified by:
        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()相同。
        Specified by:
        toArray接口 Collection<E>
        重写：
        toArray在 AbstractCollection<E>
        参数类型
        T - 包含集合的数组的运行时类型
        参数
        a - 要存储队列的元素的阵列，如果它足够大; 否则，为此目的分配相同运行时类型的新数组
        结果
        一个包含此队列中所有元素的数组
        异常
        ArrayStoreException - 如果指定数组的运行时类型不是此队列中每个元素的运行时类型的超类型
        NullPointerException - 如果指定的数组为空

      • toString

        public String toString​()
        描述从类复制： AbstractCollection
        返回此集合的字符串表示形式。 字符串表示由集合的元素的列表按照它们的迭代器返回的顺序包含在方括号（ "[]" ）中。 相邻元素由字符", " （逗号和空格）分隔。 元素将转换为字符串，如String.valueOf(Object) 。
        重写：
        toString在 AbstractCollection<E>
        结果
        此集合的字符串表示形式

      • clear

        public void clear​()
        从这个队列中原子地删除所有的元素。 此呼叫返回后队列将为空。
        Specified by:
        clear在接口 Collection<E>
        重写：
        clear在 AbstractQueue<E>

      • drainTo

        public int drainTo​(Collection<? super E> c)
        说明从接口BlockingQueue复制
        从该队列中删除所有可用的元素，并将它们添加到给定的集合中。 此操作可能比重复轮询此队列更有效。 尝试向集合c添加元素时遇到的失败可能导致在抛出关联的异常时，元素既不在两个集合中，也可能不是两个集合。 尝试将队列排入自身会导致IllegalArgumentException 。 此外，如果在操作进行中修改了指定的集合，则此操作的行为是未定义的。
        Specified by:
        drainTo在接口 BlockingQueue<E>
        参数
        c - 将元素传输到的集合
        结果
        转移的元素数量
        异常
        UnsupportedOperationException - 如果指定集合不支持元素的添加
        ClassCastException - 如果此队列的元素的类阻止将其添加到指定的集合
        NullPointerException - 如果指定的集合为空
        IllegalArgumentException - 如果指定的集合是此队列，或该队列的某个元素的某些属性阻止将其添加到指定的集合

      • drainTo

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

      • forEach

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

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

        Specified by:
        forEach在接口 Iterable<E>
        参数
        action - 要为每个元素执行的操作
        异常
        NullPointerException - 如果指定的操作为空

      • removeIf

        public boolean removeIf​(Predicate<? super E> filter)
        说明从接口Collection复制
        删除满足给定谓词的此集合的所有元素。 在迭代或谓词中抛出的错误或运行时异常被转发给调用者。
        Specified by:
        removeIf在接口 Collection<E>
        参数
        filter - 为要删除的元素返回 true的谓词
        结果
        true如果有任何元素被删除
        异常
        NullPointerException - 如果指定的过滤器为空