java.util.concurrent
類別 LinkedBlockingQueue<E>

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

型別參數：

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

所有已實作的介面：

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

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

一個基於已連接節點的、範圍任意的 blocking queue。此佇列按 FIFO（先進先出）排序元素。佇列的頭部 是在佇列中時間最長的元素。佇列的尾部 是在佇列中時間最短的元素。新元素插入到佇列的尾部，並且佇列獲取操作會獲得位於佇列頭部的元素。連接佇列的吞吐量通常要高於基於陣列的佇列，但是在大多數共時應用程序中，其可預知的性能要低。

可選的容量範圍建構子參數作為防止佇列過度擴展的一種方法。如果未指定容量，則它等於 Integer.MAX_VALUE。除非插入節點會使佇列超出容量，否則每次插入後會動態地創建連接節點。

此類別及其迭代器實作 Collection 和 Iterator 介面的所有可選 方法。

此類別是 Java Collections Framework 的成員。

從以下版本開始：

1.5

另請參見：

序列化表格

建構子摘要

LinkedBlockingQueue()
創建一個容量為 Integer.MAX_VALUE 的 LinkedBlockingQueue。

LinkedBlockingQueue(Collection<? extends E> c)
創建一個容量是 Integer.MAX_VALUE 的 LinkedBlockingQueue，最初包含給定 collection 的元素，元素按該 collection 迭代器的遍歷順序添加。

LinkedBlockingQueue(int capacity)
創建一個具有給定（固定）容量的 LinkedBlockingQueue。

方法摘要

void	clear() 從佇列徹底移除所有元素。
int	drainTo(Collection<? super E> c) 移除此佇列中所有可用的元素，並將它們添加到給定 collection 中。
int	drainTo(Collection<? super E> c, int maxElements) 最多從此佇列中移除給定數量的可用元素，並將這些元素添加到給定 collection 中。
Iterator<E>	iterator() 返回在佇列中的元素上按適當順序進行迭代的迭代器。
boolean	offer(E e) 將指定元素插入到此佇列的尾部（如果立即可行且不會超出此佇列的容量），在成功時返回 true，如果此佇列已滿，則返回 false。
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() 返回理想情況下（沒有記憶體和資源約束）此佇列可接受並且不會被阻塞的附加元素數量。
boolean	remove(Object o) 從此佇列移除指定元素的單個實例（如果存在）。
int	size() 返回佇列中的元素個數。
E	take() 獲取並移除此佇列的頭部，在元素變得可用之前一直等待（如果有必要）。
Object[]	toArray() 返回按適當順序包含此佇列中所有元素的陣列。
<T> T[]	toArray(T[] a) 返回按適當順序包含此佇列中所有元素的陣列；返回陣列的運行時型別是指定陣列的運行時型別。
String	toString() 返回此 collection 的字元串表示形式。

從類別 java.util.AbstractQueue 繼承的方法

add, addAll, element, remove

從類別 java.util.AbstractCollection 繼承的方法

contains, containsAll, isEmpty, removeAll, retainAll

從類別 java.lang.Object 繼承的方法

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

從介面 java.util.concurrent.BlockingQueue 繼承的方法

add, contains

從介面 java.util.Queue 繼承的方法

element, remove

從介面 java.util.Collection 繼承的方法

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

建構子詳細資訊

LinkedBlockingQueue

public LinkedBlockingQueue()

創建一個容量為 Integer.MAX_VALUE 的 LinkedBlockingQueue。

LinkedBlockingQueue

public LinkedBlockingQueue(int capacity)

創建一個具有給定（固定）容量的 LinkedBlockingQueue。

參數：

capacity - 佇列的容量

拋出：

IllegalArgumentException - 如果 capacity 未大於 0

LinkedBlockingQueue

public LinkedBlockingQueue(Collection<? extends E> c)

創建一個容量是 Integer.MAX_VALUE 的 LinkedBlockingQueue，最初包含給定 collection 的元素，元素按該 collection 迭代器的遍歷順序添加。

參數：

c - 最初所包含元素所屬的 collection

拋出：

NullPointerException - 如果指定 collection 或其所有元素均為 null

方法詳細資訊

size

public int size()

返回佇列中的元素個數。

指定者：

介面 Collection<E> 中的 size

指定者：

類別 AbstractCollection<E> 中的 size

返回：

佇列中的元素個數

remainingCapacity

public int remainingCapacity()

返回理想情況下（沒有記憶體和資源約束）此佇列可接受並且不會被阻塞的附加元素數量。該數量總是等於此佇列的初始容量，小於佇列的當前 size。

注意，不能 總是通過檢查 remainingCapacity 來斷定試圖插入一個元素是否成功，因為可能是另一個執行緒將插入或移除某個元素。

