java.util.concurrent
類別 SynchronousQueue<E>

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

型別參數：

E - 此 collection 保持的元素型別

所有已實作的介面：

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

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

一種阻塞佇列，其中每個插入操作必須等待另一個執行緒的對應移除操作 ，反之亦然。同步佇列沒有任何內部容量，甚至連一個佇列的容量都沒有。不能在同步佇列上進行 peek，因為僅在試圖要移除元素時，該元素才存在；除非另一個執行緒試圖移除某個元素，否則也不能（使用任何方法）插入元素；也不能迭代佇列，因為其中沒有元素可用於迭代。佇列的頭 是嘗試添加到佇列中的首個已排隊插入執行緒的元素；如果沒有這樣的已排隊執行緒，則沒有可用於移除的元素並且 poll() 將會返回 null。對於其他 Collection 方法（例如 contains），SynchronousQueue 作為一個空 collection。此佇列不允許 null 元素。

同步佇列類似於 CSP 和 Ada 中使用的 rendezvous 通道。它非常適合於傳遞性設計，在這種設計中，在一個執行緒中運行的物件要將某些資訊、事件或任務傳遞給在另一個執行緒中運行的物件，它就必須與該物件同步。

對於正在等待的生產者和使用者執行緒而言，此類別支持可選的公平排序策略。預設情況下不保證這種排序。但是，使用公平設置為 true 所建構的佇列可保證執行緒以 FIFO 的順序進行存取。

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

此類別是 Java Collections Framework 的成員。

從以下版本開始：

1.5

另請參見：

序列化表格

建構子摘要

SynchronousQueue()
創建一個具有非公平存取策略的 SynchronousQueue。

SynchronousQueue(boolean fair)
創建一個具有指定公平策略的 SynchronousQueue。

方法摘要

void	clear() 不執行任何操作。
boolean	contains(Object o) 始終返回 false。
boolean	containsAll(Collection<?> c) 除非給定 collection 為空，否則返回 false。
int	drainTo(Collection<? super E> c) 移除此佇列中所有可用的元素，並將它們添加到給定 collection 中。
int	drainTo(Collection<? super E> c, int maxElements) 最多從此佇列中移除給定數量的可用元素，並將這些元素添加到給定 collection 中。
boolean	isEmpty() 始終返回 true。
Iterator<E>	iterator() 返回一個空迭代器，其中 hasNext 始終返回 false。
boolean	offer(E e) 如果另一個執行緒正在等待以便接收指定元素，則將指定元素插入到此佇列。
boolean	offer(E o, long timeout, TimeUnit unit) 將指定元素插入到此佇列，如有必要則等待指定的時間，以便另一個執行緒接收它。
E	peek() 始終返回 null。
E	poll() 如果另一個執行緒當前正要使用某個元素，則獲取並移除此佇列的頭。
E	poll(long timeout, TimeUnit unit) 獲取並移除此佇列的頭，如有必要則等待指定的時間，以便另一個執行緒插入它。
void	put(E o) 將指定元素添加到此佇列，如有必要則等待另一個執行緒接收它。
int	remainingCapacity() 始終返回 0。
boolean	remove(Object o) 始終返回 false。
boolean	removeAll(Collection<?> c) 始終返回 false。
boolean	retainAll(Collection<?> c) 始終返回 false。
int	size() 始終返回 0。
E	take() 獲取並移除此佇列的頭，如有必要則等待另一個執行緒插入它。
Object[]	toArray() 返回一個 0 長度的陣列。
<T> T[]	toArray(T[] a) 將指定陣列的第 0 個元素設置為 null（如果該陣列有非 0 的長度）並返回它。

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

add, addAll, element, remove

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

toString

從類別 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, equals, hashCode

建構子詳細資訊

SynchronousQueue

public SynchronousQueue()

創建一個具有非公平存取策略的 SynchronousQueue。

SynchronousQueue

public SynchronousQueue(boolean fair)

創建一個具有指定公平策略的 SynchronousQueue。

參數：

fair - 如果為 true，則等待執行緒以 FIFO 的順序競爭存取；否則順序是未指定的。

方法詳細資訊

put

public void put(E o)
         throws InterruptedException

將指定元素添加到此佇列，如有必要則等待另一個執行緒接收它。

指定者：

介面 BlockingQueue<E> 中的 put

參數：

o - 要添加的元素

拋出：

InterruptedException - 如果在等待時被中斷

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

offer

public boolean offer(E e)

如果另一個執行緒正在等待以便接收指定元素，則將指定元素插入到此佇列。

指定者：

介面 BlockingQueue<E> 中的 offer

指定者：

介面 Queue<E> 中的 offer

參數：

e - 要添加的元素

返回：

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

拋出：

