Класс PriorityBlockingQueue<E>

java.lang.Object

java.util.AbstractCollection<E>

java.util.AbstractQueue<E>

java.util.concurrent.PriorityBlockingQueue<E>

Type Parameters:: E - тип элементов, хранимых в этой очереди

All Implemented Interfaces:: Serializable, Iterable<E>, Collection<E>, BlockingQueue<E>, Queue<E>

public class PriorityBlockingQueue<E> extends AbstractQueue<E> implements BlockingQueue<E>, Serializable

Неограниченная блокирующая очередь, использующая те же правила упорядочения, что и класс PriorityQueue, и предоставляющая блокирующие операции извлечения. Хотя эта очередь логически неограничена, попытки добавления могут завершиться неудачей из-за исчерпания ресурсов (вызывая OutOfMemoryError). Этот класс не допускает null элементов. Очередь с приоритетом, использующая естественный порядок, также не допускает вставки несопоставимых объектов (в результате чего ClassCastException).

Этот класс и его итератор реализуют все необязательные методы интерфейсов Collection и Iterator. Итератор, предоставленный в методе iterator(), и итератор Spliterator, предоставленный в методе spliterator(), не гарантируют обход элементов PriorityBlockingQueue в каком-либо определённом порядке. Если вам нужен упорядоченный обход, рассмотрите использование Arrays.sort(pq.toArray()). Также, метод drainTo может использоваться для удаления некоторых или всех элементов в порядке приоритета и их размещения в другой коллекции.

Операции с этим классом не гарантируют порядок элементов с одинаковым приоритетом. Если вам нужно принудительно установить порядок, вы можете определить пользовательские классы или компараторы, использующие вторичный ключ для разрыва ничьих в значениях первичного приоритета. Например, вот класс, который применяет метод «первый пришёл — первый обслужен» для разрыва ничьих между сопоставимыми элементами. Чтобы использовать его, вы должны вставить new FIFOEntry(anEntry) вместо простого объекта entry.

 
 class FIFOEntry<E extends Comparable<? super E>>
     implements Comparable<FIFOEntry<E>> {
   static final AtomicLong seq = new AtomicLong();
   final long seqNum;
   final E entry;
   public FIFOEntry(E entry) {
     seqNum = seq.getAndIncrement();
     this.entry = entry;
   }
   public E getEntry() { return entry; }
   public int compareTo(FIFOEntry<E> other) {
     int res = entry.compareTo(other.entry);
     if (res == 0 && other.entry != this.entry)
       res = (seqNum < other.seqNum ? -1 : 1);
     return res;
   }
 }

Этот класс является членом Java Collections Framework.

Since:

1.5

See Also:

Краткое описание конструкторов

Конструктор	Описание
`PriorityBlockingQueue()`	Создаёт `PriorityBlockingQueue` с начальным размером по умолчанию (11), который упорядочивает элементы в соответствии с их естественным порядком.
`PriorityBlockingQueue(int initialCapacity)`	Создаёт `PriorityBlockingQueue` с указанным начальным размером, который упорядочивает элементы в соответствии с их естественным порядком.
`PriorityBlockingQueue(int initialCapacity, Comparator<? super E> comparator)`	Создаёт `PriorityBlockingQueue` с указанным начальным размером, который упорядочивает элементы в соответствии с указанным компаратором.
`PriorityBlockingQueue(Collection<? extends E> c)`	Создаёт `PriorityBlockingQueue`, содержащую элементы в указанной коллекции.

Краткое описание методов