指定者：

介面 BlockingQueue<E> 中的 remainingCapacity

返回：

剩餘容量

put

public void put(E e)
         throws InterruptedException

將指定元素插入到此佇列的尾部，如有必要，則等待空間變得可用。

指定者：

介面 BlockingQueue<E> 中的 put

參數：

e - 要添加的元素

拋出：

InterruptedException - 如果在等待時被中斷

NullPointerException - 如果指定元素為 null

offer

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

將指定元素插入到此佇列的尾部，如有必要，則等待指定的時間以使空間變得可用。

指定者：

介面 BlockingQueue<E> 中的 offer

參數：

e - 要添加的元素

timeout - 放棄之前等待的時間長度，以 unit 為時間單位

unit - 確定如何解釋 timeout 參數的 TimeUnit

返回：

如果成功，則返回 true；如果在空間可用前超出了指定的時間，則返回 false。

拋出：

InterruptedException - 如果在等待時被中斷

NullPointerException - 如果指定元素為 null

offer

public boolean offer(E e)

將指定元素插入到此佇列的尾部（如果立即可行且不會超出此佇列的容量），在成功時返回 true，如果此佇列已滿，則返回 false。當使用有容量限制的佇列時，此方法通常要優於 add 方法，後者可能無法插入元素，而只是拋出一個異常。

指定者：

介面 BlockingQueue<E> 中的 offer

指定者：

介面 Queue<E> 中的 offer

參數：

e - 要添加的元素

返回：

如果該元素已添加到此佇列，則返回 true；否則返回 false

拋出：

NullPointerException - 如果指定元素為 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 - 如果在等待時被中斷

poll

public E poll()

從介面 Queue 複製的描述

獲取並移除此佇列的頭，如果此佇列為空，則返回 null。

指定者：

介面 Queue<E> 中的 poll

返回：

佇列的頭，如果此佇列為空，則返回 null

peek

public E peek()

從介面 Queue 複製的描述

獲取但不移除此佇列的頭；如果此佇列為空，則返回 null。

指定者：

介面 Queue<E> 中的 peek

返回：

此佇列的頭；如果此佇列為空，則返回 null

remove

public boolean remove(Object o)

從此佇列移除指定元素的單個實例（如果存在）。更確切地講，如果此佇列包含一個或多個滿足 o.equals(e) 的元素 e， 則移除一個這樣的元素。如果此佇列包含指定元素，則返回 true（或者此佇列由於調用而發生更改，則返回 true）。

指定者：

介面 Collection<E> 中的 remove

指定者：

介面 BlockingQueue<E> 中的 remove

覆寫：

類別 AbstractCollection<E> 中的 remove

參數：

o - 要從此佇列移除的元素（如果存在）

返回：

如果此佇列由於調用而發生更改，則返回 true

toArray

public Object[] toArray()

返回按適當順序包含此佇列中所有元素的陣列。

由於此佇列不維護對返回陣列的任何參考，因而它是「安全的」。（換句話說，此方法必須分派一個新陣列）。因此，調用者可以隨意修改返回的陣列。

此方法充當基於陣列的 API 與基於 collection 的 API 之間的橋樑。

指定者：

介面 Collection<E> 中的 toArray

覆寫：

類別 AbstractCollection<E> 中的 toArray

返回：

包含此佇列中所有元素的陣列

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

toString

public String toString()

從類別 AbstractCollection 複製的描述

返回此 collection 的字元串表示形式。該字元串表示形式由 collection 元素的列表組成，這些元素按其迭代器返回的順序排列，並用方括號 ("[]") 括起來。相鄰元素由字元 ", "（逗號加空格）分隔。通過 String.valueOf(Object) 可以將元素轉換成字元串。

覆寫：

類別 AbstractCollection<E> 中的 toString

返回：

此 collection 的字元串表示形式

clear

public void clear()

從佇列徹底移除所有元素。此調用返回後佇列為空。

指定者：

介面 Collection<E> 中的 clear

覆寫：

類別 AbstractQueue<E> 中的 clear

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

iterator

public Iterator<E> iterator()

返回在佇列中的元素上按適當順序進行迭代的迭代器。返回的 Iterator 是一個“弱一致”的迭代器，從不拋出 ConcurrentModificationException，並且確保可遍歷迭代器建構後所存在的所有元素，並且可能（但並不保證）反映建構後的所有修改。

指定者：

介面 Iterable<E> 中的 iterator

指定者：

介面 Collection<E> 中的 iterator

指定者：

類別 AbstractCollection<E> 中的 iterator

返回：

按適當順序對佇列中的元素進行迭代的迭代器