-
- 参数类型
-
E
- 此队列中保留的元素类型
- All Superinterfaces:
-
Collection<E>
,Iterable<E>
,Queue<E>
- All Known Subinterfaces:
-
BlockingDeque<E>
,TransferQueue<E>
- 所有已知实现类:
-
ArrayBlockingQueue
,DelayQueue
,LinkedBlockingDeque
,LinkedBlockingQueue
,LinkedTransferQueue
,PriorityBlockingQueue
,SynchronousQueue
public interface BlockingQueue<E> extends Queue<E>
Queue
还支持在检索元素时等待队列变为非空的操作,并在存储元素时等待队列中的空间可用。BlockingQueue
方法有四种形式,有不同的处理操作方式,不能立即满足,但可能在将来的某个时候满足:一个抛出异常,第二个返回一个特殊值(null
或false
,取决于操作),第三个无限期地阻塞当前线程直到操作成功,并且第四个块在放弃之前仅用于给定的最大时间限制。 这些方法总结在下表中:add(e)
offer(e)
put(e)
offer(e, time, unit)
Removeremove()
poll()
take()
poll(time, unit)
Examineelement()
peek()
not applicable not applicableA
BlockingQueue
不接受null
元素。 实现抛出NullPointerException
上尝试add
,put
或offer
一个null
。null
用作null
值以指示poll
操作失败。BlockingQueue
可以是容量限制的。 在任何给定时间它可能有一个remainingCapacity
超过该put
没有阻止的附加元素可以是put
。 一个BlockingQueue
没有任何内部容量约束始终报告的剩余容量Integer.MAX_VALUE
。BlockingQueue
实现主要用于生产者 - 消费者队列,但另外支持Collection
接口。 因此,例如,可以使用remove(x)
从队列中删除任意元素。 然而,这些操作通常不是非常有效地执行,并且仅用于偶尔使用,例如当排队的消息被取消时。BlockingQueue
实现是线程安全的。 所有排队方法都使用内部锁或其他形式的并发控制以原子方式实现其效果。 然而, 大量的Collection操作addAll
,containsAll
,retainAll
和removeAll
不一定原子除非在实现中另有规定执行。 因此,例如,addAll(c)
可能在仅添加c
一些元素后失败(抛出异常)。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
中的该元素后,将对象放入BlockingQueue
happen-before之前的操作。此界面是Java Collections Framework的成员。
- 从以下版本开始:
- 1.5
-
-
方法摘要
所有方法 实例方法 抽象方法 变量和类型 方法 描述 boolean
add(E e)
如果可以在不违反容量限制的情况下立即执行此操作,则将指定的元素插入此队列,成功时返回true
,如果当前没有空间,则抛出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
,如果当前没有空间可用。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()
检索并删除此队列的头部,必要时等待,直到元素可用。-
声明方法的接口 java.util.Collection
addAll, clear, containsAll, equals, hashCode, isEmpty, iterator, parallelStream, removeAll, removeIf, retainAll, size, spliterator, stream, toArray, toArray, toArray
-
-
-
-
方法详细信息
-
add
boolean add(E e)
如果可以在不违反容量限制的情况下立即执行此操作,则将指定的元素插入此队列,成功时返回true
,如果当前没有空间,则抛出IllegalStateException
。 使用容量限制队列时,通常最好使用offer
。- Specified by:
-
add
在界面Collection<E>
- Specified by:
-
add
在接口Queue<E>
- 参数
-
e
- 要添加的元素 - 结果
-
true
(由Collection.add(E)
指定) - 异常
-
IllegalStateException
- 如果由于容量限制,此时无法添加元素 -
ClassCastException
- 如果指定元素的类阻止将其添加到此队列 -
NullPointerException
- 如果指定的元素为null -
IllegalArgumentException
- 如果指定元素的某些属性阻止将其添加到此队列
-
offer
boolean offer(E e)
将指定的元素插入此队列中,如果它是立即可行且不会违反容量限制,返回true
在成功和false
,如果当前没有空间可用。 使用容量限制队列时,此方法通常优于add(E)
,它只能通过抛出异常来插入元素。- Specified by:
-
offer
,界面Queue<E>
- 参数
-
e
- 要添加的元素 - 结果
-
true
如果元素已添加到此队列,false
- 异常
-
ClassCastException
- 如果指定元素的类阻止将其添加到此队列 -
NullPointerException
- 如果指定的元素为null -
IllegalArgumentException
- 如果指定元素的某些属性阻止将其添加到此队列
-
put
void put(E e) throws InterruptedException
将指定的元素插入此队列,等待空间变为可用。- 参数
-
e
- 要添加的元素 - 异常
-
InterruptedException
- 如果在等待时中断 -
ClassCastException
- 如果指定元素的类阻止将其添加到此队列 -
NullPointerException
- 如果指定的元素为null -
IllegalArgumentException
- 如果指定元素的某些属性阻止将其添加到此队列
-
offer
boolean offer(E e, long timeout, TimeUnit unit) throws InterruptedException
将指定的元素插入此队列,如果需要空间可用,则等待指定的等待时间。- 参数
-
e
- 要添加的元素 -
timeout
- 放弃前等待多长时间,单位为unit
-
unit
-一个TimeUnit
确定如何解释timeout
参数 - 结果
-
true
如果成功,或false
如果在空间可用之前经过了指定的等待时间 - 异常
-
InterruptedException
- 如果在等待时中断 -
ClassCastException
- 如果指定元素的类阻止将其添加到此队列 -
NullPointerException
- 如果指定的元素为null -
IllegalArgumentException
- 如果指定元素的某些属性阻止将其添加到此队列
-
take
E take() throws InterruptedException
检索并删除此队列的头部,必要时等待,直到元素可用。- 结果
- 这个队列的头
- 异常
-
InterruptedException
- 如果在等待时中断
-
poll
E poll(long timeout, TimeUnit unit) throws InterruptedException
检索并删除此队列的头部,如果元素可用,则等待指定的等待时间。- 参数
-
timeout
- 放弃前等待多长时间,单位为unit
-
unit
-一个TimeUnit
确定如何解释timeout
参数 - 结果
-
此队列的头部,或
null
如果在元素可用之前经过了指定的等待时间 - 异常
-
InterruptedException
- 等待时中断
-
remainingCapacity
int remainingCapacity()
返回理想情况下(在没有内存或资源限制的情况下)此队列可以无阻塞地接受的其他元素的数量,如果没有内部限制,则Integer.MAX_VALUE
。请注意,您不能总是通过检查
remainingCapacity
来判断插入元素的尝试是否成功,因为可能是另一个线程即将插入或删除元素的情况。- 结果
- 剩余的容量
-
remove
boolean remove(Object o)
从此队列中删除指定元素的单个实例(如果存在)。 更正式地,如果此队列包含一个或多个这样的元素,则移除元素e
,使得o.equals(e)
。 如果此队列包含指定的元素,则返回true
(或等效地,如果此队列因调用而更改)。- Specified by:
-
remove
在界面Collection<E>
- 参数
-
o
- 要从此队列中删除的元素(如果存在) - 结果
-
true
如果此队列因调用而更改 - 异常
-
ClassCastException
- 如果指定元素的类与此队列不兼容( optional ) -
NullPointerException
- 如果指定的元素为null( optional )
-
contains
boolean contains(Object o)
如果此队列包含指定的元素,则返回true
。 更正式地,当且仅当此队列包含至少一个元素e
时才返回true
o.equals(e)
。- Specified by:
-
contains
在界面Collection<E>
- 参数
-
o
- 要在此队列中检查包含的对象 - 结果
-
true
如果此队列包含指定的元素 - 异常
-
ClassCastException
- 如果指定元素的类与此队列不兼容( optional ) -
NullPointerException
- 如果指定的元素为null( optional )
-
drainTo
int drainTo(Collection<? super E> c)
从此队列中删除所有可用元素,并将它们添加到给定集合中。 此操作可能比重复轮询此队列更有效。 尝试将元素添加到集合c
遇到的故障可能导致在抛出关联的异常时元素既不在集合中,也不在集合中。 尝试将队列排入自身会导致IllegalArgumentException
。 此外,如果在操作正在进行时修改了指定的集合,则此操作的行为是不确定的。- 参数
-
c
- 将元素转换为的集合 - 结果
- 转移的元素数量
- 异常
-
UnsupportedOperationException
- 如果指定集合不支持添加元素 -
ClassCastException
- 如果此队列的元素的类阻止将其添加到指定的集合中 -
NullPointerException
- 如果指定的集合为null -
IllegalArgumentException
- 如果指定的集合是此队列,或此队列的某个元素的某些属性阻止将其添加到指定的集合
-
drainTo
int drainTo(Collection<? super E> c, int maxElements)
从该队列中删除最多给定数量的可用元素,并将它们添加到给定集合中。 尝试将元素添加到集合c
遇到的故障可能导致在抛出关联的异常时元素既不在集合中,也不在集合中。 尝试将队列排入自身会导致IllegalArgumentException
。 此外,如果在操作正在进行时修改了指定的集合,则此操作的行为是不确定的。- 参数
-
c
- 将元素转换为的集合 -
maxElements
- 要传输的最大元素数 - 结果
- 转移的元素数量
- 异常
-
UnsupportedOperationException
- 如果指定集合不支持添加元素 -
ClassCastException
- 如果此队列的元素的类阻止将其添加到指定的集合中 -
NullPointerException
- 如果指定的集合为null -
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
-
-