Module java.base
Package java.util.concurrent

Class LinkedTransferQueue<E>

java.lang.Object
java.util.AbstractCollection<E>
java.util.AbstractQueue<E>
java.util.concurrent.LinkedTransferQueue<E>
类型参数:
E - 此队列中保存的元素的类型
所有实现的接口:
Serializable, Iterable<E>, Collection<E>, BlockingQueue<E>, TransferQueue<E>, Queue<E>
public class LinkedTransferQueue<E> extends AbstractQueue<E> implements TransferQueue<E>, Serializable
基于链表节点的无界TransferQueue。此队列根据任何给定生产者的顺序将元素按FIFO（先进先出）排序。队列的头部是队列中已经存在最长时间的元素，对于某个生产者而言。队列的尾部是队列中已经存在最短时间的元素，对于某个生产者而言。

请注意，与大多数集合不同，size方法不是一个常量时间操作。由于这些队列的异步性质，确定当前元素数量需要遍历元素，因此如果在遍历期间修改了此集合，则可能报告不准确的结果。

添加、删除或检查多个元素的批量操作，例如AbstractQueue.addAll(java.util.Collection<? extends E>)、removeIf(java.util.function.Predicate<? super E>)或forEach(java.util.function.Consumer<? super E>)，不能保证以原子方式执行。例如，与addAll操作并发的forEach遍历可能只观察到一些已添加的元素。

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

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

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

