Класс ArrayBlockingQueue<E>

Type Parameters:
E - тип элементов, хранящихся в этой очереди
Все реализованные интерфейсы:
Serializable, Iterable<E>, Collection<E>, BlockingQueue<E>, Queue<E> 
public class ArrayBlockingQueue<E>
extends AbstractQueue<E>
implements BlockingQueue<E>, Serializable

Ограниченная блокирующая очередь, реализованная на основе массива. Эта очередь упорядочивает элементы по принципу FIFO (первым вошел — первым вышел). Голова очереди — это элемент, который находится в очереди дольше всего. Хвост очереди — это элемент, который находится в очереди меньше всего времени. Новые элементы добавляются в хвост очереди, а операции извлечения элементов из очереди получают элементы из её головы.

Это классический «ограниченный буфер», в котором массив фиксированного размера хранит элементы, вставляемые производителями и извлекаемые потребителями. После создания емкость изменить нельзя. Попытки put элемента в полную очередь приведут к блокированию операции; попытки take элемента из пустой очереди аналогичным образом заблокируют выполнение.

Этот класс поддерживает необязательную политику честности для упорядочивания потоков производителей и потребителей, ожидающих доступа. По умолчанию это упорядочивание не гарантируется. Однако очередь, созданная с политикой честности, установленной в значение true, предоставляет потокам доступ в порядке FIFO. Честность обычно снижает пропускную способность, но уменьшает изменчивость и предотвращает голодание.

Этот класс и его итератор реализуют все необязательные методы интерфейсов Collection и Iterator.

Этот класс является частью Java Collections Framework.

С момента:
1.5
См. также:
Сериализованная форма

Конструкторы

Конструктор Описание
ArrayBlockingQueue​(int capacity)

Создаёт ArrayBlockingQueue с заданной (фиксированной) ёмкостью и политикой доступа по умолчанию.
ArrayBlockingQueue​(int capacity, boolean fair)

Создаёт ArrayBlockingQueue с заданной (фиксированной) ёмкостью и заданной политикой доступа.
ArrayBlockingQueue​(int capacity, boolean fair, Collection<? extends E> c)

Создаёт ArrayBlockingQueue с заданной (фиксированной) ёмкостью, заданной политикой доступа и изначально содержащий элементы заданного набора, добавленные в порядке обхода итератора набора.

Методы

Модификатор и тип Метод Описание
boolean add​(E e)

Добавляет указанный элемент в хвост этой очереди, если это возможно сделать немедленно, не превышая ёмкости очереди, возвращая true при успехе и выбрасывая IllegalStateException , если эта очередь полна.
void clear()

Атомарно удаляет все элементы из этой очереди.
boolean contains​(Object o)

Возвращает true , если эта очередь содержит указанный элемент.
int drainTo​(Collection<? super E> c)

Удаляет все доступные элементы из этой очереди и добавляет их в заданный набор.
int drainTo​(Collection<? super E> c, int maxElements)

Удаляет не более указанного количества доступных элементов из этой очереди и добавляет их в заданный набор.
void forEach​(Consumer<? super E> action)

Выполняет заданное действие для каждого элемента Iterable , пока все элементы не будут обработаны или действие не вызовет исключение.
Iterator<E> iterator()

Возвращает итератор по элементам в этой очереди в правильном порядке.
boolean offer​(E e)

Добавляет указанный элемент в хвост этой очереди, если это возможно сделать немедленно, не превышая ёмкости очереди, возвращая true при успехе и false , если эта очередь полна.
boolean offer​(E e, long timeout, TimeUnit unit)

Добавляет указанный элемент в хвост этой очереди, ожидая до указанного времени ожидания, пока не освободится место, если очередь полна.
void put​(E e)

Добавляет указанный элемент в хвост этой очереди, ожидая, пока не освободится место, если очередь полна.
int remainingCapacity()

Возвращает количество дополнительных элементов, которые эта очередь может идеально (в отсутствие ограничений памяти или ресурсов) принять без блокировки.
boolean remove​(Object o)

