
The java.util.concurrent.BlockingDeque interface extends the Deque interface with additional blocking operations:
- Dequeue operations that, when taking an element from an empty deque, wait until an element is available (i.e., until another thread inserts one).
- Enqueue operations that, when an element is inserted into a full¹ deque, block until space is available again (i.e., until another thread has taken an element).
BlockingDeque also extends BlockingQueue, and indirectly – via both Deque and BlockingQueue – the Queue and Collection interfaces:
¹ A deque is full when it is bounded, and the number of elements inserted into the deque has reached the specified deque capacity.
Since Java 21, Deque also extends SequencedCollection – what that means for a deque is explained in the article Queue vs. Deque.
Like any BlockingQueue, a BlockingDeque is thread-safe and does not permit null elements.
Java BlockingDeque Methods
The blocking methods are available in two variants: one that waits indefinitely and one that takes a timeout parameter. When this timeout expires, the method gives up and returns false or null.
All blocking methods – with and without timeout – throw an InterruptedException when the waiting thread is interrupted. What that means for your program is covered in the chapter InterruptedException for Blocking Methods of the BlockingQueue article.
The methods that BlockingDeque inherits from BlockingQueue (e.g., enqueue at the tail, dequeue at the head) have been additionally defined with new names for consistency – for example, BlockingQueue.put() as BlockingDeque.putLast().
In the following listing of methods, I include these BlockingQueue methods with the equivalent BlockingDeque methods.
At the end of the chapter, two tables summarize all the methods.
Blocking Methods for Inserting into the Deque
First, a graphical representation of the blocking enqueue methods:
BlockingDeque.putFirst() + putLast()
The methods putFirst() and putLast() insert an element at the beginning and end of the deque, respectively, if space is available. If the deque is full, however, these methods block until another thread has taken an element and thus space is available again for the new element.
The put() method inherited from the BlockingQueue interface is equivalent to BlockingDeque.putLast().
BlockingDeque.offerFirst() + offerLast() with Timeout
Also, offerFirst() and offerLast() insert an element into the deque if space is available. Otherwise, these methods block for at most the specified time. If the element could not be inserted after this time, these methods return false.
The offer(E e, long timeout, TimeUnit unit) method inherited from the BlockingQueue interface is equivalent to BlockingDeque.offerLast(E e, long timeout, TimeUnit unit).
Blocking Methods for Removing from the Deque
First, again, a graphical representation of the blocking dequeue methods:
BlockingDeque.takeFirst() + takeLast()
takeFirst() and takeLast() take an element from the beginning and end of the deque, respectively, if the deque is not empty. If the deque is empty, these methods block until another thread inserts an element.
The take() method inherited from the BlockingQueue interface is equivalent to BlockingDeque.takeFirst().
BlockingDeque.pollFirst() + pollLast() with Timeout
Also, pollFirst() and pollLast() take an element from the deque if one is available. Otherwise, the methods wait for the specified time. If an element is inserted within the wait time, the methods return it immediately. If there is still no element after the time expires, these methods return null.
The poll(long timeout, TimeUnit unit) method inherited from the BlockingQueue interface is equivalent to BlockingDeque.pollFirst(long timeout, TimeUnit unit).
BlockingDeque Methods – Summary
Below you will find two tables: the first one contains the methods for inserting and removing elements at the head of the deque; the second one lists the methods for the elements at the tail of the deque.
In the first two columns, you can see the non-blocking methods BlockingDeque inherits from Deque (and indirectly from Queue – marked with a superscript 1).
In the third and fourth columns, you will find the new blocking methods (including those defined in BlockingQueue – marked with a superscript 2).
Operations at the Beginning (Head) of the Deque
| Operation | Non-blocking: exception | Non-blocking: return value | Blocking | Blocking with timeout |
|---|---|---|---|---|
| Inserting an element (enqueue) | addFirst(e) | offerFirst(e) | putFirst(e) | offerFirst(e, time, unit) |
| Removing an element (dequeue) | removeFirst()remove()¹ | pollFirst()poll()¹ | takeFirst()take()² | pollFirst(time, unit)poll(time, unit)² |
| Viewing an element (examine) | getFirst()element()¹ | peekFirst()peek()¹ | – | – |
Operations at the End (Tail) of the Deque
| Operation | Non-blocking: exception | Non-blocking: return value | Blocking | Blocking with timeout |
|---|---|---|---|---|
| Inserting an element (enqueue) | addLast(e)add(e)¹ | offerLast(e)offer(e)¹ | putLast(e)put(e)² | offerLast(e, time, unit)offer(e, time, unit)² |
| Removing an element (dequeue) | removeLast() | pollLast() | takeLast() | pollLast(time, unit) |
| Viewing an element (examine) | getLast() | peekLast() | – | – |
¹ These methods are inherited from the Queue interface; in a deque, they are equivalent to the Deque method in the same cell.
² These methods are inherited from the BlockingQueue interface; in a blocking deque, they are equivalent to the BlockingDeque method in the same cell.
Java BlockingDeque Example
The following example shows how a BlockingDeque blocks. It uses the only implementation of the interface in the JDK, LinkedBlockingDeque, with a capacity of three elements:
- A consumer thread takes one element per second from the tail of the deque with
takeLast(). - The main thread inserts five elements at the head with
putFirst()– as fast as it can.
You can find the code in the BlockingDequeExample class on GitHub.
public class BlockingDequeExample {
private static final long START = System.currentTimeMillis();
static void main() throws InterruptedException {
BlockingDeque<Integer> deque = new LinkedBlockingDeque<>(3);
Thread consumer =
Thread.ofPlatform()
.start(
() -> {
try {
for (int i = 0; i < 5; i++) {
Thread.sleep(1000);
log("takeLast() returned " + deque.takeLast());
}
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
}
});
for (int i = 1; i <= 5; i++) {
deque.putFirst(i);
log("putFirst(" + i + ") returned");
}
consumer.join();
}
private static void log(String message) {
long seconds = Math.round((System.currentTimeMillis() - START) / 1000.0);
System.out.println(seconds + " s: " + message);
}
}
The program prints the following (the times are rounded to whole seconds):
0 s: putFirst(1) returned
0 s: putFirst(2) returned
0 s: putFirst(3) returned
1 s: putFirst(4) returned
1 s: takeLast() returned 1
2 s: putFirst(5) returned
2 s: takeLast() returned 2
3 s: takeLast() returned 3
4 s: takeLast() returned 4
5 s: takeLast() returned 5
The first three putFirst() calls return immediately. The fourth one blocks because the deque is full – it only gets through after the consumer has taken the 1, one second later. In the same way, putFirst(5) waits until the consumer takes the 2. Two lines with the same second can also appear in swapped order, since both threads print at the same time. After that, the main thread is done, and the consumer empties the deque one element per second.
The elements are taken in the order 1 to 5 because of the combination of putFirst() and takeLast(): what is inserted at the head leaves the deque at the tail – FIFO with the deque’s methods instead of the queue’s.
You can find a more extensive example with several threads inserting and taking at random ends in the article about LinkedBlockingDeque.
Summary and Outlook
In this article, you learned about the BlockingDeque interface and its blocking methods putFirst(), putLast(), offerFirst(), offerLast(), takeFirst(), takeLast(), pollFirst(), and pollLast().
In the following parts of this tutorial series, I will describe all Deque and BlockingDeque implementations with their specific characteristics. You can find a recommendation on when to use which deque implementation in the Deque interface article. At the end of the tutorial, I will show you how to implement a Deque yourself.
Did this article answer your questions? Then I’d be happy about a review on my ProvenExpert profile – it helps other developers find this content.




