Класс ArrayBlockingQueue<E>

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

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

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

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

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

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

ArrayBlockingQueue

public ArrayBlockingQueue(int capacity)

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

Параметры:

capacity - ёмкость этой очереди

Исключения:

IllegalArgumentException - если capacity < 1

ArrayBlockingQueue

public ArrayBlockingQueue(int capacity,
                          boolean fair)

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

Параметры:

capacity - ёмкость этой очереди

fair - если true , то доступ к очереди для потоков, заблокированных на вставку или удаление, обрабатывается в порядке FIFO; если false порядок доступа не определён.

Исключения:

IllegalArgumentException - если capacity < 1

ArrayBlockingQueue

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

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

Параметры:

capacity - ёмкость этой очереди

fair - если true , то доступ к очереди для потоков, заблокированных на вставку или удаление, обрабатывается в порядке FIFO; если false порядок доступа не определён.

c - набор элементов, которые должны содержаться первоначально

Исключения:

IllegalArgumentException - если capacity меньше c.size(), или меньше 1.

NullPointerException - если указанный набор или любой из его элементов равны null

Методы

add

public boolean add(E e)

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

Определено в:

add в интерфейсе Collection<E>

Определено в:

add в интерфейсе BlockingQueue<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

poll

public E poll()

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

Возвращает и удаляет голову этой очереди или возвращает null , если эта очередь пуста.

Определено в:

poll в интерфейсе Queue<E>

Возвращает:

голова этой очереди или null , если эта очередь пуста

take

public E take()
       throws InterruptedException

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

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

Определено в:

take в интерфейсе BlockingQueue<E>

Возвращает:

голова этой очереди

Исключения:

InterruptedException - если прервано ожидание

poll

public E poll(long timeout,
              TimeUnit unit)
       throws InterruptedException

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

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

Определено в:

poll в интерфейсе BlockingQueue<E>

Параметры:

timeout - время ожидания, прежде чем прекратить попытку, в единицах unit

unit - TimeUnit определяющий способ интерпретации параметра timeout

Возвращает:

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

Исключения:

InterruptedException - если прервано ожидание

peek

public E peek()

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

Возвращает, но не удаляет, голову этой очереди или возвращает null , если эта очередь пуста.

Определено в:

peek в интерфейсе Queue<E>

Возвращает:

голова этой очереди или null , если эта очередь пуста

size

public int size()

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

Определено в:

size в интерфейсе Collection<E>

Определено в:

size в классе AbstractCollection<E>

Возвращает:

количество элементов в этой очереди

remainingCapacity

public int remainingCapacity()

Определено в:

remainingCapacity в интерфейсе BlockingQueue<E>

Возвращает:

остающаяся ёмкость

remove

public boolean remove(Object o)

Определено в:

remove в интерфейсе Collection<E>

Определено в:

remove в интерфейсе BlockingQueue<E>

Переопределено в:

remove в классе AbstractCollection<E>

Параметры:

o - элемент, который нужно удалить из этой очереди, если он присутствует

Возвращает:

true если эта очередь изменилась в результате вызова

contains

public boolean contains(Object o)

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

Определено в:

contains в интерфейсе Collection<E>

Определено в:

contains в интерфейсе BlockingQueue<E>

Переопределено в:

contains в классе AbstractCollection<E>

Параметры:

o - объект, который нужно проверить на наличие в этой очереди

Возвращает:

true , если эта очередь содержит указанный элемент

toArray

public Object[] toArray()

Определено в:

toArray в интерфейсе Collection<E>

Переопределено в:

toArray в классе AbstractCollection<E>

Возвращает:

массив, содержащий все элементы этой очереди

toArray

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

String[] y = x.toArray(new String[0]);

Указано в:

toArray в интерфейсе Collection<E>

Переопределяет:

toArray в классе AbstractCollection<E>

Параметры типа:

T - тип массива, содержащего коллекцию

Параметры:

a - массив, в который должны быть сохранены элементы очереди, если он достаточно большой; в противном случае для этой цели выделяется новый массив того же типа

Возвращает:

массив, содержащий все элементы этой очереди

Исключение:

ArrayStoreException - если тип указанного массива не является супертипом типа каждого элемента в этой очереди

NullPointerException - если указанный массив null

toString

public String toString()

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

Возвращает строковое представление этой коллекции. Строковое представление состоит из списка элементов коллекции в порядке их возврата итератором, заключённых в квадратные скобки ("[]"). Соседние элементы разделяются символами ", " (запятая и пробел). Элементы преобразуются в строки с помощью String.valueOf(Object).

Переопределяет:

toString в классе AbstractCollection<E>

Возвращает:

строковое представление этой коллекции

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 в интерфейсе Iterable<E>

Указано в:

iterator в интерфейсе Collection<E>

Указано в:

iterator в классе AbstractCollection<E>

Возвращает:

итератор по элементам этой очереди в правильном порядке

spliterator

public Spliterator<E> spliterator()

Указано в:

spliterator в интерфейсе Iterable<E>

Указано в:

spliterator в интерфейсе Collection<E>

Примечание для реализации:

Spliterator реализует trySplit для обеспечения ограниченной параллельности.

Возвращает:

Spliterator по элементам этой очереди

С:

1.8