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

返回：

在此佇列元素上進行迭代的迭代器