java.util.concurrent
类 PriorityBlockingQueue<E>

java.lang.Object
  java.util.AbstractCollection<E>
      java.util.AbstractQueue<E>
          java.util.concurrent.PriorityBlockingQueue<E>

类型参数：

E - 此 collection 中所保存元素的类型

所有已实现的接口：

Serializable, Iterable<E>, Collection<E>, BlockingQueue<E>, Queue<E>

public class PriorityBlockingQueue<E>
extends AbstractQueue<E>
implements BlockingQueue<E>, Serializable

一个无界阻塞队列，它使用与类 PriorityQueue 相同的顺序规则，并且提供了阻塞获取操作。虽然此队列逻辑上是无界的，但是资源被耗尽时试图执行 add 操作也将失败（导致 OutOfMemoryError）。此类不允许使用 null 元素。依赖自然顺序的优先级队列也不允许插入不可比较的对象（这样做会导致抛出 ClassCastException）。

此类及其迭代器可以实现 Collection 和 Iterator 接口的所有可选 方法。iterator() 方法中提供的迭代器并不 保证以特定的顺序遍历 PriorityBlockingQueue 的元素。如果需要有序地进行遍历，则应考虑使用 Arrays.sort(pq.toArray())。此外，可以使用方法 drainTo 按优先级顺序移除 全部或部分元素，并将它们放在另一个 collection 中。

在此类上进行的操作不保证具有同等优先级的元素的顺序。如果需要实施某一排序，那么可以定义自定义类或者比较器，比较器可使用修改键断开主优先级值之间的联系。例如，以下是应用先进先出 (first-in-first-out) 规则断开可比较元素之间联系的一个类。要使用该类，则需要插入一个新的 FIFOEntry(anEntry) 来替换普通的条目对象。

 class FIFOEntry<E extends Comparable<? super E>>
     implements Comparable<FIFOEntry<E>> {
   final static 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 Collections Framework 的成员。

从以下版本开始：

1.5

另请参见：

序列化表格

构造方法摘要

PriorityBlockingQueue()
用默认的初始容量 (11) 创建一个 PriorityBlockingQueue，并根据元素的自然顺序对其元素进行排序。

PriorityBlockingQueue(Collection<? extends E> c)
创建一个包含指定 collection 元素的 PriorityBlockingQueue。

PriorityBlockingQueue(int initialCapacity)
使用指定的初始容量创建一个 PriorityBlockingQueue，并根据元素的自然顺序对其元素进行排序。

PriorityBlockingQueue(int initialCapacity, Comparator<? super E> comparator)
使用指定的初始容量创建一个 PriorityBlockingQueue，并根据指定的比较器对其元素进行排序。

方法摘要

boolean	add(E e) 将指定元素插入此优先级队列。
void	clear() 完全移除此队列中的所有元素。
Comparator<? super E>	comparator() 返回用于对此队列元素进行排序的比较器；如果此队列使用其元素的自然顺序，则返回 null。
boolean	contains(Object o) 如果队列包含指定的元素，则返回 true。
int	drainTo(Collection<? super E> c) 移除此队列中所有可用的元素，并将它们添加到给定 collection 中。
int	drainTo(Collection<? super E> c, int maxElements) 最多从此队列中移除给定数量的可用元素，并将这些元素添加到给定 collection 中。
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) 从队列中移除指定元素的单个实例（如果存在）。
int	size() 返回此 collection 中的元素数。
E	take() 获取并移除此队列的头部，在元素变得可用之前一直等待（如果有必要）。
Object[]	toArray() 返回包含此队列所有元素的数组。
<T> T[]	toArray(T[] a) 返回一个包含此队列所有元素的数组；返回数组的运行时类型是指定数组的类型。
String	toString() 返回此 collection 的字符串表示形式。

从类 java.util.AbstractQueue 继承的方法

addAll, element, remove

从类 java.util.AbstractCollection 继承的方法

