java.util.concurrent
類別 ArrayBlockingQueue<E>

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

型別參數：

E - 在此 collection 中保持的元素型別

所有已實作的介面：

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

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

一個由陣列支持的有界阻塞佇列。此佇列按 FIFO（先進先出）原則對元素進行排序。佇列的頭部 是在佇列中存在時間最長的元素。佇列的尾部 是在佇列中存在時間最短的元素。新元素插入到佇列的尾部，佇列獲取操作則是從佇列頭部開始獲得元素。

這是一個典型的“有界快取記憶體區”，固定大小的陣列在其中保持生產者插入的元素和使用者提取的元素。一旦創建了這樣的快取記憶體區，就不能再增加其容量。試圖向已滿佇列中放入元素會導致操作受阻塞；試圖從空佇列中提取元素將導致類似阻塞。

此類別支持對等待的生產者執行緒和使用者執行緒進行排序的可選公平策略。預設情況下，不保證是這種排序。然而，通過將公平性 (fairness) 設置為 true 而建構的佇列允許按照 FIFO 順序存取執行緒。公平性通常會降低吞吐量，但也減少了可變性和避免了“不平衡性”。

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

此類別是 Java Collections Framework 的成員。

從以下版本開始：

1.5

另請參見：

序列化表格

建構子摘要

ArrayBlockingQueue(int capacity)
創建一個帶有給定的（固定）容量和預設存取策略的 ArrayBlockingQueue。

ArrayBlockingQueue(int capacity, boolean fair)
創建一個具有給定的（固定）容量和指定存取策略的 ArrayBlockingQueue。

ArrayBlockingQueue(int capacity, boolean fair, Collection<? extends E> c)
創建一個具有給定的（固定）容量和指定存取策略的 ArrayBlockingQueue，它最初包含給定 collection 的元素，並以 collection 迭代器的遍歷順序添加元素。

方法摘要

boolean	add(E e) 將指定的元素插入到此佇列的尾部（如果立即可行且不會超過該佇列的容量），在成功時返回 true，如果此佇列已滿，則拋出 IllegalStateException。
void	clear() 自動移除此佇列中的所有元素。
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) 將指定的元素插入到此佇列的尾部（如果立即可行且不會超過該佇列的容量），在成功時返回 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 繼承的方法

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

建構子詳細資訊

ArrayBlockingQueue

public ArrayBlockingQueue(int capacity)

創建一個帶有給定的（固定）容量和預設存取策略的 ArrayBlockingQueue。

參數：

capacity - 此佇列的容量

拋出：

IllegalArgumentException - 如果 capacity 小於 1

ArrayBlockingQueue

public ArrayBlockingQueue(int capacity,
                          boolean fair)

創建一個具有給定的（固定）容量和指定存取策略的 ArrayBlockingQueue。

參數：

capacity - 此佇列的容量

fair - 如果為 true，則按照 FIFO 順序存取插入或移除時受阻塞執行緒的佇列；如果為 false，則存取順序是不確定的。

拋出：

IllegalArgumentException - 如果 capacity 小於 1

ArrayBlockingQueue

public ArrayBlockingQueue(int capacity,
                          boolean fair,
                          Collection<? extends E> c)

創建一個具有給定的（固定）容量和指定存取策略的 ArrayBlockingQueue，它最初包含給定 collection 的元素，並以 collection 迭代器的遍歷順序添加元素。

參數：

capacity - 此佇列的容量

fair - 如果為 true，則按照 FIFO 順序存取插入或移除時受阻塞執行緒的佇列；如果為 false，則存取順序是不確定的。

c - 最初要包含的元素的 collection

拋出：

IllegalArgumentException - 如果 capacity 小於 c.size()，或者小於 1

NullPointerException - 如果指定 collection 或任何其元素為 null

方法詳細資訊

add

public boolean add(E e)

將指定的元素插入到此佇列的尾部（如果立即可行且不會超過該佇列的容量），在成功時返回 true，如果此佇列已滿，則拋出 IllegalStateException。

指定者：

介面 Collection<E> 中的 add

指定者：

介面 BlockingQueue<E> 中的 add

指定者：

介面 Queue<E> 中的 add

覆寫：

類別 AbstractQueue<E> 中的 add

參數：

e - 要添加的元素

返回：

true（根據 Collection.add(E) 的規定）

拋出：

IllegalStateException - 如果此佇列已滿

NullPointerException - 如果指定的元素為 null

offer

public boolean offer(E e)

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

指定者：

介面 BlockingQueue<E> 中的 offer

指定者：

介面 Queue<E> 中的 offer

參數：

e - 要添加的元素

返回：

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

拋出：

NullPointerException - 如果指定的元素為 null

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

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

size

public int size()

返回此佇列中元素的數量。

指定者：

介面 Collection<E> 中的 size

指定者：

類別 AbstractCollection<E> 中的 size

返回：

返回此佇列中元素的數量

remainingCapacity

public int remainingCapacity()

返回在無阻塞的理想情況下（不存在記憶體或資源約束）此佇列能接受的其他元素數量。它總是等於此佇列初始容量，但小於此佇列當前的 size。

注意，不能 總是通過檢查 remainingCapacity 來判斷嘗試插入元素能否成功，因為可能出現這樣的情況：另一個執行緒將插入或移除一個元素。

指定者：

介面 BlockingQueue<E> 中的 remainingCapacity

返回：

剩餘容量

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

返回：

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

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

返回：

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