Интерфейс 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 реализации потокобезопасны. Все методы очереди достигают своих эффектов атомарно с использованием внутренних блокировок или других форм управления конкурентностью. Однако массовые операции коллекции 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 Collections Framework.

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

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

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

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

forEach

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

element, peek, poll, remove

END_OF_DOCUMENT_MARKER

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

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://download.java.net/java/early_access/jdk24/docs/api/java.base/java/util/concurrent/BlockingQueue.html