Module java.base
Package java.util.concurrent

Class DelayQueue<E extends Delayed>

java.lang.Object
java.util.AbstractCollection<E>
java.util.AbstractQueue<E>
java.util.concurrent.DelayQueue<E>
类型参数:
E - 此队列中保存的元素的类型
所有已实现的接口:
Iterable<E>, Collection<E>, BlockingQueue<E>, Queue<E>
public class DelayQueue<E extends Delayed> extends AbstractQueue<E> implements BlockingQueue<E>
一个无界的阻塞队列，其中的元素通常在其延迟到期时变为可移除。

当元素的getDelay(TimeUnit.NANOSECONDS)方法返回小于或等于零的值时，该元素被视为已过期。

如果元素是具有最早到期时间的元素，则将其视为队列的头部，无论是在过去还是将来，如果存在这样的元素。

如果元素是过去具有最早到期时间的已过期元素，则将其视为队列的已过期头部，如果存在这样的元素。当存在已过期头部时，它也是头部。

虽然此类实现了BlockingQueue接口，但它故意违反了BlockingQueue的一般契约，因为以下方法忽略了未过期元素的存在，并且仅仅移除已过期头部：

所有其他方法都会操作已过期和未过期的元素。例如，size()方法返回所有元素的计数。方法peek()可能会返回（非空）头部，即使take()会阻塞等待该元素过期。

此队列不允许空元素。

此类及其迭代器实现了Collection和Iterator接口的所有可选方法。方法iterator()中提供的迭代器不保证以任何特定顺序遍历DelayQueue的元素。

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

