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

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

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.