Интерфейс BlockingQueue<E>

Параметры типа:: E - тип элементов, хранящихся в этой очереди

Все суперинтерфейсы:: Collection<E>, Iterable<E>, Queue<E>

Все известные подинтерфейсы:: BlockingDeque<E>, TransferQueue<E>

Все известные классы-реализации:: ArrayBlockingQueue, DelayQueue, LinkedBlockingDeque, LinkedBlockingQueue, LinkedTransferQueue, PriorityBlockingQueue, SynchronousQueue

public interface BlockingQueue<E> extends Queue<E>

Queue, который дополнительно поддерживает операции, ожидающие, пока очередь станет непустой, при извлечении элемента, и ожидающие освобождения места в очереди при добавлении элемента.

BlockingQueue методы имеют четыре формы, различающиеся способом обработки операций, которые нельзя выполнить немедленно, но которые могут быть выполнены позднее: первая форма генерирует исключение, вторая возвращает специальное значение (null или false в зависимости от операции), третья блокирует текущий поток на неопределённый срок, пока операция не сможет завершиться успешно, а четвёртая блокирует поток только на заданный максимальный промежуток времени, после чего прекращает ожидание. Эти методы сведены в следующую таблицу:

Сводка методов BlockingQueue
	Генерирует исключение	Специальное значение	Блокирует	Ограничено временем ожидания
Добавление	`add(e)`	`offer(e)`	`put(e)`	`offer(e, time, unit)`
Удаление	`remove()`	`poll()`	`take()`	`poll(time, unit)`
Просмотр	`element()`	`peek()`	не применимо	не применимо

BlockingQueue не принимает элементы null. Реализации генерируют NullPointerException при попытках add, put или offer null. null используется в качестве специального значения, указывающего на неудачу операций poll.

BlockingQueue может иметь ограниченную ёмкость. В любой момент времени может существовать remainingCapacity, превышение которого невозможно без блокировки при добавлении дополнительных элементов put. BlockingQueue без встроенных ограничений ёмкости всегда сообщает, что оставшаяся ёмкость равна Integer.MAX_VALUE.

Реализации BlockingQueue предназначены главным образом для использования в очередях производителей и потребителей, но также поддерживают интерфейс Collection. Например, из очереди можно удалить произвольный элемент с помощью remove(x). Однако такие операции, как правило, выполняются не очень эффективно и предназначены только для эпизодического использования, например при отмене сообщения в очереди.

Реализации BlockingQueue являются потокобезопасными. Все методы работы с очередью выполняют свои действия атомарно, используя внутренние блокировки или другие средства управления параллелизмом. Однако пакетные операции Collection addAll, containsAll, retainAll и removeAll не обязательно выполняются атомарно, если в реализации не указано иное. Например, addAll(c) может завершиться неудачно (сгенерировав исключение) после добавления лишь некоторых элементов из c.

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, происходят до действий, следующих за доступом к этому элементу или его удалением из BlockingQueue в другом потоке.

Этот интерфейс является частью фреймворка коллекций Java.

Начиная с версии:: 1.5

Краткое описание методов

Модификатор и тип	Метод	Описание
`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()`	Извлекает и удаляет голову этой очереди, при необходимости ожидая появления элемента.

Методы, объявленные в интерфейсе Collection

addAll, clear, containsAll, equals, hashCode, isEmpty, iterator, parallelStream, removeAll, removeIf, retainAll, size, spliterator, stream, toArray, toArray, toArray

Методы, объявленные в интерфейсе Iterable

forEach

Методы, объявленные в интерфейсе Queue

element, peek, poll, remove

Подробное описание методов

add

boolean add(E e)

Добавляет указанный элемент в эту очередь, если это можно сделать немедленно, не нарушая ограничений ёмкости; при успехе возвращает true, а если свободного места в данный момент нет, генерирует IllegalStateException. При использовании очереди с ограниченной ёмкостью обычно предпочтительно применять offer.

Определён в:: add в интерфейсе Collection<E>
Определён в:: add в интерфейсе Queue<E>
Параметры:: e - добавляемый элемент
Возвращает:: true (как указано в Collection.add(E))
Исключения:: IllegalStateException - если элемент невозможно добавить в данный момент из-за ограничений ёмкости; ClassCastException - если класс указанного элемента не позволяет добавить его в эту очередь; NullPointerException - если указанный элемент равен null; IllegalArgumentException - если какое-либо свойство указанного элемента не позволяет добавить его в эту очередь

offer

boolean offer(E e)

Добавляет указанный элемент в эту очередь, если это можно сделать немедленно, не нарушая ограничений ёмкости; при успехе возвращает true, а если свободного места в данный момент нет — false. При использовании очереди с ограниченной ёмкостью этот метод обычно предпочтительнее add(E), который может не добавить элемент только путём генерации исключения.

Определён в:: offer в интерфейсе Queue<E>
Параметры:: e - добавляемый элемент
Возвращает:: true, если элемент добавлен в эту очередь, иначе false
Исключения:: ClassCastException - если класс указанного элемента не позволяет добавить его в эту очередь; NullPointerException - если указанный элемент равен null; IllegalArgumentException - если какое-либо свойство указанного элемента не позволяет добавить его в эту очередь

put

void put(E e) throws InterruptedException

Добавляет указанный элемент в эту очередь, при необходимости ожидая освобождения места.

