CKTIS / Java
BlockingQueue — a queue with waiting operations
BlockingQueue<E> supports safe exchange of elements between threads, such as a producer and a consumer. It distinguishes operations that do not wait for space or elements, waiting operations, and timed variants. The example uses an ArrayBlockingQueue with capacity 1.
Version: Java SE 21; repository runtime, production runtime not attested
Syntax
BlockingQueue<E> queue = new ArrayBlockingQueue<>(capacity);
boolean accepted = queue.offer(element);
E removed = queue.poll();
queue.put(element); // throws InterruptedException
E received = queue.take(); // throws InterruptedException
E head = queue.peek();
int count = queue.size();
boolean acceptedInTime = queue.offer(element, timeout, unit);
E receivedInTime = queue.poll(timeout, unit);BlockingQueue<E> in java.util.concurrent extends Queue<E>. Implementations are thread-safe and support uses such as producer–consumer communication. Capacity and ordering depend on the implementation: ArrayBlockingQueue has fixed capacity and FIFO ordering; the interface itself does not guarantee FIFO.
BlockingQueue.offer(e) returns true after insertion or false when no space is available. BlockingQueue.poll() removes and returns the head, or returns null when empty. BlockingQueue.peek() reads the head without removal and returns null when empty. These variants do not wait for space or elements. BlockingQueue.size() returns the element count, but that result can change before the next operation; do not use it to check whether a later insertion or retrieval will succeed.
BlockingQueue.put(e) waits for space, while BlockingQueue.take() waits for an element and removes it. They can wait indefinitely. The variants offer(e, timeout, unit) and poll(timeout, unit) limit waiting, returning false or null, respectively, if time expires without success. Waiting operations declare InterruptedException; propagate it or handle interruption without silently ignoring it.
Elements cannot be null. Individual queuing operations are atomic, but a sequence of calls does not thereby become atomic. The interface has no built-in close operation; termination requires a separate protocol.
The single-threaded example deterministically demonstrates full and empty states. put and take can complete immediately because space and an element, respectively, are available; the example does not demonstrate waiting between threads.
Examples
import java.util.concurrent.ArrayBlockingQueue;
import java.util.concurrent.BlockingQueue;
public class Main {
public static void main(String[] args) throws InterruptedException {
BlockingQueue<String> queue = new ArrayBlockingQueue<>(1);
System.out.println(queue.offer("A"));
System.out.println(queue.offer("B"));
System.out.println(queue.peek());
System.out.println(queue.size());
System.out.println(queue.poll());
System.out.println(queue.poll());
queue.put("C");
System.out.println(queue.take());
System.out.println(queue.size());
}
}Result
true false A 1 A null C 0
The displayed code and declared result were verified in an isolated environment using the method recorded in the verification evidence for this exact version.