Module java.base
Package java.util.concurrent

Class PriorityBlockingQueue<E>

java.lang.Object
java.util.AbstractCollection<E>
java.util.AbstractQueue<E>
java.util.concurrent.PriorityBlockingQueue<E>
类型参数:
E - 此队列中保存的元素的类型
所有已实现的接口:
Serializable, Iterable<E>, Collection<E>, BlockingQueue<E>, Queue<E>
public class PriorityBlockingQueue<E> extends AbstractQueue<E> implements BlockingQueue<E>, Serializable
一个无界的阻塞队列，使用与类PriorityQueue相同的排序规则，并提供阻塞检索操作。虽然这个队列在逻辑上是无界的，但由于资源耗尽（导致OutOfMemoryError），尝试添加元素可能会失败。此类不允许null元素。依赖于自然排序的优先级队列也不允许插入不可比较的对象（这样做会导致ClassCastException）。

此类及其迭代器实现了Collection和Iterator接口的所有可选方法。在方法iterator()中提供的迭代器和在方法spliterator()中提供的Spliterator 不能保证以任何特定顺序遍历PriorityBlockingQueue的元素。如果需要有序遍历，请考虑使用Arrays.sort(pq.toArray())。此外，方法drainTo可用于按优先级顺序移除一些或所有元素并将它们放入另一个集合中。

此类的操作不保证具有相同优先级的元素的顺序。如果需要强制执行排序，可以定义使用次要键来打破主要优先级值中的平局的自定义类或比较器。例如，这是一个将先进先出的平局应用于可比较元素的类。要使用它，您应该插入一个new FIFOEntry(anEntry)而不是一个普通的entry对象。

 
 class FIFOEntry<E extends Comparable<? super E>>
     implements Comparable<FIFOEntry<E>> {
   static final AtomicLong seq = new AtomicLong();
   final long seqNum;
   final E entry;
   public FIFOEntry(E entry) {
     seqNum = seq.getAndIncrement();
     this.entry = entry;
   }
   public E getEntry() { return entry; }
   public int compareTo(FIFOEntry<E> other) {
     int res = entry.compareTo(other.entry);
     if (res == 0 && other.entry != this.entry)
       res = (seqNum < other.seqNum ? -1 : 1);
     return res;
   }
 }

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