containsAll, isEmpty, removeAll, retainAll

从类 java.lang.Object 继承的方法

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

从接口 java.util.Queue 继承的方法

element, remove

从接口 java.util.Collection 继承的方法

addAll, containsAll, equals, hashCode, isEmpty, removeAll, retainAll

构造方法详细信息

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)

创建一个包含指定 collection 元素的 PriorityBlockingQueue。如果指定 collection 是一个 SortedSet 或 PriorityQueue，则此优先级队列将按照相同顺序进行排序。否则，此优先级队列将根据此元素的自然顺序进行排序。

参数：

c - 其元素将被放置在此优先级队列中的 collection

抛出：

ClassCastException - 如果根据优先级队列的顺序，指定 collection 的元素无法与另一个 collection 的元素进行比较

NullPointerException - 如果指定 collection 或其任意元素为 null

方法详细信息

add

public boolean add(E e)

将指定元素插入此优先级队列。

指定者：

接口 Collection<E> 中的 add

指定者：

接口 BlockingQueue<E> 中的 add

指定者：

接口 Queue<E> 中的 add

覆盖：

类 AbstractQueue<E> 中的 add

参数：

o - 要添加的元素

返回：

true（根据 Collection.add(E) 的规定）

抛出：

ClassCastException - 如果根据优先级队列的排序规则，无法将指定的元素与优先级队列中当前的元素进行比较

NullPointerException - 如果指定元素为 null

offer

public boolean offer(E e)

将指定元素插入此优先级队列。

指定者：

接口 BlockingQueue<E> 中的 offer

指定者：

接口 Queue<E> 中的 offer

参数：

e - 将添加的元素

返回：

true（根据 Queue.offer(E) 的规定）

抛出：

ClassCastException - 如果根据优先级队列的排序规则无法将指定元素与优先级队列中当前的元素进行比较

NullPointerException - 如果指定元素为 null

put

public void put(E e)

将指定元素插入此优先级队列。该队列是无界的，所以此方法不会阻塞。

指定者：

接口 BlockingQueue<E> 中的 put

参数：

e - 要添加的元素

抛出：

ClassCastException - 如果根据优先级队列的排序规则无法将指定元素与优先级队列中当前的元素进行比较

NullPointerException - 如果指定元素为 null

offer

public boolean offer(E e,
                     long timeout,
                     TimeUnit unit)

将指定元素插入此优先级队列。该队列是无界的，所以此方法不会阻塞。

指定者：

接口 BlockingQueue<E> 中的 offer

参数：

e - 要添加的元素

timeout - 忽略此参数，因为此方法不会阻塞

unit - 忽略此参数，因为此方法不会阻塞

返回：

true

抛出：

ClassCastException - 如果根据优先级队列的排序规则无法将指定元素与优先级队列中当前的元素进行比较

NullPointerException - 如果指定元素为 null

poll

public E poll()

从接口 Queue 复制的描述

获取并移除此队列的头，如果此队列为空，则返回 null。

指定者：

接口 Queue<E> 中的 poll

返回：

队列的头，如果此队列为空，则返回 null

take

public E take()
       throws InterruptedException

从接口 BlockingQueue 复制的描述

获取并移除此队列的头部，在元素变得可用之前一直等待（如果有必要）。

指定者：

接口 BlockingQueue<E> 中的 take

返回：

此队列的头部

抛出：

InterruptedException - 如果在等待时被中断

poll

public E poll(long timeout,
              TimeUnit unit)
       throws InterruptedException

从接口 BlockingQueue 复制的描述

获取并移除此队列的头部，在指定的等待时间前等待可用的元素（如果有必要）。

指定者：

接口 BlockingQueue<E> 中的 poll

参数：

timeout - 放弃之前要等待的时间长度，用 unit 的时间单位表示

unit - 确定如何解释 timeout 参数的 TimeUnit

返回：