Удаляет единственный экземпляр указанного элемента из этой очереди, если он присутствует.
boolean removeAll​(Collection<?> c)

Удаляет все элементы этого набора, которые также содержатся в указанном наборе (необязательная операция).
boolean removeIf​(Predicate<? super E> filter)

Удаляет все элементы этого набора, которые удовлетворяют данному предикату.
boolean retainAll​(Collection<?> c)

Сохраняет только элементы в этом наборе, которые содержатся в указанном наборе (необязательная операция).
int size()

Возвращает количество элементов в этой очереди.
Spliterator<E> spliterator()

Возвращает Spliterator по элементам в этой очереди.
Object[] toArray()

Возвращает массив, содержащий все элементы в этой очереди в правильном порядке.
<T> T[] toArray​(T[] a)

Возвращает массив, содержащий все элементы в этой очереди в правильном порядке; тип времени выполнения возвращённого массива — тип указанного массива.

Методы, объявленные в классе java.util.AbstractQueue

addAll, element, remove

Методы, объявленные в классе java.util.AbstractCollection

containsAll, isEmpty, toString

Методы, объявленные в классе java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Методы, объявленные в интерфейсе java.util.concurrent.BlockingQueue

poll, take

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

addAll, containsAll, equals, hashCode, isEmpty, parallelStream, stream, toArray

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

element, peek, poll, remove

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

ArrayBlockingQueue

public ArrayBlockingQueue(int capacity)

Создаёт ArrayBlockingQueue с заданной (фиксированной) ёмкостью и политикой доступа по умолчанию.

Параметры:
capacity - ёмкость этой очереди
Исключения:
IllegalArgumentException - если capacity < 1

ArrayBlockingQueue

public ArrayBlockingQueue(int capacity,
                          boolean fair)

Создаёт ArrayBlockingQueue с заданной (фиксированной) ёмкостью и заданной политикой доступа.

Параметры:
capacity - ёмкость этой очереди
fair - если true , то доступ в очереди для потоков, заблокированных на вставке или удалении, обрабатывается в порядке FIFO; если false , то порядок доступа не определён.
Исключения:
IllegalArgumentException - если capacity < 1

ArrayBlockingQueue

public ArrayBlockingQueue(int capacity,
                          boolean fair,
                          Collection<? extends E> c)

Создаёт ArrayBlockingQueue с заданной (фиксированной) ёмкостью, заданной политикой доступа и изначально содержащий элементы заданного набора, добавленные в порядке обхода итератора набора.

Параметры:
capacity - ёмкость этой очереди
fair - если true , то доступ в очереди для потоков, заблокированных на вставке или удалении, обрабатывается в порядке FIFO; если false , то порядок доступа не определён.
c - набор элементов, которые изначально должны содержаться
Исключения:
IllegalArgumentException - если capacity меньше c.size(), или меньше 1.
NullPointerException - если указанный набор или любой из его элементов равны null

Методы

add

public boolean add(E e)

Вставляет указанный элемент в конец этой очереди, если это возможно сделать немедленно без превышения емкости очереди, возвращает true при успехе и выбрасывает IllegalStateException , если эта очередь заполнена.

Указано в:
add в интерфейсе BlockingQueue<E>
Указано в:
add в интерфейсе Collection<E>
Указано в:
add в интерфейсе Queue<E>
Переопределяет:
add в классе AbstractQueue<E>
Параметры:
e - элемент для добавления
Возвращает:
true (как указано в Collection.add(E))
Исключения:
IllegalStateException - если эта очередь заполнена
NullPointerException - если указанный элемент равен null

offer

public boolean offer(E e)

Вставляет указанный элемент в конец этой очереди, если это возможно сделать немедленно без превышения емкости очереди, возвращает true при успехе и false , если эта очередь заполнена. Этот метод, как правило, предпочтительнее метода add(E), который может не вставить элемент только сбросив исключение.

Указано в:
offer в интерфейсе BlockingQueue<E>
Указано в:
offer в интерфейсе Queue<E>
Параметры:
e - элемент для добавления
Возвращает:
true если элемент был добавлен в эту очередь, иначе false
Исключения:
NullPointerException - если указанный элемент равен null

