Интерфейс 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 элементы. При попытках add, put или offer null реализации выбрасывают NullPointerException. null используется в качестве сигнального значения, указывающего на неудачу операций poll.

BlockingQueue может иметь ограниченную ёмкость. В каждый момент времени у неё может быть remainingCapacity, превышение которого невозможно без блокировки при добавлении новых элементов put. BlockingQueue без встроенных ограничений ёмкости всегда сообщает, что оставшаяся ёмкость равна Integer.MAX_VALUE.

Реализации BlockingQueue предназначены главным образом для использования в очередях «производитель — потребитель», но также поддерживают интерфейс Collection. Например, с помощью remove(x) можно удалить из очереди произвольный элемент. Однако такие операции, как правило, выполняются не очень эффективно и предназначены только для эпизодического использования, например, когда поставленное в очередь сообщение отменяется.

Реализации BlockingQueue являются потокобезопасными. Все методы работы с очередью выполняют свои действия атомарно с помощью внутренних блокировок или других средств управления параллелизмом. Однако массовые операции Collection 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()`	Извлекает и удаляет начало этой очереди, при необходимости ожидая появления элемента.

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

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

Модификатор и тип	Метод	Описание
`boolean`	`addAll(Collection<? extends E> c)`	Добавляет все элементы указанной коллекции в эту коллекцию (необязательная операция).
`void`	`clear()`	Удаляет все элементы из этой коллекции (необязательная операция).
`boolean`	`containsAll(Collection<?> c)`	Возвращает `true`, если эта коллекция содержит все элементы указанной коллекции.
`boolean`	`equals(Object o)`	Сравнивает указанный объект с этой коллекцией на равенство.
`int`	`hashCode()`	Возвращает значение хеш-кода этой коллекции.
`boolean`	`isEmpty()`	Возвращает `true`, если эта коллекция не содержит элементов.
`Iterator<E>`	`iterator()`	Возвращает итератор для элементов этой коллекции.
`default Stream<E>`	`parallelStream()`	Возвращает, возможно, параллельный `Stream`, источником которого является эта коллекция.
`boolean`	`removeAll(Collection<?> c)`	Удаляет из этой коллекции все элементы, которые также содержатся в указанной коллекции (необязательная операция).
`default boolean`	`removeIf(Predicate<? super E> filter)`	Удаляет из этой коллекции все элементы, удовлетворяющие заданному предикату (необязательная операция).
`boolean`	`retainAll(Collection<?> c)`	Оставляет в этой коллекции только элементы, содержащиеся в указанной коллекции (необязательная операция).
`int`	`size()`	Возвращает количество элементов в этой коллекции.
`default Spliterator<E>`	`spliterator()`	Создаёт `Spliterator` для элементов этой коллекции.
`default Stream<E>`	`stream()`	Возвращает последовательный `Stream`, источником которого является эта коллекция.
`Object[]`	`toArray()`	Возвращает массив, содержащий все элементы этой коллекции.
`default <T> T[]`	`toArray(IntFunction<T[]> generator)`	Возвращает массив, содержащий все элементы этой коллекции; для выделения возвращаемого массива используется предоставленная функция `generator`.
`<T> T[]`	`toArray(T[] a)`	Возвращает массив, содержащий все элементы этой коллекции; тип возвращаемого массива во время выполнения соответствует типу указанного массива.

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

forEach

Модификатор и тип	Метод	Описание
`default void`	`forEach(Consumer<? super E> action)`	Выполняет заданное действие для каждого элемента `Iterable`, пока не будут обработаны все элементы или действие не выбросит исключение.

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

element, peek, poll, remove

Модификатор и тип	Метод	Описание
`E`	`element()`	Извлекает, но не удаляет начало этой очереди.
`E`	`peek()`	Извлекает, но не удаляет начало этой очереди; если очередь пуста, возвращает `null`.
`E`	`poll()`	Извлекает и удаляет начало этой очереди; если очередь пуста, возвращает `null`.
`E`	`remove()`	Извлекает и удаляет начало этой очереди.

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

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.