此队列的头部；如果在元素可用前超过了指定的等待时间，则返回 null

抛出：

InterruptedException - 如果在等待时被中断

peek

public E peek()

从接口 Queue 复制的描述

获取但不移除此队列的头；如果此队列为空，则返回 null。

指定者：

接口 Queue<E> 中的 peek

返回：

此队列的头；如果此队列为空，则返回 null

comparator

public Comparator<? super E> comparator()

返回用于对此队列元素进行排序的比较器；如果此队列使用其元素的自然顺序，则返回 null。

返回：

用于对此队列元素进行排序的比较器；如果此队列使用其元素的自然顺序，则返回 null

size

public int size()

从接口 Collection 复制的描述

返回此 collection 中的元素数。如果此 collection 包含的元素大于 Integer.MAX_VALUE，则返回 Integer.MAX_VALUE。

指定者：

接口 Collection<E> 中的 size

指定者：

类 AbstractCollection<E> 中的 size

返回：

此 collection 中的元素数

remainingCapacity

public int remainingCapacity()

总是返回 Integer.MAX_VALUE，因为 PriorityBlockingQueue 没有容量限制。

指定者：

接口 BlockingQueue<E> 中的 remainingCapacity

返回：

Integer.MAX_VALUE

remove

public boolean remove(Object o)

从队列中移除指定元素的单个实例（如果存在）。更确切地讲，如果此队列包含一个或多个满足 o.equals(e) 的元素 e，则移除一个这样的元素。当且仅当此队列包含指定的元素（或者此队列由于调用而发生更改）时，返回 true。

指定者：

接口 Collection<E> 中的 remove

指定者：

接口 BlockingQueue<E> 中的 remove

覆盖：

类 AbstractCollection<E> 中的 remove

参数：

o - 将从此队列中移除的元素（如果存在）

返回：

如果此队列由于调用而发生更改，则返回 true

contains

public boolean contains(Object o)

如果队列包含指定的元素，则返回 true。更确切地讲，当且仅当此队列至少包含一个满足 o.equals(e) 的元素 e 时，返回 true。

指定者：

接口 Collection<E> 中的 contains

指定者：

接口 BlockingQueue<E> 中的 contains

覆盖：

类 AbstractCollection<E> 中的 contains

参数：

o - 要检查是否包含于此队列的对象

返回：

如果此队列包含指定元素，则返回 true

toArray

public Object[] toArray()

返回包含此队列所有元素的数组。所返回数组的元素没有特定的顺序。

由于此队列并不维护对返回数组的任何引用，因而它将是“安全的”。（换句话说，此方法必须分配一个新数组）。因此，调用者可以随意修改返回的数组。

此方法充当基于数组的 API 与基于 collection 的 API 之间的桥梁。

指定者：

接口 Collection<E> 中的 toArray

覆盖：

类 AbstractCollection<E> 中的 toArray

返回：

包含此队列所有元素的数组

toString

public String toString()

从类 AbstractCollection 复制的描述

返回此 collection 的字符串表示形式。该字符串表示形式由 collection 元素的列表组成，这些元素按其迭代器返回的顺序排列，并用方括号 ("[]") 括起来。相邻元素由字符 ", "（逗号加空格）分隔。通过 String.valueOf(Object) 可以将元素转换成字符串。

覆盖：

类 AbstractCollection<E> 中的 toString

返回：

此 collection 的字符串表示形式

drainTo

public int drainTo(Collection<? super E> c)

从接口 BlockingQueue 复制的描述

移除此队列中所有可用的元素，并将它们添加到给定 collection 中。此操作可能比反复轮询此队列更有效。在试图向 collection c 中添加元素没有成功时，可能导致在抛出相关异常时，元素会同时在两个 collection 中出现，或者在其中一个 collection 中出现，也可能在两个 collection 中都不出现。如果试图将一个队列放入自身队列中，则会导致 IllegalArgumentException 异常。此外，如果正在进行此操作时修改指定的 collection，则此操作行为是不确定的。