put

public void put(E e)
         throws InterruptedException

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

Указано в:
put в интерфейсе BlockingQueue<E>
Параметры:
e - элемент для добавления
Исключения:
InterruptedException - если прервано ожидание
NullPointerException - если указанный элемент равен null

offer

public boolean offer(E e,
                     long timeout,
                     TimeUnit unit)
              throws InterruptedException

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

Указано в:
offer в интерфейсе BlockingQueue<E>
Параметры:
e - элемент для добавления
timeout - сколько времени ждать, прежде чем сдаться, в единицах unit
unit - TimeUnit определяющий, как интерпретировать параметр timeout
Возвращает:
true если успешно, или false если указанное время ожидания истекло, прежде чем освободится место
Исключения:
InterruptedException - если прервано ожидание
NullPointerException - если указанный элемент равен null

size

public int size()

Возвращает количество элементов в этой очереди.

Указано в:
size в интерфейсе Collection<E>
Возвращает:
количество элементов в этой очереди

remainingCapacity

public int remainingCapacity()

Возвращает количество дополнительных элементов, которые эта очередь может в идеале (в отсутствие ограничений памяти или ресурсов) принять без блокировки. Это всегда равно начальной емкости этой очереди минус текущая size этой очереди.

Обратите внимание, что вы не всегда можете определить, будет ли попытка вставить элемент успешной, проверяя remainingCapacity, потому что может случиться, что другой поток собирается вставить или удалить элемент.

Указано в:
remainingCapacity в интерфейсе BlockingQueue<E>
Возвращает:
оставшаяся емкость

remove

public boolean remove(Object o)

Удаляет единственный экземпляр указанного элемента из этой очереди, если он присутствует. Более формально, удаляет элемент e такой, что o.equals(e), если эта очередь содержит один или несколько таких элементов. Возвращает true , если эта очередь содержала указанный элемент (или, что эквивалентно, если эта очередь изменилась в результате вызова).

Удаление внутренних элементов в очередях на основе циклических массивов — это внутренне медленная и разрушительная операция, поэтому её следует выполнять только в исключительных случаях, в идеале только когда известно, что к очереди не обращаются другие потоки.

Указано в:
remove в интерфейсе BlockingQueue<E>
Указано в:
remove в интерфейсе Collection<E>
Переопределяет:
remove в классе AbstractCollection<E>
Параметры:
o - элемент, который нужно удалить из этой очереди, если он присутствует
Возвращает:
true если эта очередь изменилась в результате вызова

contains

public boolean contains(Object o)

Возвращает true , если эта очередь содержит указанный элемент. Более формально, возвращает true тогда и только тогда, когда эта очередь содержит по крайней мере один элемент e такой, что o.equals(e).

Указано в:
contains в интерфейсе BlockingQueue<E>
Указано в:
contains в интерфейсе Collection<E>
Переопределяет:
contains в классе AbstractCollection<E>
Параметры:
o - объект, который нужно проверить на наличие в этой очереди
Возвращает:
true если эта очередь содержит указанный элемент

toArray

public Object[] toArray()

Возвращает массив, содержащий все элементы в этой очереди в правильном порядке.

Возвращаемый массив будет «безопасным», так как к нему не сохраняются ссылки этой очередью. (Другими словами, этот метод должен выделять новый массив). Таким образом, вызывающий метод свободен изменять возвращаемый массив.

Этот метод действует как мост между API на основе массивов и на основе коллекций.

Указано в:
toArray в интерфейсе Collection<E>
Переопределяет:
toArray в классе AbstractCollection<E>
Возвращает:
массив, содержащий все элементы в этой очереди

toArray

public <T> T[] toArray(T[] a)

Возвращает массив, содержащий все элементы в этой очереди в правильном порядке; тип времени выполнения возвращаемого массива — тип указанного массива. Если очередь помещается в указанный массив, она возвращается в нём. В противном случае выделяется новый массив с типом времени выполнения указанного массива и размером этой очереди.

