Класс ConcurrentLinkedQueue<E>

java.lang.Object

java.util.AbstractCollection<E>

java.util.AbstractQueue<E>

java.util.concurrent.ConcurrentLinkedQueue<E>

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

Все реализованные интерфейсы:: Serializable, Iterable<E>, Collection<E>, Queue<E>

public class ConcurrentLinkedQueue<E> extends AbstractQueue<E> implements Queue<E>, Serializable

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

Эта реализация использует эффективный неблокирующий алгоритм, основанный на алгоритме, описанном в Simple, Fast, and Practical Non-Blocking and Blocking Concurrent Queue Algorithms Магеда М. Майкла и Майкла Л. Скотта.

Итераторы являются слабо согласованными, возвращая элементы, отражающие состояние очереди в какой-то момент времени или после создания итератора. Они не бросают исключение ConcurrentModificationException и могут работать параллельно с другими операциями. Элементы, содержащиеся в очереди с момента создания итератора, будут возвращены ровно один раз.

Следует учесть, что, в отличие от большинства коллекций, метод size НЕ является операцией с постоянной сложностью. Из-за асинхронной природы этих очередей определение текущего количества элементов требует обхода элементов, поэтому результат может быть неточным, если эта коллекция изменяется во время обхода.

Массовые операции, которые добавляют, удаляют или проверяют несколько элементов, такие как addAll(java.util.Collection<? extends E>), removeIf(java.util.function.Predicate<? super E>) или forEach(java.util.function.Consumer<? super E>), не гарантируются как атомарные операции. Например, обход forEach параллельно с операцией addAll может наблюдать только некоторые добавленные элементы.

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

Влияние согласованности памяти: Как и в других коллекциях, используемых в многопоточных средах, действия в потоке до помещения объекта в ConcurrentLinkedQueue предшествуют последующим действиям доступа или удаления этого элемента из ConcurrentLinkedQueue в другом потоке.

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

С момента:

1.5

См. также:

Сериализованная форма

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

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

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

Модификатор и тип	Метод	Описание
`boolean`	`add(E e)`	Вставляет указанный элемент в конец этой очереди.
`boolean`	`addAll(Collection<? extends E> c)`	Добавляет все элементы из заданной коллекции в конец этой очереди в порядке, в котором они возвращаются итератором заданной коллекции.
`void`	`clear()`	Удаляет все элементы из этой очереди.
`boolean`	`contains(Object o)`	Возвращает `true`, если эта очередь содержит указанный элемент.
`void`	`forEach(Consumer<? super E> action)`	Выполняет заданное действие для каждого элемента `Iterable` до обработки всех элементов или возникновения исключения.
`boolean`	`isEmpty()`	Возвращает `true`, если эта очередь не содержит элементов.
`Iterator<E>`	`iterator()`	Возвращает итератор по элементам этой очереди в правильном порядке.
`boolean`	`offer(E e)`	Вставляет указанный элемент в конец этой очереди.
`E`	`peek()`	Извлекает, но не удаляет, голову этой очереди или возвращает `null`, если очередь пуста.
`E`	`poll()`	Извлекает и удаляет голову этой очереди или возвращает `null`, если очередь пуста.
`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

clear, element, remove

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

containsAll, toString

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

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

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

containsAll, equals, hashCode, parallelStream, stream, toArray

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

element, remove

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

ConcurrentLinkedQueue

public ConcurrentLinkedQueue()

Создаёт пустую очередь.

ConcurrentLinkedQueue

public ConcurrentLinkedQueue(Collection<? extends E> c)

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

Parameters:: c - набор элементов, которые должны содержаться в очереди изначально
Throws:: NullPointerException - если указанный набор или любой из его элементов равны null

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

add

public boolean add(E e)

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

Specified by:: add в интерфейсе Collection<E>
Specified by:: add в интерфейсе Queue<E>
Overrides:: add в классе AbstractQueue<E>
Parameters:: e - элемент для добавления
Returns:: true (как указано в Collection.add(E))
Throws:: NullPointerException - если указанный элемент равен null

offer

public boolean offer(E e)

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

Specified by:: offer в интерфейсе Queue<E>
Parameters:: e - элемент для добавления
Returns:: true (как указано в Queue.offer(E))
Throws:: NullPointerException - если указанный элемент равен null

poll

public E poll()

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

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

Specified by:: poll в интерфейсе Queue<E>
Returns:: голова этой очереди или null если эта очередь пуста

peek

public E peek()

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

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

Specified by:: peek в интерфейсе Queue<E>
Returns:: голова этой очереди или null если эта очередь пуста

isEmpty

public boolean isEmpty()

Возвращает true если эта очередь не содержит элементов.

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

size

public int size()

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

Обратите внимание, что, в отличие от большинства коллекций, этот метод НЕ является операцией с постоянной сложностью. Из-за асинхронного характера этих очередей определение текущего количества элементов требует O(n) обхода. Кроме того, если элементы добавляются или удаляются во время выполнения этого метода, возвращаемый результат может быть неточным. Таким образом, этот метод обычно не очень полезен в многопоточных приложениях.

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

contains

public boolean contains(Object o)

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

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

remove

public boolean remove(Object o)

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

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

addAll

public boolean addAll(Collection<? extends E> c)

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

Specified by:

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

Overrides:

addAll в классе AbstractQueue<E>

Parameters:

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

Returns:

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

Throws:

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

IllegalArgumentException - если набор - это эта очередь

See Also:

AbstractQueue.add(Object)

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 является слабо согласованным.

Spliterator сообщает о Spliterator.CONCURRENT, Spliterator.ORDERED и Spliterator.NONNULL.

Specified by:: spliterator в интерфейсе Collection<E>
Specified by:: spliterator в интерфейсе Iterable<E>
Implementation Note:: Spliterator реализует trySplit для разрешения ограниченного параллелизма.
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

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

Specified by:

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

Overrides:

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

Parameters:

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

Returns:

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

Throws:

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

See Also:

clear

public void clear()

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

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

Эта реализация многократно вызывает poll до тех пор, пока не вернет null.

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

forEach

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

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

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

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

Specified by:: forEach в интерфейсе Iterable<E>
Parameters:: action - Действие, которое должно выполняться для каждого элемента
Throws:: NullPointerException - если указанное действие равно null

© 1993, 2021, 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/17/docs/api/java.base/java/util/concurrent/ConcurrentLinkedQueue.html