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

Методы

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()

Возвращает:

оставшаяся емкость

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 - если указанная коллекция является этой очередью, или некоторые свойства элемента этой очереди предотвращают его добавление в указанную коллекцию