Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Java Queue poll: How to Use It Correctly

The poll() method removes and returns the head of a Java Queue, or returns null if it is empty. Learn how it differs from remove(), peek(), and element(), how common queue implementations behave, and mistakes to avoid.

~4 min readJava
#Java#Queue#poll()#BlockingQueue
Illustration of a Java queue with a poll operation extracting the head element.

To use Java's Queue.poll() correctly, you need to understand its return value, how it differs from the related access methods, and how it behaves across the common Queue implementations. This article covers those details and points out common mistakes.

The poll() method on a Java Queue retrieves and removes the head of the queue, or returns null if the queue is empty. It is one of the most commonly used queue operations, but its behavior differs subtly from the related access methods.

How poll() Differs from remove(), peek(), and element()

The Queue interface defines two pairs of methods for the head element:

  • poll() returns and removes the head, or returns null if the queue is empty.
  • remove() returns and removes the head, but throws NoSuchElementException if the queue is empty.
  • peek() returns the head without removing it, and returns null if the queue is empty.
  • element() returns the head without removing it, but throws NoSuchElementException if the queue is empty.

The choice between poll() and remove() depends on how you want to handle the empty case. poll() is safer when an empty queue is a normal condition, while remove() signals an error condition. peek() and element() are useful when you need to inspect the head without consuming it.

Using poll() in a Loop to Drain a Queue

A common pattern is to drain a queue until it is empty. Because poll() returns null when the queue has no elements, you can use it directly in a condition:

java
Queue<String> tasks = new LinkedList<>(); tasks.add("task1"); tasks.add("task2"); String task; while ((task = tasks.poll()) != null) { System.out.println("Processing: " + task); }

This loop continues until poll() returns null, which signals that the queue is empty. Note that this approach assumes the queue does not contain null elements. If your queue can legitimately hold null, this loop terminates prematurely. The next section covers that nuance.

poll() on Different Queue Implementations

The Queue interface is implemented by several classes, each with different characteristics. The behavior of poll() itself is consistent—it removes and returns the head—but the underlying data structure affects performance and ordering.

  • LinkedList implements Queue with a doubly-linked list. poll() runs in constant time, O(1), and maintains FIFO order.
  • ArrayDeque is a resizable array-based deque. It also offers O(1) poll() and is often more memory-efficient than LinkedList.
  • PriorityQueue orders elements by natural order or a provided comparator. poll() removes the smallest (or highest-priority) element and runs in O(log n) time because the heap must be restructured.
  • ConcurrentLinkedQueue is a thread-safe, lock-free queue. poll() is generally O(1) and safe for concurrent access, but it does not permit null elements.

For most FIFO use cases, ArrayDeque is a solid choice because it avoids the overhead of node objects and offers good cache locality. If you need thread safety, ConcurrentLinkedQueue or a blocking queue is appropriate.

Handling null Elements and the Meaning of null Return

The poll() method returns null to indicate an empty queue. This creates an ambiguity: if your queue can contain null as a legitimate element, you cannot distinguish between an empty queue and a null element at the head. Most queue implementations, including ArrayDeque, PriorityQueue, and ConcurrentLinkedQueue, explicitly forbid null elements. LinkedList allows null, but it is rarely a good practice to store null in a queue.

If you must support null elements, you can use remove() and catch NoSuchElementException, or check isEmpty() before calling poll() in a single-threaded context. The cleaner approach is to avoid null elements altogether and use a sentinel value or a wrapper object.

Timeouts and Blocking Queues: poll(time, unit)

The BlockingQueue interface adds a timed version of poll():

java
BlockingQueue<String> queue = new ArrayBlockingQueue<>(10); String element = queue.poll(2, TimeUnit.SECONDS);

This call waits up to the specified time for an element to become available. If no element arrives within the timeout, it returns null. This is useful in producer-consumer scenarios where you want to avoid indefinite blocking. The timed poll() differs from the ordinary poll(), which returns immediately.

Performance Characteristics of poll()

The time complexity of poll() depends on the implementation. For LinkedList and ArrayDeque, it is O(1). For PriorityQueue, it is O(log n) because removing the head requires re-heapification. For concurrent queues like ConcurrentLinkedQueue, poll() is lock-free and typically O(1) under low contention, but can degrade under heavy contention due to retries.

In a single-threaded context, ArrayDeque is often the fastest choice because it uses an array and avoids node allocation. In a multi-threaded context, ConcurrentLinkedQueue provides thread safety without blocking, but you must ensure that no null elements are added.

Common Mistakes When Using poll()

One frequent mistake is calling poll() and then using the result without checking for null when the queue might be empty, which leads to NullPointerException. Another is assuming that the ordinary poll() blocks when the queue is empty; it does not. If you need blocking behavior, use BlockingQueue.take() for an indefinite wait or poll(time, unit) for a timed wait. A third mistake is using poll() on a PriorityQueue and expecting FIFO order; the order depends on the comparator.

Also, be careful when mixing poll() with peek() in the same loop. If you call peek() to inspect the head and then poll() to remove it, another thread can change the queue between the two calls in a concurrent setting. In such cases, use a lock or a single atomic operation.

Try matching browser tools

All tools

Small utilities that fit Java work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Java guides

More in Java

All Java guides

The guides filed next to this one in Java, in library order.