JavaTM Platform
Standard Ed. 6

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 的顺序进行访问。

此类及其迭代器实现 CollectionIterator 接口的所有可选 方法。

此类是 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()
始终返回 trueSynchronousQueue 没有内部容量。

指定者:
接口 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)
始终返回 falseSynchronousQueue 没有内部容量。

指定者:
接口 Collection<E> 中的 contains
指定者:
接口 BlockingQueue<E> 中的 contains
覆盖:
AbstractCollection<E> 中的 contains
参数:
o - 元素
返回:
false

remove

public boolean remove(Object o)
始终返回 falseSynchronousQueue 没有内部容量。

指定者:
接口 Collection<E> 中的 remove
指定者:
接口 BlockingQueue<E> 中的 remove
覆盖:
AbstractCollection<E> 中的 remove
参数:
o - 要移除的元素
返回:
false

containsAll

public boolean containsAll(Collection<?> c)
除非给定 collection 为空,否则返回 falseSynchronousQueue 没有内部容量。

指定者:
接口 Collection<E> 中的 containsAll
覆盖:
AbstractCollection<E> 中的 containsAll
参数:
c - collection
返回:
除非给定 collection 为空,否则返回 false
另请参见:
AbstractCollection.contains(Object)

removeAll

public boolean removeAll(Collection<?> c)
始终返回 falseSynchronousQueue 没有内部容量。

指定者:
接口 Collection<E> 中的 removeAll
覆盖:
AbstractCollection<E> 中的 removeAll
参数:
c - collection
返回:
false
另请参见:
AbstractCollection.remove(Object), AbstractCollection.contains(Object)

retainAll

public boolean retainAll(Collection<?> c)
始终返回 falseSynchronousQueue 没有内部容量。

指定者:
接口 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

JavaTM Platform
Standard Ed. 6

提交错误或意见
有关更多的 API 参考资料和开发人员文档,请参阅 Java SE 开发人员文档。该文档包含更详细的、面向开发人员的描述,以及总体概述、术语定义、使用技巧和工作代码示例。

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策