Модификатор и тип	Метод	Описание
`boolean`	`add(E e)`	Вставляет указанный элемент в эту очередь с приоритетом.
`void`	`clear()`	Атомарно удаляет все элементы из этой очереди.
`Comparator<? super E>`	`comparator()`	Возвращает компаратор, используемый для упорядочения элементов в этой очереди, или `null` если эта очередь использует естественный порядок своих элементов.
`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)`	Вставляет указанный элемент в эту очередь с приоритетом.
`boolean`	`offer(E e, long timeout, TimeUnit unit)`	Вставляет указанный элемент в эту очередь с приоритетом.
`E`	`peek()`	Возвращает голову этой очереди, не удаляя её, или возвращает `null` если эта очередь пуста.
`E`	`poll()`	Возвращает и удаляет голову этой очереди, или возвращает `null` если эта очередь пуста.
`E`	`poll(long timeout, TimeUnit unit)`	Возвращает и удаляет голову этой очереди, ожидая до указанного времени ожидания, если необходимо, для того, чтобы элемент стал доступным.
`void`	`put(E e)`	Вставляет указанный элемент в эту очередь с приоритетом.
`int`	`remainingCapacity()`	Всегда возвращает `Integer.MAX_VALUE`, так как `PriorityBlockingQueue` не ограничена по размеру.
`boolean`	`remove(Object o)`	Удаляет один экземпляр указанного элемента из этой очереди, если он присутствует.
`boolean`	`removeAll(Collection<?> c)`	Удаляет все элементы этой коллекции, которые также содержатся в указанной коллекции (необязательная операция).
`boolean`	`removeIf(Predicate<? super E> filter)`	Удаляет все элементы этой коллекции, которые удовлетворяют заданному предикату.
`boolean`	`retainAll(Collection<?> c)`	Оставляет только элементы в этой коллекции, которые содержатся в указанной коллекции (необязательная операция).
`int`	`size()`	Возвращает количество элементов в этой коллекции.
`Spliterator<E>`	`spliterator()`	Возвращает `Spliterator` по элементам в этой очереди.
`E`	`take()`	Возвращает и удаляет голову этой очереди, ожидая, если необходимо, пока элемент не станет доступным.
`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.Collection

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

Методы, унаследованные от интерфейса java.util.Queue

element, remove

Детали конструкторов

PriorityBlockingQueue

public PriorityBlockingQueue()

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

PriorityBlockingQueue

public PriorityBlockingQueue(int initialCapacity)

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

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

PriorityBlockingQueue

public PriorityBlockingQueue(int initialCapacity, Comparator<? super E> comparator)

Создаёт PriorityBlockingQueue с заданной начальной ёмкостью, упорядочивающей элементы в соответствии с указанным компаратором.

Параметры:: initialCapacity - начальная ёмкость для этой очереди с приоритетом; comparator - компаратор, который будет использоваться для упорядочивания этой очереди с приоритетом. Если null, будет использован естественный порядок элементов.
Исключения:: IllegalArgumentException - если initialCapacity меньше 1

PriorityBlockingQueue

public PriorityBlockingQueue(Collection<? extends E> c)

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

Параметры:: c - набор, элементы которого должны быть помещены в эту очередь с приоритетом
Исключения:: ClassCastException - если элементы указанного набора не могут быть сравнены друг с другом в соответствии с порядком очереди с приоритетом; NullPointerException - если указанный набор или любой из его элементов равен null

Детали методов

add

public boolean add(E e)

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

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

offer

public boolean offer(E e)

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

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

put

public void put(E e)

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

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

offer

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

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

Определено в:: offer в интерфейсе BlockingQueue<E>
Параметры:: e - добавляемый элемент; timeout - Этот параметр игнорируется, так как метод никогда не блокируется; unit - Этот параметр игнорируется, так как метод никогда не блокируется
Возвращает:: true (как указано в BlockingQueue.offer)
Исключения:: ClassCastException - если указанный элемент нельзя сравнить с текущими элементами в очереди с приоритетом в соответствии с порядком очереди; 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 если эта очередь пуста

comparator

public Comparator<? super E> comparator()

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

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

size

public int size()

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

Возвращает количество элементов в этом наборе. Если этот набор содержит более Integer.MAX_VALUE элементов, возвращает Integer.MAX_VALUE.

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

remainingCapacity

public int remainingCapacity()

Всегда возвращает Integer.MAX_VALUE , так как PriorityBlockingQueue не ограничена по ёмкости.

Определено в:: remainingCapacity в интерфейсе BlockingQueue<E>
Возвращает:: Integer.MAX_VALUE всегда

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

Specified by:: contains в интерфейсе BlockingQueue<E>
Specified by:: contains в интерфейсе Collection<E>
Overrides:: contains в классе AbstractCollection<E>
Parameters:: o - объект, который нужно проверить на наличие в этой очереди
Returns:: true , если эта очередь содержит указанный элемент

drainTo

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

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

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

Specified by:: drainTo в интерфейсе BlockingQueue<E>
Parameters:: c - коллекция, в которую нужно перенести элементы
Returns:: количество переданных элементов
Throws:: UnsupportedOperationException - если добавление элементов не поддерживается заданной коллекцией; ClassCastException - если класс элемента этой очереди препятствует его добавлению в заданную коллекцию; NullPointerException - если заданная коллекция равна null; IllegalArgumentException - если заданная коллекция является этой очередью или какое-либо свойство элемента этой очереди препятствует его добавлению в заданную коллекцию

drainTo

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

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

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

Specified by:: drainTo в интерфейсе BlockingQueue<E>
Parameters:: c - коллекция, в которую нужно перенести элементы; maxElements - максимальное количество элементов для переноса
Returns:: количество переданных элементов
Throws:: UnsupportedOperationException - если добавление элементов не поддерживается заданной коллекцией; ClassCastException - если класс элемента этой очереди препятствует его добавлению в заданную коллекцию; NullPointerException - если заданная коллекция равна null; IllegalArgumentException - если заданная коллекция является этой очередью или какое-либо свойство элемента этой очереди препятствует его добавлению в заданную коллекцию

clear

public void clear()

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

Specified by:: clear в интерфейсе Collection<E>
Overrides:: clear в классе AbstractQueue<E>

toArray

public Object[] toArray()

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

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

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

Specified by:: toArray в интерфейсе Collection<E>
Overrides:: toArray в классе AbstractCollection<E>
Returns:: массив, содержащий все элементы этой очереди

toArray

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

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

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

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

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

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

Обратите внимание, что toArray(new Object[0]) выполняет те же функции, что и toArray().

Specified by:: toArray в интерфейсе Collection<E>
Overrides:: toArray в классе AbstractCollection<E>
Type Parameters:: T - тип компонента массива, который должен содержать коллекцию
Parameters:: a - массив, в который должны быть сохранены элементы очереди, если он достаточно велик; в противном случае для этой цели выделяется новый массив того же типа выполнения
Returns:: массив, содержащий все элементы этой очереди
Throws:: ArrayStoreException - если тип выполнения указанного массива не является надтипом типа выполнения каждого элемента в этой очереди; NullPointerException - если указанный массив равен null

iterator

public Iterator<E> iterator()

Возвращает итератор по элементам в этой очереди. Итератор не возвращает элементы в каком-либо определенном порядке.

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

Specified by:: iterator в интерфейсе Collection<E>
Specified by:: iterator в интерфейсе Iterable<E>
Specified by:: iterator в классе AbstractCollection<E>
Returns:: итератор по элементам в этой очереди

spliterator

public Spliterator<E> spliterator()

Возвращает Spliterator по элементам в этой очереди. Spliterator не перебирает элементы в каком-либо определенном порядке (характеристика ORDERED не сообщается).

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

Spliterator сообщает о Spliterator.SIZED и Spliterator.NONNULL.

Specified by:: spliterator в интерфейсе Collection<E>
Specified by:: spliterator в интерфейсе Iterable<E>
Implementation Note:: Spliterator дополнительно сообщает о Spliterator.SUBSIZED.
Returns:: Spliterator по элементам в этой очереди
Since:: 1.8

removeIf

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

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

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

Specified by:: removeIf в интерфейсе Collection<E>
Parameters:: filter - предикат, возвращающий true для удаляемых элементов
Returns:: true , если какие-либо элементы были удалены
Throws:: NullPointerException - если заданный фильтр равен null

removeAll

public boolean removeAll(Collection<?> c)

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

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

Specified by:

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

Overrides:

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

Parameters:

c - коллекция, содержащая элементы, которые нужно удалить из этой коллекции

Returns:

true , если эта коллекция изменилась в результате вызова

Throws:

NullPointerException - если эта коллекция содержит один или несколько элементов null, а указанная коллекция не поддерживает элементы null (необязательно), или если указанная коллекция равна null

See Also:

retainAll

public boolean retainAll(Collection<?> c)

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

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

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

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

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

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

Параметры:

c - набор, содержащий элементы, которые должны быть сохранены в этом наборе

Возвращает:

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

Выбрасывает:

NullPointerException - если этот набор содержит один или несколько нулевых элементов, а указанный набор не допускает нулевых элементов (необязательное) или если указанный набор равен null

См. также:

forEach

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

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

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

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

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

© 1993, 2023, 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/21/docs/api/java.base/java/util/concurrent/PriorityBlockingQueue.html