BlockingDeque Interface in Java (+ Code Example)

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.

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.

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

For an example of how to use the BlockingDeque interface, check out the tutorial on the sole implementation of this interface: LinkedBlockingDeque.

Summary and Outlook

In this article, you learned about the BlockingDeque interface and its blocking methods putFirst(), putLast(), offerFirst(), offerLast(), takeFirst(), takeLast(), and pollFirst(), 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.