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

public interface BlockingQueue<E>
extends Queue<E>

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

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

	Выбрасывает исключение	Специальное значение	Блокирует	Истекает время
Вставка	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.