Интерфейс 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 Collections Framework.