ArrayBlockingQueue

public class ArrayBlockingQueue

基本介紹

• 中文名：有界阻塞佇列
• 外文名：ArrayBlockingQueue

簡介

JAVAjava.util.concurrent

類 ArrayBlockingQueue<E>

java.lang.Object

java.util.AbstractCollection<E>

java.util.AbstractQueue<E>

java.util.concurrent.ArrayBlockingQueue<E>

類型參數

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

所有已實現的接口：

java. io.Serializable, Iterable<E>, Collection<E>, BlockingQueue<E>, Queue<E>

--------------------------------------------------------------------------------

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

此類支持對等待的生產者執行緒和使用者執行緒進行排序的可選公平策略。默認情況下，不保證是這種排序。然而，通過將公平性 (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 疊代器的遍歷順序添加元素。

方法摘要

void clear()

自動移除此佇列中的所有元素。

boolean contains(Object o)

如果此 collection 包含指定的元素，則返回 true。

int drainTo(Collection<? super E> c)

移除此佇列中所有可用的元素，並將它們添加到給定 collection 中。

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

最多從此佇列中移除給定數量的可用元素，並將這些元素添加到給定 collection 中。

Iterator<E> iterator()

返回在此佇列中的元素上以正確順序進行疊代的疊代器。

boolean offer(E o)

將指定的元素插入到此佇列的尾部（如果可能），如果此佇列已滿，則立即返回。

boolean offer(E o, long timeout, TimeUnit unit)

將指定的元素插入到此佇列的尾部，如果沒有可用空間，將等待指定的等待時間（如果有必要）。

E peek()

檢索，但是不移除此佇列的頭，如果此佇列為空，則返回 null。

E poll()

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

E poll(long timeout, TimeUnit unit)

檢索並移除此佇列的頭部，如果此佇列中沒有任何元素，則等待指定等待的時間（如果有必要）。

void put(E o)

將指定的元素添加到此佇列的尾部，如果必要，將等待可用的空間。

int remainingCapacity()

返回在無阻塞的理想情況下（不存在記憶體或資源約束）此佇列能接受的元素數量。

boolean remove(Object o)

從此佇列中移除指定元素的一個實例（如果存在）。

int size()

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

E take()

檢索並移除此佇列的頭部，如果此佇列不存在任何元素，則一直等待。

Object[] toArray()

返回包含此 collection 中所有元素的數組。

<T> T[]

toArray(T[] a)

返回包含此 collection 中所有元素的數組；返回數組的運行時類型是指定數組的類型。

String toString()

返回此 collection 的字元串表示形式。

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

add, 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.concurrent.BlockingQueue 繼承的方法

add

從接口 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 - 如果 c 或其中任何元素為 null

方法詳細信息

offer

public boolean offer(E o)將指定的元素插入到此佇列的尾部（如果可能），如果此佇列已滿，則立即返回。

指定者：

接口 BlockingQueue<E> 中的 offer

指定者：

接口 Queue<E> 中的 offer

參數：

o - 要添加的元素。

返回：

如果可以將元素添加到此佇列中，則返回 true，其他情況則返回 false

拋出：

NullPointerException - 如果指定的元素為 null

--------------------------------------------------------------------------------

offer

public boolean offer(E o,

long timeout,

TimeUnit unit)

throws InterruptedException將指定的元素插入到此佇列的尾部，如果沒有可用空間，將等待指定的等待時間（如果有必要）。

指定者：

接口 BlockingQueue<E> 中的 offer

參數：

o - 要添加的元素

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

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

返回：

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

拋出：

InterruptedException - 如果在等待時被中斷。

NullPointerException - 如果指定的元素為 null。

--------------------------------------------------------------------------------

poll

public E poll()從接口 Queue 複製的描述

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

指定者：

接口 Queue<E> 中的 poll

返回：

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

--------------------------------------------------------------------------------

poll

public E poll(long timeout,

TimeUnit unit)

throws InterruptedException從接口 BlockingQueue 複製的描述

檢索並移除此佇列的頭部，如果此佇列中沒有任何元素，則等待指定等待的時間（如果有必要）。

指定者：

接口 BlockingQueue<E> 中的 poll

參數：

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

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

返回：

此佇列的頭部；如果在元素出現前超過了指定的等待時間，則返回 null。

拋出：

InterruptedException - 如果在等待時被中斷。

--------------------------------------------------------------------------------

remove

public boolean remove(Object o)從此佇列中移除指定元素的一個實例（如果存在）。

指定者：

接口 Collection<E> 中的 remove

覆蓋：

類 AbstractCollection<E> 中的 remove

參數：

o - 要從此 collection 中移除的元素（如果存在）。

返回：

如果該 collection 包含指定的元素,則返回 true。

--------------------------------------------------------------------------------

peek

public E peek()從接口 Queue 複製的描述

檢索，但是不移除此佇列的頭，如果此佇列為空，則返回 null。

指定者：

接口 Queue<E> 中的 peek

返回：

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

--------------------------------------------------------------------------------

take

public E take()

throws InterruptedException從接口 BlockingQueue 複製的描述

檢索並移除此佇列的頭部，如果此佇列不存在任何元素，則一直等待。

指定者：

接口 BlockingQueue<E> 中的 take

返回：

此佇列的頭部

拋出：

InterruptedException - 如果在等待時被中斷。

--------------------------------------------------------------------------------

put

public void put(E o)

throws InterruptedException將指定的元素添加到此佇列的尾部，如果必要，將等待可用的空間。

指定者：

接口 BlockingQueue<E> 中的 put

參數：

o - 要添加的元素

拋出：

InterruptedException - 如果在等待時被中斷。

NullPointerException - 如果指定的元素為 null。

--------------------------------------------------------------------------------

size

public int size()返回此佇列中元素的數量。

指定者：

接口 Collection<E> 中的 size

指定者：

類 AbstractCollection<E> 中的 size

返回：

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

--------------------------------------------------------------------------------

remainingCapacity

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

注意，不能 總是通過檢查 remainingCapacity 來判斷嘗試 add 元素能否成功，因為可能出現這樣的情況：一個等待中的使用者已經準備好從其他已滿的佇列中 take 一個元素。

指定者：

接口 BlockingQueue<E> 中的 remainingCapacity

返回：

剩餘容量

--------------------------------------------------------------------------------

contains

public boolean contains(Object o)從類 AbstractCollection 複製的描述

如果此 collection 包含指定的元素，則返回 true。更正式地說，若且唯若此 collection 至少包含一個滿足以下條件的元素 e 時才返回 true：(o==null ? e==null : o.equals(e))。

此實現疊代該 collection 中的元素，並依次檢查每個元素以確定其是否與指定的元素相等。

指定者：

接口 Collection<E> 中的 contains

覆蓋：

類 AbstractCollection<E> 中的 contains

參數：

o - 要檢查的對象，以確定其是否包含在此 collection 中。

返回：

如果此 collection 包含指定的元素，則返回 true。

--------------------------------------------------------------------------------

toArray

public Object[] toArray()從類 AbstractCollection 複製的描述

返回包含此 collection 中所有元素的數組。如果此 collection 保證其疊代器按順序返回其元素，那么此方法也必須按相同的順序返回這些元素。返回的數組將是“安全的”，因為此 collection 並不維護對返回數組的任何引用。（換句話說，即使 collection 受到數組的支持，此方法也必須分配一個新的數組）。因此，調用方可以隨意修改返回的數組。

此實現會分配返回的數組，并迭代 collection 中的元素，將每個對象引用存儲在數組的下一個連續元素中，並從元素 0 開始。

指定者：

接口 Collection<E> 中的 toArray

覆蓋：

類 AbstractCollection<E> 中的 toArray

返回：

包含此 collection 中所有元素的數組。

--------------------------------------------------------------------------------

toArray

public <T> T[] toArray(T[] a)從類 AbstractCollection 複製的描述

返回包含此 collection 中所有元素的數組；返回數組的運行時類型是指定數組的類型。如果指定的數組能容納該 collection，則在此數組中返回 collection 的元素。否則，將根據指定數組的運行時類型和此 collection 的大小分配一個新數組。

如果指定的數組能容納 collection，並且有剩餘的空間（即數組的元素比 collection 多），那么會將緊挨著 collection 尾部的元素設定為 null（這對確定 collection 的長度很有用，但只有 在調用方知道 collection 不包含任何 null 元素時才可行）。

如果此 collection 保證其疊代器按順序返回其元素，那么此方法也必須按相同的順序返回這些元素。

此實現會檢查該數組是否足夠大，以包含該 collection 中的元素；如果不能包含，則將分配一個具有適當大小和類型的新數組（使用反射）。然後，在該 collection 上進行疊代，將每個對象引用存儲在數組的下一個連續元素中，並從元素 0 開始。如果該數組比該 collection 大，則在該 collection 尾部後面的第一個位置存儲 null。

指定者：

接口 Collection<E> 中的 toArray

覆蓋：

類 AbstractCollection<E> 中的 toArray

參數：

a - 存儲此 collection 的元素的數組（如果其足夠大）；否則，將為此分配一個具有相同運行時類型的新數組。

返回：

包含此 collection 的元素的數組。

--------------------------------------------------------------------------------

toString

public String toString()從類 AbstractCollection 複製的描述

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

此實現會創建一個空字元串緩衝區，追加一個左方括弧，然後在 collection 上進行疊代，依次追加每個元素的字元串表示形式。每追加一個元素後（最後一個元素除外），將追加字元串 ", "。最後，追加一個右括弧。從字元串緩衝區獲取一個字元串並返回它。

覆蓋：

類 AbstractCollection<E> 中的 toString

返回：

此 collection 的字元串表示形式。

--------------------------------------------------------------------------------

clear

public void clear()自動移除此佇列中的所有元素。在此調用返回之後，佇列將為空。

指定者：

接口 Collection<E> 中的 clear

覆蓋：

類 AbstractQueue<E> 中的 clear

--------------------------------------------------------------------------------

drainTo

public int drainTo(Collection<? super E> c)從接口 BlockingQueue 複製的描述

移除此佇列中所有可用的元素，並將它們添加到給定 collection 中。此操作可能比反覆輪詢此佇列更有效。在試圖向 c 集合中 add 元素沒有成功時，可能導致在拋出相關異常時，元素會同時在兩個 collection 中出現，或者在其中一個 collection 中出現，也可能在兩個 collection 中都不出現。如果試圖將一個佇列放入自身佇列中，則會導致 IllegalArgumentException 異常。此外，如果正在進行此操作時修改指定的 collection，則此操作行為是不確定的。

指定者：

接口 BlockingQueue<E> 中的 drainTo

參數：

c - 接收傳輸元素的 collection

返回：

傳輸元素的數量。

--------------------------------------------------------------------------------

drainTo

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

int maxElements)從接口 BlockingQueue 複製的描述

