Module java.base
Package java.util.concurrent

Class 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元素。

此实现采用了一种高效的非阻塞算法，该算法基于Maged M. Michael和Michael L. Scott在 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>)，不保证以原子方式执行。例如，与addAll操作并发进行的forEach遍历可能只观察到一些已添加的元素。

此类及其迭代器实现了Queue和Iterator接口的所有可选方法。

内存一致性效果: 与其他并发集合一样，在将对象放入ConcurrentLinkedQueue之前的线程中的操作先行发生于在另一个线程中访问或从ConcurrentLinkedQueue中删除该元素的操作。

此类是Java集合框架的成员。

自 JDK 版本:
1.5
参见:

  • Constructor Summary

    Constructors
    Constructor
    Description
    ConcurrentLinkedQueue()
    创建一个最初为空的ConcurrentLinkedQueue。
    ConcurrentLinkedQueue(Collection<? extends E> c)
    创建一个最初包含给定集合元素的ConcurrentLinkedQueue，按照集合迭代器的遍历顺序添加。

  • Method Summary

    Modifier and Type
    Method
    Description
    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)
    返回包含此队列中所有元素的数组，按正确顺序；返回数组的运行时类型是指定数组的类型。

    Methods declared in class java.util.AbstractQueue

    clear, element, remove

    Methods declared in class java.util.AbstractCollection

    containsAll, toString

    Methods declared in class java.lang.Object

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

    Methods declared in interface java.util.Collection

    containsAll, equals, hashCode, parallelStream, stream, toArray

    Methods declared in interface java.util.Queue

    element, remove

  • Constructor Details

    • ConcurrentLinkedQueue

      public ConcurrentLinkedQueue()
      创建一个最初为空的ConcurrentLinkedQueue。

    • ConcurrentLinkedQueue

      public ConcurrentLinkedQueue(Collection<? extends E> c)
      创建一个最初包含给定集合元素的ConcurrentLinkedQueue，按照集合迭代器的遍历顺序添加。
      参数:
      c - 最初包含元素的集合
      抛出:
      NullPointerException - 如果指定集合或其任何元素为null

  • Method Details

    • add

      public boolean add(E e)
      将指定元素插入到此队列的尾部。由于队列是无界的，此方法永远不会抛出IllegalStateException或返回false。
      指定者:
      add 在接口 Collection<E>中
      指定者:
      add 在接口 Queue<E>中
      覆盖:
      add 在类 AbstractQueue<E>中
      参数:
      e - 要添加的元素
      返回:
      true（如Collection.add(E)指定的）
      抛出:
      NullPointerException - 如果指定元素为null

    • offer

      public boolean offer(E e)
      将指定元素插入到此队列的尾部。由于队列是无界的，此方法永远不会返回false。
      指定者:
      offer 在接口 Queue<E>中
      参数:
      e - 要添加的元素
      返回:
      true（如Queue.offer(E)指定的）
      抛出:
      NullPointerException - 如果指定元素为null

    • poll

      public E poll()
      从接口复制的描述: Queue
      检索并移除此队列的头部，如果此队列为空，则返回null。
      指定者:
      poll 在接口 Queue<E>中
      返回:
      此队列的头部，如果此队列为空，则返回null

    • peek

      public E peek()
      从接口复制的描述: Queue
      检索但不移除此队列的头部，如果此队列为空，则返回null。
      指定者:
      peek 在接口 Queue<E>中
      返回:
      此队列的头部，如果此队列为空，则返回null

    • isEmpty

      public boolean isEmpty()
      如果此队列不包含任何元素，则返回true。
      指定由：
      isEmpty 在接口 Collection<E>中
      覆盖：
      isEmpty 在类 AbstractCollection<E>中
      返回：
      如果此队列不包含任何元素，则返回true

    • size

      public int size()
      返回此队列中的元素数量。如果此队列包含超过Integer.MAX_VALUE个元素，则返回Integer.MAX_VALUE。

      请注意，与大多数集合不同，此方法不是一个常量时间操作。由于这些队列的异步性质，确定当前元素数量需要进行O(n)遍历。此外，如果在执行此方法期间添加或删除元素，则返回的结果可能不准确。因此，在并发应用程序中，此方法通常不是非常有用的。

      指定由：
      size 在接口 Collection<E>中
      返回：
      此队列中的元素数量

    • contains

      public boolean contains(Object o)
      如果此队列包含指定元素，则返回true。更正式地说，如果此队列包含至少一个元素e使得o.equals(e)为true，则返回true。
      指定由：
      contains 在接口 Collection<E>中
      覆盖：
      contains 在类 AbstractCollection<E>中
      参数：
      o - 要在此队列中检查包含性的对象
      返回：
      如果此队列包含指定元素，则返回true

    • remove

      public boolean remove(Object o)
      从此队列中移除指定元素的单个实例（如果存在）。更正式地说，如果此队列包含一个或多个这样的元素e使得o.equals(e)为true，则移除一个元素e。如果此队列包含指定元素，则返回true（或者等效地，如果此队列由于调用而更改，则返回true）。
      指定由：
      remove 在接口 Collection<E>中
      覆盖：
      remove 在类 AbstractCollection<E>中
      参数：
      o - 如果存在，则从此队列中移除的元素
      返回：
      如果此队列由于调用而更改，则返回true

    • addAll

      public boolean addAll(Collection<? extends E> c)
      将指定集合中的所有元素追加到此队列的末尾，顺序与指定集合的迭代器返回它们的顺序相同。尝试将队列的addAll到自身会导致IllegalArgumentException。
      指定由：
      addAll 在接口 Collection<E>中
      覆盖：
      addAll 在类 AbstractQueue<E>中
      参数：
      c - 要插入到此队列中的元素
      返回：
      如果此队列由于调用而更改，则返回true
      抛出：
      NullPointerException - 如果指定的集合或其任何元素为null
      IllegalArgumentException - 如果集合是此队列
      参见：

    • 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

    • 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版本起：
      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