Если эта очередь помещается в указанный массив с избытком (то есть массив имеет больше элементов, чем эта очередь), элемент в массиве, непосредственно следующий за концом очереди, устанавливается в null.

Как и метод toArray(), этот метод действует как мост между API на основе массивов и на основе коллекций. Кроме того, этот метод позволяет точно управлять типом времени выполнения массива вывода и может в определенных обстоятельствах использоваться для экономии затрат на выделение памяти.

Предположим, x — это очередь, известная тем, что содержит только строки. Следующий код может использоваться для выгрузки очереди в новый выделенный массив String:

String[] y = x.toArray(new String[0]);
Обратите внимание, что toArray(new Object[0]) выполняет ту же функцию, что и toArray().
Указано в:
toArray в интерфейсе Collection<E>
Переопределяет:
toArray в классе AbstractCollection<E>
Параметры типа:
T - компонентный тип массива, который должен содержать коллекцию
Параметры:
a - массив, в который должны быть помещены элементы очереди, если он достаточно велик; в противном случае для этой цели выделяется новый массив того же типа времени выполнения
Возвращает:
массив, содержащий все элементы в этой очереди
Исключения:
ArrayStoreException - если тип времени выполнения указанного массива не является супертипом типа времени выполнения каждого элемента в этой очереди
NullPointerException - если указанный массив равен null

clear

public void clear()

Атомарно удаляет все элементы из этой очереди. Очередь будет пустой после возврата этого вызова.

Указано в:
clear в интерфейсе Collection<E>
Переопределяет:
clear в классе AbstractQueue<E>

drainTo

public int drainTo(Collection<? super E> c)

Описание скопировано из интерфейса: BlockingQueue

Удаляет все доступные элементы из этой очереди и добавляет их в заданную коллекцию. Эта операция может быть более эффективной, чем многократное опробование этой очереди. Ошибка, возникшая при попытке добавить элементы в коллекцию c, может привести к тому, что элементы будут в ни одной, ни в той, ни в другой, либо в обеих коллекциях, когда будет сгенерировано соответствующее исключение. Попытки слить очередь в себя приводят к IllegalArgumentException. Кроме того, поведение этой операции не определено, если указанная коллекция изменяется во время выполнения операции.

Указано в:
drainTo в интерфейсе BlockingQueue<E>
Параметры:
c - коллекция для переноса элементов
Возвращает:
количество перенесённых элементов
Исключения:
UnsupportedOperationException - если добавление элементов не поддерживается заданной коллекцией
ClassCastException - если класс элемента этой очереди препятствует его добавлению в заданную коллекцию
NullPointerException - если указанная коллекция равна null
IllegalArgumentException - если указанная коллекция — это эта очередь, или некоторые свойства элемента этой очереди препятствуют его добавлению в заданную коллекцию

drainTo

public int drainTo(Collection<? super E> c,
                   int maxElements)

Описание скопировано из интерфейса: BlockingQueue

Удаляет не более указанного количества доступных элементов из этой очереди и добавляет их в заданный набор. Ошибка, возникшая при попытке добавить элементы в набор c, может привести к тому, что элементы будут находиться ни в одном, ни в другом, или в обоих наборах, когда будет сгенерировано соответствующее исключение. Попытки опустошить очередь в саму себя приводят к IllegalArgumentException. Кроме того, поведение этой операции не определено, если указанный набор изменяется во время выполнения операции.

Определено в:
drainTo в интерфейсе BlockingQueue<E>
Параметры:
c - набор для перевода элементов
maxElements - максимальное количество элементов для перевода
Возвращает:
количество переведённых элементов
Исключения:
UnsupportedOperationException - если добавление элементов не поддерживается указанным набором
ClassCastException - если класс элемента этой очереди не позволяет добавить его в указанный набор
NullPointerException - если указанный набор равен null
IllegalArgumentException - если указанный набор является этой очередью или какое-либо свойство элемента этой очереди не позволяет добавить его в указанный набор

iterator

public Iterator<E> iterator()

