E
- 此集合中保存的元素的类型
public interface BlockingQueue<E> extends Queue<E>
Queue
另外支持在检索元素时等待队列变为非空的操作,并且在存储元素时等待队列中的空间变得可用。
BlockingQueue
方法有四种形式,具有不同的操作方式,不能立即满足,但可能在将来的某个时间点满足:一个抛出异常,第二个返回一个特殊值( null
或false
,具体取决于操作),第三个程序将无限期地阻止当前线程,直到操作成功为止,而第四个程序块在放弃之前只有给定的最大时限。 这些方法总结在下表中:
add(e)
offer(e)
put(e)
offer(e, time, unit)
Remove remove()
poll()
take()
poll(time, unit)
Examine element()
peek()
not applicable not applicable
A BlockingQueue
不接受null
元素。 实现抛出NullPointerException
上尝试add
, put
或offer
一个null
。 A null
用作哨兵值以指示poll
操作失败。
A BlockingQueue
可能是容量有限的。 在任何给定的时间它可能有一个remainingCapacity
超过其中没有额外的元素可以put
没有阻止。 没有任何内在容量限制的A BlockingQueue
总是报告剩余容量为Integer.MAX_VALUE
。
BlockingQueue
实现被设计为主要用于生产者 - 消费者队列,但另外支持Collection
接口。 因此,例如,可以使用remove(x)
从队列中删除任意元素。 然而,这样的操作通常不能非常有效地执行,并且仅用于偶尔使用,例如当排队的消息被取消时。
BlockingQueue
实现是线程安全的。 所有排队方法使用内部锁或其他形式的并发控制在原子上实现其效果。 然而, 大量的Collection操作addAll
, containsAll
, retainAll
和removeAll
不一定原子除非在实现中另有规定执行。 因此有可能,例如,为addAll(c)
到只增加一些元件在后失败(抛出异常) c
。
A BlockingQueue
上不支持任何类型的“关闭”或“关闭”操作,表示不再添加项目。 这些功能的需求和使用往往依赖于实现。 例如,一个常见的策略是生产者插入特殊的尾流或毒物 ,这些消费者在被消费者摄取时被相应地解释。
使用示例,基于典型的生产者 - 消费者场景。 请注意, BlockingQueue
可以安全地与多个生产者和多个消费者一起使用。
class Producer implements Runnable { private final BlockingQueue queue; Producer(BlockingQueue q) { queue = q; } public void run() { try { while (true) { queue.put(produce()); } } catch (InterruptedException ex) { ... handle ...} } Object produce() { ... } } class Consumer implements Runnable { private final BlockingQueue queue; Consumer(BlockingQueue q) { queue = q; } public void run() { try { while (true) { consume(queue.take()); } } catch (InterruptedException ex) { ... handle ...} } void consume(Object x) { ... } } class Setup { void main() { BlockingQueue q = new SomeQueueImplementation(); Producer p = new Producer(q); Consumer c1 = new Consumer(q); Consumer c2 = new Consumer(q); new Thread(p).start(); new Thread(c1).start(); new Thread(c2).start(); } }
存储器一致性效果:当与其他并发集合,事先将物体放置成在一个线程动作BlockingQueue
happen-before到该元素的从访问或移除后续动作BlockingQueue
在另一个线程。
此接口是成员Java Collections Framework 。
Modifier and Type | Method and Description |
---|---|
boolean |
add(E e)
将指定的元素插入到此队列中,如果可以立即执行此操作而不违反容量限制,
true 在成功后返回
IllegalStateException 如果当前没有可用空间,则抛出IllegalStateException。
|
boolean |
contains(Object o)
如果此队列包含指定的元素,则返回
true 。
|
int |
drainTo(Collection<? super E> c)
从该队列中删除所有可用的元素,并将它们添加到给定的集合中。
|
int |
drainTo(Collection<? super E> c, int maxElements)
最多从该队列中删除给定数量的可用元素,并将它们添加到给定的集合中。
|
boolean |
offer(E e)
将指定的元素插入到此队列中,如果可以立即执行此操作,而不会违反容量限制,
true 在成功时
false 如果当前没有可用空间,则返回false。
|
boolean |
offer(E e, long timeout, TimeUnit unit)
将指定的元素插入到此队列中,等待指定的等待时间(如有必要)才能使空间变得可用。
|
E |
poll(long timeout, TimeUnit unit)
检索并删除此队列的头,等待指定的等待时间(如有必要)使元素变为可用。
|
void |
put(E e)
将指定的元素插入到此队列中,等待空格可用。
|
int |
remainingCapacity()
返回该队列最好可以(在没有存储器或资源约束)接受而不会阻塞,或附加的元素的数量
Integer.MAX_VALUE 如果没有固有的限制。
|
boolean |
remove(Object o)
从该队列中删除指定元素的单个实例(如果存在)。
|
E |
take()
检索并删除此队列的头,如有必要,等待元素可用。
|
addAll, clear, containsAll, equals, hashCode, isEmpty, iterator, parallelStream, removeAll, removeIf, retainAll, size, spliterator, stream, toArray, toArray
boolean add(E e)
true
在成功和抛出IllegalStateException
如果当前没有空间可用。
当使用容量限制队列时,通常最好使用offer
。
add
在界面
Collection<E>
add
在界面
Queue<E>
e
- 要添加的元素
true
(由
Collection.add(E)
指定 )
IllegalStateException
- 如果由于容量限制,此时无法添加该元素
ClassCastException
- 如果指定元素的类阻止将其添加到此队列
NullPointerException
- 如果指定的元素为空
IllegalArgumentException
- 如果指定元素的某些属性阻止将其添加到此队列中
boolean offer(E e)
true
在成功和false
,如果当前没有空间可用。
当使用容量限制队列时,此方法通常优于add(E)
,这可能无法仅通过抛出异常来插入元素。
offer
在界面
Queue<E>
e
- 要添加的元素
true
如果元素被添加到此队列,否则
false
ClassCastException
- 如果指定元素的类阻止将其添加到此队列中
NullPointerException
- 如果指定的元素为空
IllegalArgumentException
- 如果指定元素的某些属性阻止将其添加到此队列
void put(E e) throws InterruptedException
e
- 要添加的元素
InterruptedException
- 如果在等待时中断
ClassCastException
- 如果指定元素的类阻止将其添加到此队列中
NullPointerException
- 如果指定的元素为空
IllegalArgumentException
- 如果指定元素的某些属性阻止将其添加到此队列中
boolean offer(E e, long timeout, TimeUnit unit) throws InterruptedException
e
- 要添加的元素
timeout
- 放弃之前等待多久,以
unit
为单位
unit
- a
TimeUnit
确定如何解释
timeout
参数
true
如果成功,或
false
如果在空间可用之前经过指定的等待时间
InterruptedException
- 如果在等待时中断
ClassCastException
- 如果指定元素的类阻止将其添加到此队列中
NullPointerException
- 如果指定的元素为空
IllegalArgumentException
- 如果指定元素的某些属性阻止将其添加到此队列中
E take() throws InterruptedException
InterruptedException
- 如果在等待时中断
E poll(long timeout, TimeUnit unit) throws InterruptedException
timeout
- 放弃等待多久,以
unit
为单位
unit
- a
TimeUnit
确定如何解释
timeout
参数
null
如果在元素可用之前经过了指定的等待时间
InterruptedException
- 如果在等待时中断
int remainingCapacity()
Integer.MAX_VALUE
如果没有固有的限制。
请注意,您不能总是通过检查remainingCapacity
来判断是否尝试插入元素,因为可能是另一个线程即将插入或删除元素的情况。
boolean remove(Object o)
e
,使得o.equals(e)
,如果这个队列包含一个或多个这样的元素。
如果此队列包含指定的元素(或等效地,如果此队列作为调用的结果而更改),则返回true
。
remove
在界面
Collection<E>
o
- 要从此队列中删除的元素(如果存在)
true
如果此队列由于调用而更改
ClassCastException
- 如果指定元素的类与此队列不兼容(
optional )
NullPointerException
- 如果指定的元素为空(
optional )
boolean contains(Object o)
true
。
更正式地,返回true
如果且仅当这个队列至少包含一个元素e
,使得o.equals(e)
。
contains
在界面
Collection<E>
o
- 要检查此队列中的遏制的对象
true
如果此队列包含指定的元素
ClassCastException
- 如果指定元素的类与此队列不兼容(
optional )
NullPointerException
- 如果指定的元素为空(
optional )
int drainTo(Collection<? super E> c)
c
添加元素时遇到的c
可能会导致在抛出关联的异常时,元素既不在两个集合中,也可能不是两个集合。
尝试将队列排入自身会导致IllegalArgumentException
。
此外,如果在操作进行中修改了指定的集合,则此操作的行为是未定义的。
c
- 传输元素的集合
UnsupportedOperationException
- 如果指定集合不支持元素的添加
ClassCastException
- 如果此队列的元素的类阻止将其添加到指定的集合
NullPointerException
- 如果指定的集合为空
IllegalArgumentException
- 如果指定的集合是此队列,或此队列的某个元素的某些属性会阻止将其添加到指定的集合
int drainTo(Collection<? super E> c, int maxElements)
c
添加元素时遇到的c
可能会导致在抛出关联的异常时,元素既不在两个集合中,也可能不是两个集合。
尝试将队列排入自身导致IllegalArgumentException
。
此外,如果在操作进行中修改了指定的集合,则此操作的行为是未定义的。
c
- 传输元素的集合
maxElements
- 要传输的元素的最大数量
UnsupportedOperationException
- 如果指定集合不支持元素的添加
ClassCastException
- 如果此队列的元素的类阻止将其添加到指定的集合
NullPointerException
- 如果指定的集合为空
IllegalArgumentException
- if the specified collection is this queue, or some property of an element of this queue prevents it from being added to the specified collection
Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2014, Oracle and/or its affiliates. All rights reserved.