Класс ConcurrentLinkedQueue<E>

java.lang.Object

java.util.AbstractCollection<E>

java.util.AbstractQueue<E>

java.util.concurrent.ConcurrentLinkedQueue<E>

Type Parameters:: 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.

Since:

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:

toArray

public Object[] toArray()

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

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

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

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

toArray

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

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

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

Как и метод toArray(), этот метод служит мостом между API на основе массивов и 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.CONCURRENT, Spliterator.ORDERED и Spliterator.NONNULL.

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

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-элементов, а указанный набор не поддерживает null-элементы (необязательное) или если указанный набор равен null

См. также:

retainAll

public boolean retainAll(Collection<?> c)

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

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

Указано в:

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

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

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

Параметры:

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

Возвращает:

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

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

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

См. также:

clear

public void clear()

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

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

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

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

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/ConcurrentLinkedQueue.html