Параметры:: e - добавляемый элемент
Исключения:: InterruptedException - если ожидание было прервано; ClassCastException - если класс указанного элемента не позволяет добавить его в эту очередь; NullPointerException - если указанный элемент равен null; IllegalArgumentException - если какое-либо свойство указанного элемента не позволяет добавить его в эту очередь

offer

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

Добавляет указанный элемент в эту очередь, при необходимости ожидая освобождения места в течение заданного времени.

Параметры:: e - добавляемый элемент; timeout - время ожидания до прекращения ожидания, в единицах unit; unit - TimeUnit, определяющий способ интерпретации параметра timeout
Возвращает:: true при успехе или false, если заданное время ожидания истекло до освобождения места
Исключения:: InterruptedException - если ожидание было прервано; ClassCastException - если класс указанного элемента не позволяет добавить его в эту очередь; NullPointerException - если указанный элемент равен null; IllegalArgumentException - если какое-либо свойство указанного элемента не позволяет добавить его в эту очередь

take

E take() throws InterruptedException

Извлекает и удаляет голову этой очереди, при необходимости ожидая появления элемента.

Возвращает:: голову этой очереди
Исключения:: InterruptedException - если ожидание было прервано

poll

E poll(long timeout, TimeUnit unit) throws InterruptedException

Извлекает и удаляет голову этой очереди, при необходимости ожидая появления элемента в течение заданного времени.

Параметры:: timeout - время ожидания до прекращения ожидания, в единицах unit; unit - TimeUnit, определяющий способ интерпретации параметра timeout
Возвращает:: голову этой очереди или null, если заданное время ожидания истекло до появления элемента
Исключения:: InterruptedException - если ожидание было прервано

remainingCapacity

int remainingCapacity()

Возвращает количество дополнительных элементов, которые эта очередь в идеальных условиях (при отсутствии ограничений памяти или ресурсов) может принять без блокировки, или Integer.MAX_VALUE, если встроенного ограничения нет.

Обратите внимание, что по значению remainingCapacity не всегда можно определить, завершится ли успешно попытка добавить элемент, поскольку другой поток может в этот момент добавлять или удалять элемент.

Возвращает:: оставшуюся ёмкость

remove

boolean remove(Object o)

Удаляет из этой очереди один экземпляр указанного элемента, если он присутствует. Точнее, удаляет элемент e такой, что o.equals(e), если эта очередь содержит один или несколько таких элементов. Возвращает true, если эта очередь содержала указанный элемент (или, что эквивалентно, если в результате вызова очередь изменилась).

Определён в:: remove в интерфейсе Collection<E>
Параметры:: o - элемент, который нужно удалить из этой очереди, если он присутствует
Возвращает:: true, если очередь изменилась в результате вызова
Исключения:: ClassCastException - если класс указанного элемента несовместим с этой очередью (необязательно); NullPointerException - если указанный элемент равен null (необязательно)

contains

boolean contains(Object o)

Возвращает true, если эта очередь содержит указанный элемент. Точнее, возвращает true тогда и только тогда, когда эта очередь содержит хотя бы один элемент e такой, что o.equals(e).

Определён в:: contains в интерфейсе Collection<E>
Параметры:: o - объект, наличие которого в этой очереди нужно проверить
Возвращает:: true, если эта очередь содержит указанный элемент
Исключения:: ClassCastException - если класс указанного элемента несовместим с этой очередью (необязательно); NullPointerException - если указанный элемент равен null (необязательно)

drainTo

int drainTo(Collection<? super E> c)

Удаляет из этой очереди все доступные элементы и добавляет их в указанную коллекцию. Эта операция может быть эффективнее, чем многократный вызов poll для этой очереди. Если при добавлении элементов в коллекцию c возникнет ошибка, то на момент генерации соответствующего исключения элементы могут отсутствовать в обеих коллекциях, находиться в одной из них или присутствовать в обеих. Попытка перенести элементы очереди в неё же приводит к IllegalArgumentException. Кроме того, поведение этой операции не определено, если указанная коллекция изменяется во время её выполнения.

Параметры:: c - коллекция, в которую нужно переместить элементы
Возвращает:: количество перемещённых элементов
Исключения:: UnsupportedOperationException - если указанная коллекция не поддерживает добавление элементов; ClassCastException - если класс элемента этой очереди не позволяет добавить его в указанную коллекцию; NullPointerException - если указанная коллекция равна null; IllegalArgumentException - если указанная коллекция является этой очередью или какое-либо свойство элемента этой очереди не позволяет добавить его в указанную коллекцию

drainTo

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

Удаляет из этой очереди не более указанного количества доступных элементов и добавляет их в указанную коллекцию. Если при добавлении элементов в коллекцию c возникнет ошибка, то на момент генерации соответствующего исключения элементы могут отсутствовать в обеих коллекциях, находиться в одной из них или присутствовать в обеих. Попытка перенести элементы очереди в неё же приводит к IllegalArgumentException. Кроме того, поведение этой операции не определено, если указанная коллекция изменяется во время её выполнения.

Параметры:: c - коллекция, в которую нужно переместить элементы; maxElements - максимальное количество элементов для перемещения
Возвращает:: количество перемещённых элементов
Исключения:: UnsupportedOperationException - если указанная коллекция не поддерживает добавление элементов; ClassCastException - если класс элемента этой очереди не позволяет добавить его в указанную коллекцию; NullPointerException - если указанная коллекция равна null; IllegalArgumentException - если указанная коллекция является этой очередью или какое-либо свойство элемента этой очереди не позволяет добавить его в указанную коллекцию

© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/concurrent/BlockingQueue.html