自 JDK 版本:
1.5

  • Constructor Details

    • DelayQueue

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

    • DelayQueue

      public DelayQueue(Collection<? extends E> c)
      创建一个最初包含给定Delayed实例集合的DelayQueue。
      参数:
      c - 最初包含元素的集合
      抛出:
      NullPointerException - 如果指定的集合或其任何元素为null

  • Method Details

    • add

      public boolean add(E e)
      将指定的元素插入到此延迟队列中。
      指定者:
      add 在接口 BlockingQueue<E extends Delayed>中
      指定者:
      add 在接口 Collection<E extends Delayed>中
      指定者:
      add 在接口 Queue<E extends Delayed>中
      覆盖:
      add 在类 AbstractQueue<E extends Delayed>中
      参数:
      e - 要添加的元素
      返回:
      true（如Collection.add(E)中指定的）
      抛出:
      NullPointerException - 如果指定的元素为null

    • offer

      public boolean offer(E e)
      将指定的元素插入到此延迟队列中。
      指定者:
      offer 在接口 BlockingQueue<E extends Delayed>中
      指定者:
      offer 在接口 Queue<E extends Delayed>中
      参数:
      e - 要添加的元素
      返回:
      true
      抛出:
      NullPointerException - 如果指定的元素为null

    • put

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

    • offer

      public boolean offer(E e, long timeout, TimeUnit unit)
      将指定的元素插入到此延迟队列中。由于队列是无界的，因此此方法永远不会阻塞。
      指定者:
      offer 在接口 BlockingQueue<E extends Delayed>中
      参数:
      e - 要添加的元素
      timeout - 此参数被忽略，因为该方法永远不会阻塞
      unit - 此参数被忽略，因为该方法永远不会阻塞
      返回:
      true
      抛出:
      NullPointerException - 如果指定的元素为null

    • poll

      public E poll()
      检索并移除此队列的已过期头部，如果此队列没有已过期元素，则返回null。
      指定者:
      poll 在接口 Queue<E extends Delayed>中
      返回值:
      此队列的过期头部，如果此队列没有具有过期延迟的元素，则返回null

    • take

      public E take() throws InterruptedException
      检索并移除此队列的过期头部，如果必要，等待，直到此队列上有一个过期元素可用。
      指定者:
      take 在接口 BlockingQueue<E extends Delayed>中
      返回值:
      此队列的过期头部
      抛出:
      InterruptedException - 如果在等待时被中断

    • poll

      public E poll(long timeout, TimeUnit unit) throws InterruptedException
      检索并移除此队列的过期头部，如果必要，等待，直到此队列上有一个过期元素可用，或者指定的等待时间到期。
      指定者:
      poll 在接口 BlockingQueue<E extends Delayed>中
      参数:
      timeout - 在unit单位内等待多长时间后放弃
      unit - 一个TimeUnit，用于解释timeout参数
      返回值:
      此队列的过期头部，如果指定的等待时间在具有过期延迟的元素变为可用之前到期，则返回null
      抛出:
      InterruptedException - 如果在等待时被中断

    • remove

      public E remove()
      检索并移除此队列的过期头部，如果此队列没有过期元素，则抛出异常。
      指定者:
      remove 在接口 Queue<E extends Delayed>中
      覆盖:
      remove 在类 AbstractQueue<E extends Delayed>中
      返回值:
      此队列的过期头部
      抛出:
      NoSuchElementException - 如果此队列没有具有过期延迟的元素

    • peek

      public E peek()
      检索但不移除此队列的头部，如果此队列为空，则返回null。与poll不同，如果队列中没有过期元素可用，此方法将返回下一个将要过期的元素（如果存在）。
      指定者:
      peek 在接口 Queue<E extends Delayed>中
      返回值:
      此队列的头部，如果此队列为空，则返回null

    • size

      public int size()
      从接口复制的描述: Collection
      返回此集合中的元素数量。如果此集合包含的元素超过Integer.MAX_VALUE个，则返回Integer.MAX_VALUE。
      指定者:
      size 在接口 Collection<E extends Delayed>中
      返回值:
      此集合中的元素数量

    • drainTo

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

    • drainTo

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

    • clear

      public void clear()
      原子性地从此延迟队列中移除所有元素。此调用返回后，队列将为空。不会等待具有未过期延迟的元素；它们只是从队列中丢弃。
      指定者:
      clear 在接口 Collection<E extends Delayed>中
      覆盖:
      clear 在类 AbstractQueue<E extends Delayed>中

    • remainingCapacity

      public int remainingCapacity()
      由于DelayQueue没有容量限制，因此始终返回Integer.MAX_VALUE。
      指定由：
      remainingCapacity 在接口 BlockingQueue<E extends Delayed>
      返回：
      Integer.MAX_VALUE

    • toArray

      public Object[] toArray()
      返回一个包含此队列中所有元素的数组。返回的数组元素没有特定顺序。

      返回的数组将是“安全”的，因为此队列不会保留对它的任何引用。（换句话说，此方法必须分配一个新数组）。因此，调用者可以自由修改返回的数组。

      此方法充当基于数组和基于集合的API之间的桥梁。

      指定由：
      toArray 在接口 Collection<E extends Delayed>
      覆盖：
      toArray 在类 AbstractCollection<E extends Delayed>
      返回：
      包含此队列中所有元素的数组

    • toArray

      public <T> T[] toArray(T[] a)
      返回一个包含此队列中所有元素的数组；返回的数组的运行时类型与指定数组的类型相同。返回的数组元素没有特定顺序。如果队列适合指定的数组，则将其返回。否则，将使用指定数组的运行时类型和此队列的大小分配一个新数组。

      如果此队列适合指定数组并有剩余空间（即，数组的元素比此队列多），则紧随队列末尾的数组元素将设置为null。

      与toArray()方法类似，此方法充当基于数组和基于集合的API之间的桥梁。此外，此方法允许精确控制输出数组的运行时类型，并且在某些情况下可用于节省分配成本。

      以下代码可用于将延迟队列转储到新分配的Delayed数组中：

       Delayed[] a = q.toArray(new Delayed[0]);
      注意，toArray(new Object[0])在功能上与toArray()相同。
      指定由：
      toArray 在接口 Collection<E extends Delayed>
      覆盖：
      toArray 在类 AbstractCollection<E extends Delayed>
      类型参数：
      T - 包含集合的数组的组件类型
      参数：
      a - 如果足够大，则要将队列元素存储到其中的数组；否则，将为此目的分配相同运行时类型的新数组
      返回：
      包含此队列中所有元素的数组
      抛出：
      ArrayStoreException - 如果指定数组的运行时类型不是此队列中每个元素的运行时类型的超类型
      NullPointerException - 如果指定数组为null

    • remove

      public boolean remove(Object o)
      从此队列中删除指定元素的单个实例（如果存在），无论其是否已过期。
      指定由：
      remove 在接口 BlockingQueue<E extends Delayed>
      指定由：
      remove 在接口 Collection<E extends Delayed>
      覆盖：
      remove 在类 AbstractCollection<E extends Delayed>
      参数：
      o - 如果存在，则从此集合中删除的元素
      返回：
      true 如果由于此调用而删除了一个元素

    • iterator

      public Iterator<E> iterator()
      返回一个迭代器，用于遍历此队列中所有元素（已过期和未过期）。迭代器不以任何特定顺序返回元素。

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

      指定由：
      iterator 在接口 Collection<E extends Delayed>
      指定由：
      iterator 在接口 Iterable<E extends Delayed>
      指定由：
      iterator 在类 AbstractCollection<E extends Delayed>
      返回：
      一个迭代器，用于遍历此队列中的元素