最多從此佇列中移除給定數量的可用元素，並將這些元素添加到給定 collection 中。在試圖向 c 集合中 add 元素沒有成功時，可能導致在拋出相關異常時，元素會同時在兩個 collection 中出現，或者在其中一個 collection 中出現，也可能在兩個 collection 中都不出現。如果試圖將一個佇列放入自身佇列中，則會導致 IllegalArgumentException 異常。此外，如果正在進行此操作時修改指定的 collection，則此操作行為是不確定的。

指定者：

接口 BlockingQueue<E> 中的 drainTo

參數：

c - 接收傳輸元素的 collection

maxElements - 傳輸元素的最大數量

返回：

傳輸元素的數量。

--------------------------------------------------------------------------------

iterator

public Iterator<E> iterator()返回在此佇列中的元素上以正確順序進行疊代的疊代器。返回的 Iterator 是一個“弱一致”的疊代器，從不拋出 ConcurrentModificationException，並且確保可遍歷疊代器構造時存在的元素，此外還可能（但並不保證）反映構造後的所有修改。

指定者：

接口 Iterable<E> 中的 iterator

指定者：

接口 Collection<E> 中的 iterator

指定者：

類 AbstractCollection<E> 中的 iterator

返回：

在佇列中的元素上以正確順序進行疊代的疊代器