Java Reference ยท Concurrency
The BlockingQueue interface
Reference for java.util.concurrent.BlockingQueue: put and take, timed offer and poll, bounded and unbounded implementations, and the producer-consumer pattern.
BlockingQueue<E> is a thread-safe Queue whose operations can wait. put() blocks while the queue is full, and take() blocks while it is empty. This makes it the standard building block for the producer-consumer pattern: producers add work, consumers remove it, and the queue handles all the coordination and back-pressure.
The main implementations are ArrayBlockingQueue (bounded, array-backed), LinkedBlockingQueue (optionally bounded), PriorityBlockingQueue (unbounded, ordered), DelayQueue, SynchronousQueue (no storage: a hand-off) and LinkedTransferQueue. Thread pools use blocking queues internally to hold waiting tasks.
BlockingQueue<String> queue = new ArrayBlockingQueue<>(10); queue.put("job"); // waits if full String job = queue.take(); // waits if empty
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.
Syntax
public interface BlockingQueue<E> extends Queue<E> { void put(E e) throws InterruptedException; E take() throws InterruptedException; boolean offer(E e, long timeout, TimeUnit unit) throws InterruptedException; E poll(long timeout, TimeUnit unit) throws InterruptedException; int remainingCapacity(); int drainTo(Collection<? super E> c); int drainTo(Collection<? super E> c, int maxElements); }
Each operation comes in four flavours depending on what should happen when it cannot complete right away:
| Action | Throws exception | Returns special value | Blocks | Times out |
|---|---|---|---|---|
| Insert | add(e) |
offer(e) (false) |
put(e) |
offer(e, time, unit) |
| Remove | remove() |
poll() (null) |
take() |
poll(time, unit) |
| Examine | element() |
peek() (null) |
not available | not available |
Usage notes
- No
nullelements. Queues rejectnullwithNullPointerException, becausepoll()usesnullto mean "empty". - Bounded queues give back-pressure. A fast producer is slowed by
put()when consumers fall behind. An unboundedLinkedBlockingQueuecan grow until memory runs out. - Shutting down consumers: the queue has no "closed" state. Use a poison pill value (as above), one per consumer, or interrupt the consumer threads.
- Interruption:
put,takeand the timed variants throwInterruptedException. Restore the flag withThread.currentThread().interrupt()if you cannot propagate it. size()is only a snapshot in a concurrent setting; do not use it to decide whethertake()will block.- Fairness:
ArrayBlockingQueue(capacity, true)serves waiting threads in order at some cost in throughput. SynchronousQueuehands each element directly from a producer to a consumer;Executors.newCachedThreadPool()uses one.- Iteration is weakly consistent and never throws
ConcurrentModificationException. - Memory visibility: actions before putting an element happen-before actions after taking it.