NullPointerException - 如果指定元素 null

take

public E take()
       throws InterruptedException

獲取並移除此佇列的頭，如有必要則等待另一個執行緒插入它。

指定者：

介面 BlockingQueue<E> 中的 take

返回：

佇列的頭

拋出：

InterruptedException - 如果在等待時被中斷

poll

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

獲取並移除此佇列的頭，如有必要則等待指定的時間，以便另一個執行緒插入它。

指定者：

介面 BlockingQueue<E> 中的 poll

參數：

timeout - 放棄之前要等待的時間長度，用 unit 的時間單位表示

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

返回：

佇列的頭，如果該元素出現前已超出指定的等待時間，則返回 null。

拋出：

InterruptedException - 如果在等待時被中斷

poll

public E poll()

如果另一個執行緒當前正要使用某個元素，則獲取並移除此佇列的頭。

指定者：

介面 Queue<E> 中的 poll

返回：

佇列的頭，如果沒有元素可用，則返回 null。

isEmpty

public boolean isEmpty()

始終返回 true。SynchronousQueue 沒有內部容量。

指定者：

介面 Collection<E> 中的 isEmpty

覆寫：

類別 AbstractCollection<E> 中的 isEmpty

返回：

true

size

public int size()

始終返回 0。SynchronousQueue 沒有內部容量。

指定者：

介面 Collection<E> 中的 size

指定者：

類別 AbstractCollection<E> 中的 size

返回：

0。

remainingCapacity

public int remainingCapacity()

始終返回 0。SynchronousQueue 沒有內部容量。

指定者：

介面 BlockingQueue<E> 中的 remainingCapacity

返回：

0。

clear

public void clear()

不執行任何操作。SynchronousQueue 沒有內部容量。

指定者：

介面 Collection<E> 中的 clear

覆寫：

類別 AbstractQueue<E> 中的 clear

contains

public boolean contains(Object o)

始終返回 false。SynchronousQueue 沒有內部容量。

指定者：

介面 Collection<E> 中的 contains

指定者：

介面 BlockingQueue<E> 中的 contains

覆寫：

類別 AbstractCollection<E> 中的 contains

參數：

o - 元素

返回：

false

remove

public boolean remove(Object o)

始終返回 false。SynchronousQueue 沒有內部容量。

指定者：

介面 Collection<E> 中的 remove

指定者：

介面 BlockingQueue<E> 中的 remove

覆寫：

類別 AbstractCollection<E> 中的 remove

參數：

o - 要移除的元素

返回：

false

containsAll

public boolean containsAll(Collection<?> c)

除非給定 collection 為空，否則返回 false。SynchronousQueue 沒有內部容量。

指定者：

介面 Collection<E> 中的 containsAll

覆寫：

類別 AbstractCollection<E> 中的 containsAll

參數：

c - collection

返回：

除非給定 collection 為空，否則返回 false

另請參見：

AbstractCollection.contains(Object)

removeAll

public boolean removeAll(Collection<?> c)

始終返回 false。SynchronousQueue 沒有內部容量。

指定者：

介面 Collection<E> 中的 removeAll

覆寫：

類別 AbstractCollection<E> 中的 removeAll

參數：

c - collection

返回：

false

另請參見：

AbstractCollection.remove(Object), AbstractCollection.contains(Object)

retainAll

public boolean retainAll(Collection<?> c)

始終返回 false。SynchronousQueue 沒有內部容量。

指定者：

介面 Collection<E> 中的 retainAll

覆寫：

類別 AbstractCollection<E> 中的 retainAll

參數：

c - collection

返回：

false

另請參見：

AbstractCollection.remove(Object), AbstractCollection.contains(Object)

peek

public E peek()

始終返回 null。除非 SynchronousQueue 正在等待，否則不返回元素。

指定者：

介面 Queue<E> 中的 peek

返回：

null

iterator

public Iterator<E> iterator()

返回一個空迭代器，其中 hasNext 始終返回 false。

指定者：

介面 Iterable<E> 中的 iterator

指定者：

介面 Collection<E> 中的 iterator

指定者：

類別 AbstractCollection<E> 中的 iterator

返回：

空迭代器

toArray

public Object[] toArray()

返回一個 0 長度的陣列。

指定者：

介面 Collection<E> 中的 toArray

覆寫：

類別 AbstractCollection<E> 中的 toArray

返回：

一個 0 長度的陣列

toArray

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

將指定陣列的第 0 個元素設置為 null（如果該陣列有非 0 的長度）並返回它。

指定者：

介面 Collection<E> 中的 toArray

覆寫：

類別 AbstractCollection<E> 中的 toArray

參數：

a - 陣列

返回：

指定的陣列

拋出：

NullPointerException - 如果指定的陣列為 null

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