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

Interface BlockingQueue<E>

  • 参数类型
    E - 这个队列中保存的元素的类型
    All Superinterfaces:
    Collection<E> ， Iterable<E> ， Queue<E>
    All Known Subinterfaces:
    BlockingDeque<E> ， TransferQueue<E>
    所有已知实现类：
    ArrayBlockingQueue ， DelayQueue ， LinkedBlockingDeque ， LinkedBlockingQueue ， LinkedTransferQueue ， PriorityBlockingQueue ， SynchronousQueue 

    public interface BlockingQueue<E>
extends Queue<E>
    A Queue另外支持在检索元素时等待队列变为非空的操作，并在存储元素时等待队列中的空间变得可用。

    BlockingQueue方法有四种形式，具有不同的操作方式，不能立即满足，但可能在将来的某个时间点满足：一个异常，第二个返回一个特殊值（ null或false ，具体取决于操作），第三个程序将无限期地阻止当前线程，直到操作成功为止，而第四个程序块在放弃之前只有给定的最大时限。 这些方法总结在下表中：

    Summary of BlockingQueue methods Throws exception Special value Blocks Times out Insert add(e) offer(e) put(e) offer(e, time, unit) Remove remove() poll() take() poll(time, unit) Examine element() peek() not applicable not applicable

    A BlockingQueue不接受null元素。 实现抛出NullPointerException上尝试add ， put或者offer一个null 。 A null用作哨兵值以指示poll操作的故障。

    A BlockingQueue可能是容量有限的。 在任何给定的时间它可能有一个remainingCapacity超过其中没有附加元素可以put没有阻止。 A BlockingQueue没有任何固有的容量限制，总是报告剩余容量为Integer.MAX_VALUE 。

    BlockingQueue实现被设计为主要用于生产者 - 消费者队列，但另外支持Collection接口。 因此，例如，可以使用remove(x)从队列中删除任意元素。 然而，这样的操作通常不能非常有效地执行，并且仅用于偶尔使用，例如当排队的消息被取消时。

    BlockingQueue实现是线程安全的。 所有排队方法使用内部锁或其他形式的并发控制在原子上实现其效果。 然而， 大量的Collection操作addAll ， containsAll ， retainAll和removeAll 不一定原子除非在实现中另有规定执行。 因此有可能，例如，为addAll(c)到只增加一些元件在后失败（抛出异常） c 。

    A BlockingQueue本质上不支持任何类型的“关闭”或“关闭”操作，表示不再添加项目。 这些功能的需求和使用往往依赖于实现。 例如，一个常见的策略是生产者插入特殊的尾流或毒物 ，这些消费者在被消费者摄取时被相应地解释。

    使用示例，基于典型的生产者 - 消费者场景。 请注意， BlockingQueue可以安全地与多个生产者和多个消费者一起使用。 

       class Producer implements Runnable { private final BlockingQueue queue; Producer(BlockingQueue q) { queue = q; } public void run() { try { while (true) { queue.put(produce()); } } catch (InterruptedException ex) { ... handle ...} } Object produce() { ... } } class Consumer implements Runnable { private final BlockingQueue queue; Consumer(BlockingQueue q) { queue = q; } public void run() { try { while (true) { consume(queue.take()); } } catch (InterruptedException ex) { ... handle ...} } void consume(Object x) { ... } } class Setup { void main() { BlockingQueue q = new SomeQueueImplementation(); Producer p = new Producer(q); Consumer c1 = new Consumer(q); Consumer c2 = new Consumer(q); new Thread(p).start(); new Thread(c1).start(); new Thread(c2).start(); } }

    内存一致性效果：与其他并发集合一样，在将对象放入BlockingQueue happen-before之后的线程中的操作，随后从另一个线程中的BlockingQueue访问或删除该元素。

    此接口是Java Collections Framework的成员。

    从以下版本开始：
    1.5

    • 方法摘要

      所有方法  接口方法  抽象方法 
      Modifier and Type 方法 描述
      boolean add​(E e)
      将指定的元素插入到此队列中，如果可以立即执行此操作，而不会违反容量限制，成功后返回 true ，如果没有空间可用，则抛出 IllegalStateException 。
      boolean contains​(Object o)
      如果此队列包含指定的元素，则返回 true 。
      int drainTo​(Collection<? super E> c)
      从该队列中删除所有可用的元素，并将它们添加到给定的集合中。
      int drainTo​(Collection<? super E> c, int maxElements)
      最多从该队列中删除给定数量的可用元素，并将它们添加到给定的集合中。
      boolean offer​(E e)
      将指定的元素插入此队列中，如果它是立即可行且不会违反容量限制，返回 true在成功和 false如果当前没有空间可用。
      boolean offer​(E e, long timeout, TimeUnit unit)
      将指定的元素插入到此队列中，等待指定的等待时间（如有必要）才能使空间变得可用。
      E poll​(long timeout, TimeUnit unit)
      检索并删除此队列的头，等待指定的等待时间（如有必要）使元素变为可用。
      void put​(E e)
      将指定的元素插入到此队列中，等待空格可用。
      int remainingCapacity​()
      返回此队列可理想地（在没有内存或资源约束的情况下）接受而不阻止的附加元素数，如果没有内在限制则 Integer.MAX_VALUE 。
      boolean remove​(Object o)
      从该队列中删除指定元素的单个实例（如果存在）。
      E take​()
      检索并删除此队列的头，如有必要，等待元素可用。

    • 方法详细信息

      • add

        boolean add​(E e)
        将指定的元素插入到此队列中，如果可以立即执行此操作，而不会违反容量限制，成功后返回true ，如果当前没有可用空间，则抛出IllegalStateException 。 当使用容量限制队列时，通常最好使用offer 。
        Specified by:
        add在接口 Collection<E>
        Specified by:
        add在接口 Queue<E>
        参数
        e - 要添加的元素
        结果
        true （由 Collection.add(E)指定）
        异常
        IllegalStateException - 如果由于容量限制，此时无法添加该元素
        ClassCastException - 如果指定元素的类阻止将其添加到此队列中
        NullPointerException - 如果指定的元素为空
        IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此队列

      • offer

        boolean offer​(E e)
        将指定的元素插入此队列中，如果它是立即可行且不会违反容量限制，返回true在成功和false如果当前没有空间可用。 当使用容量限制队列时，此方法通常优于add(E) ，这可能无法仅通过抛出异常来插入元素。
        Specified by:
        offer在接口 Queue<E>
        参数
        e - 要添加的元素
        结果
        true如果元素被添加到此队列，否则为 false
        异常
        ClassCastException - 如果指定元素的类阻止将其添加到此队列中
        NullPointerException - 如果指定的元素为空
        IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此队列中

      • offer

        boolean offer​(E e,
              long timeout,
              TimeUnit unit)
       throws InterruptedException
        将指定的元素插入到此队列中，等待指定的等待时间（如有必要）才能使空间变得可用。
        参数
        e - 要添加的元素
        timeout - 放弃之前等待多久，以 unit为单位
        unit - a TimeUnit确定如何解释 timeout参数
        结果
        true如果成功，或 false如果在空间可用之前经过了指定的等待时间
        异常
        InterruptedException - 如果在等待时中断
        ClassCastException - 如果指定元素的类阻止将其添加到此队列中
        NullPointerException - 如果指定的元素为空
        IllegalArgumentException - 如果指定元素的某些属性阻止将其添加到此队列中

      • poll

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

      • remainingCapacity

        int remainingCapacity​()
        返回此队列可理想地（在没有内存或资源约束的情况下）接受而不阻止的附加元素数，如果没有内在限制则Integer.MAX_VALUE 。

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

        结果
        剩余容量

      • remove

        boolean remove​(Object o)
        从该队列中删除指定元素的单个实例（如果存在）。 更正式地，删除元素e ，使得o.equals(e) ，如果这个队列包含一个或多个这样的元素。 如果此队列包含指定的元素（或等效地，如果此队列作为调用的结果而更改），则返回true 。
        Specified by:
        remove在接口 Collection<E>
        参数
        o - 要从此队列中删除的元素（如果存在）
        结果
        true如果此队列由于调用而更改
        异常
        ClassCastException - 如果指定元素的类与此队列不兼容（ optional ）
        NullPointerException - 如果指定的元素为空（ optional ）

      • contains

        boolean contains​(Object o)
        如果此队列包含指定的元素，则返回true 。 更正式地，返回true当且仅当该队列至少包含一个元素e ，使得o.equals(e) 。
        Specified by:
        contains在接口 Collection<E>
        参数
        o - 要检查此队列中的遏制的对象
        结果
        true如果此队列包含指定的元素
        异常
        ClassCastException - 如果指定元素的类与此队列不兼容（ optional ）
        NullPointerException - 如果指定的元素为空（ optional ）

      • drainTo

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

      • drainTo

        int drainTo​(Collection<? super E> c,
            int maxElements)
        最多从该队列中删除给定数量的可用元素，并将它们添加到给定的集合中。 尝试向集合c添加元素时遇到的失败可能导致元素在抛出关联的异常时既不在两个集合中，也可能不是两个集合。 尝试将队列排入自身会导致IllegalArgumentException 。 此外，如果在操作进行中修改了指定的集合，则此操作的行为是未定义的。
        参数
        c - 传输元素的集合
        maxElements - 要传输的元素的最大数量
        结果
        转移的元素数量
        异常
        UnsupportedOperationException - 如果指定集合不支持添加元素
        ClassCastException - 如果此队列的元素的类阻止将其添加到指定的集合
        NullPointerException - 如果指定的集合为空
        IllegalArgumentException - if the specified collection is this queue, or some property of an element of this queue prevents it from being added to the specified collection