指定者：

接口 BlockingQueue<E> 中的 drainTo

参数：

c - 接收传输元素的 collection

返回：

传输元素的数量

抛出：

UnsupportedOperationException - 如果指定 collection 不支持添加元素

ClassCastException - 如果此队列元素的类不允许将其添加到指定 collection

NullPointerException - 如果指定 collection 为 null

IllegalArgumentException - 如果指定 collection 是此队列，或者此队列元素的某些属性不允许将其添加到指定 collection

drainTo

public int drainTo(Collection<? super E> c,
                   int maxElements)

从接口 BlockingQueue 复制的描述

最多从此队列中移除给定数量的可用元素，并将这些元素添加到给定 collection 中。在试图向 collection c 中添加元素没有成功时，可能导致在抛出相关异常时，元素会同时在两个 collection 中出现，或者在其中一个 collection 中出现，也可能在两个 collection 中都不出现。如果试图将一个队列放入自身队列中，则会导致 IllegalArgumentException 异常。此外，如果正在进行此操作时修改指定的 collection，则此操作行为是不确定的。

指定者：

接口 BlockingQueue<E> 中的 drainTo

参数：

c - 接收传输元素的 collection

maxElements - 传输元素的最大数量

返回：

传输元素的数量

抛出：

UnsupportedOperationException - 如果指定 collection 不支持添加元素

ClassCastException - 如果此队列元素的类不允许将其添加到指定 collection

NullPointerException - 如果指定 collection 为 null

IllegalArgumentException - 如果指定 collection 是此队列，或者此队列元素的某些属性不允许将其添加到指定 collection

clear

public void clear()

完全移除此队列中的所有元素。此调用返回后，队列将为空。

指定者：

接口 Collection<E> 中的 clear

覆盖：

类 AbstractQueue<E> 中的 clear

toArray

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

返回一个包含此队列所有元素的数组；返回数组的运行时类型是指定数组的类型。所返回数组的元素没有特定的顺序。如果指定的数组能容纳队列，则将该队列返回此处。否则，将分配一个具有指定数组的运行时类型和此队列大小的新数组。

如果指定的数组能容纳队列，并有剩余的空间（即数组的元素比队列多），那么会将紧接队列尾部的元素设置为 null。

像 toArray() 方法一样，此方法充当基于数组 的 API 与基于 collection 的 API 之间的桥梁。更进一步说，此方法允许对输出数组的运行时类型进行精确控制，在某些情况下，可以用来节省分配开销。

假定 x 是只包含字符串的一个已知队列。以下代码用来将该队列转储到一个新分配的 String 数组：

     String[] y = x.toArray(new String[0]);

注意，toArray(new Object[0]) 和 toArray() 在功能上是相同的。

指定者：

接口 Collection<E> 中的 toArray

覆盖：

类 AbstractCollection<E> 中的 toArray

参数：

a - 用来存储队列元素的数组（如果该数组足够大）；否则为此分配一个具有相同运行时类型的新数组

返回：

包含此队列所有元素的数组

抛出：

ArrayStoreException - 如果指定数组的运行时类型不是此队列每个元素的运行时类型的超类型

NullPointerException - 如果指定数组为 null

iterator

public Iterator<E> iterator()

返回在此队列元素上进行迭代的迭代器。迭代器不以任何特定的顺序返回元素。返回的 Iterator 是一个“弱一致”迭代器，不会抛出 ConcurrentModificationException，并且可确保遍历迭代器构造后存在的所有元素，并且可能（但并不保证）反映构造后的所有修改。

指定者：

接口 Iterable<E> 中的 iterator

指定者：

接口 Collection<E> 中的 iterator

指定者：

类 AbstractCollection<E> 中的 iterator

返回：

在此队列元素上进行迭代的迭代器