Возвращает итератор по элементам этой очереди в правильной последовательности. Элементы будут возвращаться в порядке от первого (начала) к последнему (концу).

Возвращаемый итератор является слабо согласованным.

Определено в:
iterator в интерфейсе Collection<E>
Определено в:
iterator в интерфейсе Iterable<E>
Определено в:
iterator в классе AbstractCollection<E>
Возвращает:
итератор по элементам этой очереди в правильной последовательности

spliterator

public Spliterator<E> spliterator()

Возвращает Spliterator по элементам этой очереди.

Возвращаемый разделитель является слабо согласованным.

Разделитель Spliterator сообщает о Spliterator.CONCURRENT, Spliterator.ORDERED и Spliterator.NONNULL.

Определено в:
spliterator в интерфейсе Collection<E>
Определено в:
spliterator в интерфейсе Iterable<E>
Замечание реализации:
Spliterator реализует trySplit для разрешения ограниченного параллелизма.
Возвращает:
Spliterator по элементам этой очереди
С:
1.8

forEach

public void forEach(Consumer<? super E> action)

Описание скопировано из интерфейса: Iterable

Выполняет данное действие для каждого элемента Iterable до тех пор, пока все элементы не будут обработаны или действие не вызовет исключение. Действия выполняются в порядке итерации, если этот порядок указан. Исключения, сгенерированные действием, передаются вызывающей стороне.

Поведение этого метода не определено, если действие производит побочные эффекты, изменяющие базовый источник элементов, если только переопределяемый класс не указал политику одновременного изменения.

Определено в:
forEach в интерфейсе Iterable<E>
Параметры:
action - действие, которое должно выполняться для каждого элемента
Исключения:
NullPointerException - если указанное действие равно null

removeIf

public boolean removeIf(Predicate<? super E> filter)

Описание скопировано из интерфейса: Collection

Удаляет все элементы этого набора, которые удовлетворяют данному предикату. Ошибки или исключения времени выполнения, возникающие во время итерации или предикатом, передаются вызывающей стороне.

Определено в:
removeIf в интерфейсе Collection<E>
Параметры:
filter - предикат, который возвращает true для удаляемых элементов
Возвращает:
true если какие-либо элементы были удалены
Исключения:
NullPointerException - если указанный фильтр равен null

removeAll

public boolean removeAll(Collection<?> c)

Описание скопировано из класса: AbstractCollection

Удаляет все элементы этого набора, которые также содержатся в указанном наборе (необязательная операция). После этого вызова в этом наборе не будет элементов, общих с указанным набором.

Определено в:
removeAll в интерфейсе Collection<E>
Переопределяет:
removeAll в классе AbstractCollection<E>
Параметры:
c - набор, содержащий элементы, которые должны быть удалены из этого набора
Возвращает:
true если этот набор изменился в результате вызова
Исключения:
NullPointerException - если этот набор содержит один или несколько нулевых элементов, а указанный набор не поддерживает нулевые элементы (необязательно), или если указанный набор равен null
См. также:
AbstractCollection.remove(Object), AbstractCollection.contains(Object)

retainAll

public boolean retainAll(Collection<?> c)

Описание скопировано из класса: AbstractCollection

Сохраняет только элементы этого набора, которые содержатся в указанном наборе (необязательная операция). Другими словами, удаляет из этого набора все элементы, которые не содержатся в указанном наборе.

Определено в:
retainAll в интерфейсе Collection<E>
Переопределяет:
retainAll в классе AbstractCollection<E>
Параметры:
c - набор, содержащий элементы, которые должны быть сохранены в этом наборе
Возвращает:
true если этот набор изменился в результате вызова
Исключения:
NullPointerException - если этот набор содержит один или несколько нулевых элементов, а указанный набор не допускает нулевые элементы (необязательно), или если указанный набор равен null
См. также:
AbstractCollection.remove(Object), AbstractCollection.contains(Object)

© 1993, 2020, 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.
https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/concurrent/ArrayBlockingQueue.html

Spec-Zone .ru
спецификации, руководства, описания, API