Skip to content
Tutorials Center
My learning

Topics

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.

Java
BlockingQueue<String> queue = new ArrayBlockingQueue<>(10);
queue.put("job");          // waits if full
String job = queue.take(); // waits if empty

Try it

Java Producer and consumer

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.

Java The four ways to add and remove

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

Java
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 null elements. Queues reject null with NullPointerException, because poll() uses null to mean "empty".
  • Bounded queues give back-pressure. A fast producer is slowed by put() when consumers fall behind. An unbounded LinkedBlockingQueue can 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, take and the timed variants throw InterruptedException. Restore the flag with Thread.currentThread().interrupt() if you cannot propagate it.
  • size() is only a snapshot in a concurrent setting; do not use it to decide whether take() will block.
  • Fairness: ArrayBlockingQueue(capacity, true) serves waiting threads in order at some cost in throughput.
  • SynchronousQueue hands 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.