自版本:
1.7
参见:

  • Constructor Summary

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

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    add(E e)
    将指定的元素插入到此队列的尾部。
    void
    clear()
    从此队列中移除所有元素。
    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的每个元素执行给定的操作，直到所有元素都已处理或操作引发异常。
    int
    getWaitingConsumerCount()
    返回通过BlockingQueue.take()或定时poll等待接收元素的消费者数量的估计值。
    boolean
    hasWaitingConsumer()
    如果至少有一个消费者正在等待通过BlockingQueue.take()或定时poll接收元素，则返回true。
    boolean
    isEmpty()
    如果此队列不包含任何元素，则返回true。
    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，因为LinkedTransferQueue没有容量限制。
    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)
    返回一个包含此队列中所有元素的数组，按正确的顺序；返回数组的运行时类型与指定数组的类型相同。
    void
    transfer(E e)
    将元素传输给消费者，必要时等待。
    boolean
    tryTransfer(E e)
    如果可能，立即将元素传输给等待的消费者。
    boolean
    tryTransfer(E e, long timeout, TimeUnit unit)
    如果可能，在超时时间之前将元素传输给消费者。

    Methods declared in class java.util.AbstractQueue

    addAll, 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

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

    Methods declared in interface java.util.Queue

    element, remove

  • Constructor Details

    • LinkedTransferQueue

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

    • LinkedTransferQueue

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

  • Method Details

    • 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

    • spliterator

      public Spliterator<E> spliterator()
      返回此队列中元素的Spliterator。

      返回的spliterator是弱一致性的。

      Spliterator报告Spliterator.CONCURRENT、Spliterator.ORDERED和Spliterator.NONNULL。

      指定由:
      spliterator 在接口 Collection<E>中
      指定由:
      spliterator 在接口 Iterable<E>中
      实现注意:
      Spliterator实现trySplit以允许有限的并行性
      返回:
      包含此队列中元素的Spliterator
      自1.8起:
      1.8

    • put

      public void put(E e)
      将指定元素插入到此队列的尾部。由于队列是无界的，因此此方法永远不会阻塞。
      指定由:
      put 在接口 BlockingQueue<E>中
      参数:
      e - 要添加的元素
      抛出:
      NullPointerException - 如果指定元素为null

    • offer

      public boolean offer(E e, long timeout, TimeUnit unit)
      将指定元素插入到此队列的尾部。由于队列是无界的，因此此方法永远不会阻塞或返回false。
      指定由:
      offer 在接口 BlockingQueue<E>中
      参数:
      e - 要添加的元素
      timeout - 等待放弃的时间长度，以unit为单位
      unit - 一个TimeUnit，用于解释timeout参数
      返回:
      true（如BlockingQueue.offer指定的）
      抛出:
      NullPointerException - 如果指定元素为null

    • offer

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

    • add

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

    • tryTransfer

      public boolean tryTransfer(E e)
      如果可能，立即将元素传输给等待的消费者。

      更准确地说，如果已经有消费者在等待接收指定元素（在take()或定时poll中），则立即传输指定元素，否则在不将元素排队的情况下返回false。

      指定由:
      tryTransfer 在接口 TransferQueue<E>中
      参数:
      e - 要传输的元素
      返回:
      true如果元素已传输，否则false
      抛出:
      NullPointerException - 如果指定元素为null

    • transfer

      public void transfer(E e) throws InterruptedException
      将元素传输给消费者，必要时等待。

      更准确地说，如果已经有消费者在等待接收指定元素（在take()或定时poll中），则立即传输指定元素，否则将指定元素插入到此队列的尾部，并等待直到元素被消费者接收。

      指定由:
      transfer 在接口 TransferQueue<E>中
      参数:
      e - 要传输的元素
      抛出:
      NullPointerException - 如果指定元素为null
      InterruptedException - 如果在等待时被中断，此时元素不会被留在队列中

    • tryTransfer

      public boolean tryTransfer(E e, long timeout, TimeUnit unit) throws InterruptedException
      如果在超时之前可以将元素传输给消费者，则将元素传输给消费者。

      更准确地说，如果已经有消费者在等待接收指定元素（在take()或定时poll中），则立即传输指定元素，否则将指定元素插入到此队列的尾部，并等待直到元素被消费者接收，如果在元素可以传输之前经过指定的等待时间，则返回false。

      指定由:
      tryTransfer 在接口 TransferQueue<E>
      参数:
      e - 要传输的元素
      timeout - 在单位unit中等待多长时间后放弃
      unit - 一个TimeUnit，用于解释timeout参数
      返回:
      如果成功，则返回true，如果指定的等待时间在完成之前过去，则返回false，在这种情况下，元素不会被留在队列中
      抛出:
      NullPointerException - 如果指定的元素为null
      InterruptedException - 如果在等待时被中断，此时元素不会被留在队列中

    • 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 - 如果在等待时被中断

    • poll

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

    • drainTo

      public int drainTo(Collection<? super E> c)
      从接口复制的描述: BlockingQueue
      从此队列中移除所有可用元素并将它们添加到给定的集合中。此操作可能比重复轮询此队列更有效。在尝试将元素添加到集合c时遇到故障可能导致在抛出相关异常时元素既不在集合中也不在队列中，或者在两者中的一个中。尝试将队列排空到自身会导致IllegalArgumentException。此外，如果在操作进行中修改了指定的集合，则此操作的行为是未定义的。
      指定由:
      drainTo 在接口 BlockingQueue<E>
      参数:
      c - 要将元素传输到的集合
      返回:
      转移的元素数量
      抛出:
      NullPointerException - 如果指定的集合为null
      IllegalArgumentException - 如果指定的集合为此队列，或者此队列的某个元素属性阻止将其添加到指定的集合中

    • drainTo

      public int drainTo(Collection<? super E> c, int maxElements)
      从接口复制的描述: BlockingQueue
      从此队列中最多移除给定数量的可用元素，并将它们添加到给定的集合中。在尝试将元素添加到集合c时遇到故障可能导致在抛出相关异常时元素既不在集合中也不在队列中，或者在两者中的一个中。尝试将队列排空到自身会导致IllegalArgumentException。此外，如果在操作进行中修改了指定的集合，则此操作的行为是未定义的。
      指定由:
      drainTo 在接口 BlockingQueue<E>
      参数:
      c - 要将元素传输到的集合
      maxElements - 要传输的最大元素数量
      返回:
      转移的元素数量
      抛出:
      NullPointerException - 如果指定的集合为null
      IllegalArgumentException - 如果指定的集合为此队列，或者此队列的某个元素属性阻止将其添加到指定的集合中

    • iterator

      public Iterator<E> iterator()
      返回此队列中元素的迭代器，按正确顺序返回元素，从第一个（头部）到最后一个（尾部）。

      返回的迭代器是弱一致的。

      指定由:
      iterator 在接口 Collection<E>
      指定由:
      iterator 在接口 Iterable<E>
      指定由:
      iterator 在类 AbstractCollection<E>
      返回:
      按正确顺序返回此队列中元素的迭代器

    • peek

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

    • isEmpty

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

    • hasWaitingConsumer

      public boolean hasWaitingConsumer()
      从接口复制的描述: TransferQueue
      返回true如果至少有一个消费者正在等待通过BlockingQueue.take()或定时poll接收元素。返回值表示瞬时状态。
      指定由:
      hasWaitingConsumer 在接口 TransferQueue<E>
      返回:
      如果至少有一个等待的消费者，则返回true

    • size

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

      请注意，与大多数集合不同，此方法不是常量时间操作。由于这些队列的异步性质，确定当前元素数量需要进行O(n)遍历。

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

    • getWaitingConsumerCount

      public int getWaitingConsumerCount()
      从接口复制的描述： TransferQueue
      返回通过BlockingQueue.take()或定时poll接收元素的消费者数量的估计值。返回值是瞬时状态的近似值，如果消费者已完成或放弃等待，则可能不准确。该值可能对监控和启发式有用，但不适用于同步控制。该方法的实现可能比TransferQueue.hasWaitingConsumer()的实现明显慢。
      指定者：
      getWaitingConsumerCount 在接口 TransferQueue<E>
      返回：
      等待接收元素的消费者数量

    • 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。更正式地说，仅当此队列包含至少一个元素e使得o.equals(e)时，才返回true。
      指定者：
      contains 在接口 BlockingQueue<E>
      指定者：
      contains 在接口 Collection<E>
      覆盖：
      contains 在类 AbstractCollection<E>
      参数：
      o - 要在此队列中检查包含性的对象
      返回：
      如果此队列包含指定元素，则返回true

    • remainingCapacity

      public int remainingCapacity()
      由于LinkedTransferQueue没有容量限制，因此始终返回Integer.MAX_VALUE。
      指定者：
      remainingCapacity 在接口 BlockingQueue<E>
      返回：
      Integer.MAX_VALUE（如BlockingQueue.remainingCapacity()中指定的）

    • 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