自 JDK 版本:
1.5
参见:

  • Constructor Summary

    Constructors
    Constructor
    Description
    PriorityBlockingQueue()
    创建一个具有默认初始容量（11）的PriorityBlockingQueue，根据其自然排序对其元素进行排序。
    PriorityBlockingQueue(int initialCapacity)
    创建一个具有指定初始容量的PriorityBlockingQueue，根据其自然排序对其元素进行排序。
    PriorityBlockingQueue(int initialCapacity, Comparator<? super E> comparator)
    创建一个具有指定初始容量的PriorityBlockingQueue，根据指定的比较器对其元素进行排序。
    PriorityBlockingQueue(Collection<? extends E> c)
    创建一个包含指定集合中元素的PriorityBlockingQueue。

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    add(E e)
    将指定元素插入此优先级队列。
    void
    clear()
    原子性地从此队列中移除所有元素。
    Comparator<? super E>
    comparator()
    返回用于对此队列中的元素进行排序的比较器，如果此队列使用其元素的自然排序，则返回null。
    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的每个元素执行给定操作，直到所有元素都已处理或操作引发异常。
    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，因为PriorityBlockingQueue没有容量限制。
    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)
    返回一个包含此队列中所有元素的数组；返回数组的运行时类型是指定数组的类型。

    Methods declared in class java.util.AbstractQueue

    addAll, element, remove

    Methods declared in class java.util.AbstractCollection

    containsAll, isEmpty, 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, isEmpty, parallelStream, stream, toArray

    Methods declared in interface java.util.Queue

    element, remove

  • Constructor Details

    • PriorityBlockingQueue

      public PriorityBlockingQueue()
      创建一个具有默认初始容量（11）的PriorityBlockingQueue，根据其自然排序对其元素进行排序。

    • PriorityBlockingQueue

      public PriorityBlockingQueue(int initialCapacity)
      创建一个具有指定初始容量的PriorityBlockingQueue，根据其自然排序对其元素进行排序。
      参数:
      initialCapacity - 此优先级队列的初始容量
      抛出:
      IllegalArgumentException - 如果initialCapacity小于1

    • PriorityBlockingQueue

      public PriorityBlockingQueue(int initialCapacity, Comparator<? super E> comparator)
      创建一个具有指定初始容量的PriorityBlockingQueue，根据指定的比较器对其元素进行排序。
      参数:
      initialCapacity - 此优先级队列的初始容量
      comparator - 将用于对此优先级队列进行排序的比较器。如果为null，则将使用元素的自然排序。
      抛出:
      IllegalArgumentException - 如果initialCapacity小于1

    • PriorityBlockingQueue

      public PriorityBlockingQueue(Collection<? extends E> c)
      创建一个包含指定集合中元素的PriorityBlockingQueue。如果指定的集合是一个SortedSet或一个PriorityBlockingQueue，则此优先级队列将根据相同的排序顺序进行排序。否则，此优先级队列将根据其元素的自然排序进行排序。
      参数:
      c - 要放入此优先级队列中的元素的集合
      抛出:
      ClassCastException - 如果指定集合的元素无法根据优先级队列的排序进行比较
      NullPointerException - 如果指定集合或其任何元素为null

  • Method Details

    • add

      public boolean add(E e)
      将指定元素插入此优先级队列。
      指定者:
      add 在接口 BlockingQueue<E>中指定
      指定者:
      add 在接口 Collection<E>中指定
      指定者:
      add 在接口 Queue<E>中指定
      覆盖:
      add 在类 AbstractQueue<E>中覆盖
      参数:
      e - 要添加的元素
      返回值:
      true (由Collection.add(E)指定)
      抛出:
      ClassCastException - 如果指定的元素无法根据优先级队列的排序与当前在优先级队列中的元素进行比较
      NullPointerException - 如果指定的元素为null

    • offer

      public boolean offer(E e)
      将指定的元素插入此优先级队列。由于队列是无界的，因此此方法永远不会返回false。
      指定者:
      offer 在接口 BlockingQueue<E>中指定
      指定者:
      offer 在接口 Queue<E>中指定
      参数:
      e - 要添加的元素
      返回值:
      true (由Queue.offer(E)指定)
      抛出:
      ClassCastException - 如果指定的元素无法根据优先级队列的排序与当前在优先级队列中的元素进行比较
      NullPointerException - 如果指定的元素为null

    • put

      public void put(E e)
      将指定的元素插入此优先级队列。由于队列是无界的，因此此方法永远不会阻塞。
      指定者:
      put 在接口 BlockingQueue<E>中指定
      参数:
      e - 要添加的元素
      抛出:
      ClassCastException - 如果指定的元素无法根据优先级队列的排序与当前在优先级队列中的元素进行比较
      NullPointerException - 如果指定的元素为null

    • offer

      public boolean offer(E e, long timeout, TimeUnit unit)
      将指定的元素插入此优先级队列。由于队列是无界的，因此此方法永远不会阻塞或返回false。
      指定者:
      offer 在接口 BlockingQueue<E>中指定
      参数:
      e - 要添加的元素
      timeout - 此参数被忽略，因为该方法永远不会阻塞
      unit - 此参数被忽略，因为该方法永远不会阻塞
      返回值:
      true (由BlockingQueue.offer指定)
      抛出:
      ClassCastException - 如果指定的元素无法根据优先级队列的排序与当前在优先级队列中的元素进行比较
      NullPointerException - 如果指定的元素为null

    • poll

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

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

    • peek

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

    • comparator

      public Comparator<? super E> comparator()
      返回用于对此队列中的元素进行排序的比较器，如果此队列使用其元素的自然排序，则返回null。
      返回值:
      用于对此队列中的元素进行排序的比较器，如果此队列使用其元素的自然排序，则返回null

    • size

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

    • remainingCapacity

      public int remainingCapacity()
      始终返回Integer.MAX_VALUE，因为PriorityBlockingQueue没有容量限制。
      指定者:
      remainingCapacity 在接口 BlockingQueue<E>中指定
      返回值:
      总是返回Integer.MAX_VALUE

    • 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 如果此队列包含指定的元素

    • drainTo

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

    • drainTo

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

    • clear

      public void clear()
      原子性地移除此队列中的所有元素。此调用返回后，队列将为空。
      指定由:
      clear 在接口 Collection<E>
      覆盖:
      clear 在类 AbstractQueue<E>

    • 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不以任何特定顺序遍历元素（不报告ORDERED特征）。

      返回的Spliterator是弱一致的。

      Spliterator报告Spliterator.SIZED和Spliterator.NONNULL。

      指定由:
      spliterator 在接口 Collection<E>中
      指定由:
      spliterator 在接口 Iterable<E>中
      实现注意:
      Spliterator另外报告Spliterator.SUBSIZED。
      返回:
      包含此队列中元素的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
      参见:

    • forEach

      public void forEach(Consumer<? super E> action)
      从接口复制的描述: Iterable
      对Iterable的每个元素执行给定操作，直到所有元素都已处理或操作引发异常。如果指定了迭代顺序，则按照迭代顺序执行操作。操作引发的异常将传递给调用者。

      如果操作执行会修改元素的底层源并具有副作用，则此方法的行为是未指定的，除非覆盖类已指定并发修改策略。

      指定由:
      forEach 在接口 Iterable<E>中
      参数:
      action - 要对每个元素执行的操作
      抛出:
      NullPointerException - 如果指定的操作为null