Top Description Constructors Methods
com.google.common.collect

public final Class Queues

extends Object
Class Inheritance
Annotations
@GwtCompatible
emulated:true
@ElementTypesAreNonnullByDefault
Imports
com.google.common.annotations.GwtCompatible, .GwtIncompatible, .J2ktIncompatible, com.google.common.base.Preconditions, com.google.errorprone.annotations.CanIgnoreReturnValue, java.util.ArrayDeque, .Collection, .Deque, .PriorityQueue, .Queue, java.util.concurrent.ArrayBlockingQueue, .BlockingQueue, .ConcurrentLinkedQueue, .LinkedBlockingDeque, .LinkedBlockingQueue, .PriorityBlockingQueue, .SynchronousQueue, .TimeUnit, org.checkerframework.checker.nullness.qual.Nullable
Static utility methods pertaining to Queue and Deque instances. Also see this class's counterparts Lists, Sets, and Maps.
Author
Kurt Alfred Kluever
Since
11.0

Constructor Summary

AccessConstructor and Description
private
Queues()

Method Summary

Modifier and TypeMethod and Description
public static <E> int

Returns:

the number of elements transferred
drain(BlockingQueue<E>
the blocking queue to be drained
q, Collection<? super E>
where to add the transferred elements
buffer, int
the number of elements to be waited for
numElements, Duration
how long to wait before giving up
timeout)

Drains the queue as BlockingQueue#drainTo(Collection, int), but if the requested numElements elements are not available, it will wait for them up to the specified timeout.

public static <E> int

Returns:

the number of elements transferred
drain(BlockingQueue<E>
the blocking queue to be drained
q, Collection<? super E>
where to add the transferred elements
buffer, int
the number of elements to be waited for
numElements, long
how long to wait before giving up, in units of unit
timeout, TimeUnit
a TimeUnit determining how to interpret the timeout parameter
unit)

Drains the queue as BlockingQueue#drainTo(Collection, int), but if the requested numElements elements are not available, it will wait for them up to the specified timeout.

public static <E> int

Returns:

the number of elements transferred
drainUninterruptibly(BlockingQueue<E>
the blocking queue to be drained
q, Collection<? super E>
where to add the transferred elements
buffer, int
the number of elements to be waited for
numElements, Duration
how long to wait before giving up
timeout)

Drains the queue as drain(BlockingQueue, Collection, int, Duration), but with a different behavior in case it is interrupted while waiting.

public static <E> int

Returns:

the number of elements transferred
drainUninterruptibly(BlockingQueue<E>
the blocking queue to be drained
q, Collection<? super E>
where to add the transferred elements
buffer, int
the number of elements to be waited for
numElements, long
how long to wait before giving up, in units of unit
timeout, TimeUnit
a TimeUnit determining how to interpret the timeout parameter
unit)

Drains the queue as drain(BlockingQueue, Collection, int, long, TimeUnit), but with a different behavior in case it is interrupted while waiting.

public static <E> ArrayBlockingQueue<E>
newArrayBlockingQueue(int capacity)

Creates an empty ArrayBlockingQueue with the given (fixed) capacity and nonfair access policy.

public static <E> ArrayDeque<E>
newArrayDeque()

Creates an empty ArrayDeque.

public static <E> ArrayDeque<E>
newArrayDeque(Iterable<? extends E> elements)

Creates an ArrayDeque containing the elements of the specified iterable, in the order they are returned by the iterable's iterator.

public static <E> ConcurrentLinkedQueue<E>
newConcurrentLinkedQueue()

Creates an empty ConcurrentLinkedQueue.

public static <E> ConcurrentLinkedQueue<E>
newConcurrentLinkedQueue(Iterable<? extends E> elements)

Creates a ConcurrentLinkedQueue containing the elements of the specified iterable, in the order they are returned by the iterable's iterator.

public static <E> LinkedBlockingDeque<E>
newLinkedBlockingDeque()

Creates an empty LinkedBlockingDeque with a capacity of Integer#MAX_VALUE.

public static <E> LinkedBlockingDeque<E>
newLinkedBlockingDeque(int capacity)

Creates an empty LinkedBlockingDeque with the given (fixed) capacity.

public static <E> LinkedBlockingDeque<E>
newLinkedBlockingDeque(Iterable<? extends E> elements)

Creates a LinkedBlockingDeque with a capacity of Integer#MAX_VALUE, containing the elements of the specified iterable, in the order they are returned by the iterable's iterator.

public static <E> LinkedBlockingQueue<E>
newLinkedBlockingQueue()

Creates an empty LinkedBlockingQueue with a capacity of Integer#MAX_VALUE.

public static <E> LinkedBlockingQueue<E>
newLinkedBlockingQueue(int capacity)

Creates an empty LinkedBlockingQueue with the given (fixed) capacity.

public static <E> LinkedBlockingQueue<E>

Returns:

a new LinkedBlockingQueue containing those elements
newLinkedBlockingQueue(Iterable<? extends E>
the elements that the queue should contain, in order
elements)

Creates a LinkedBlockingQueue with a capacity of Integer#MAX_VALUE, containing the elements of the specified iterable, in the order they are returned by the iterable's iterator.

public static <E extends Comparable<T>> PriorityBlockingQueue<E>
newPriorityBlockingQueue()

Creates an empty PriorityBlockingQueue with the ordering given by its elements' natural ordering.

public static <E extends Comparable<T>> PriorityBlockingQueue<E>
newPriorityBlockingQueue(Iterable<? extends E> elements)

Creates a PriorityBlockingQueue containing the given elements.

public static <E extends Comparable<T>> PriorityQueue<E>
newPriorityQueue()

Creates an empty PriorityQueue with the ordering given by its elements' natural ordering.

public static <E extends Comparable<T>> PriorityQueue<E>
newPriorityQueue(Iterable<? extends E> elements)

Creates a PriorityQueue containing the given elements.

public static <E> SynchronousQueue<E>
newSynchronousQueue()

Creates an empty SynchronousQueue with nonfair access policy.

public static <E extends @Nullable Object> Deque<E>

Returns:

a synchronized view of the specified deque
synchronizedDeque(Deque<E>
the deque to be wrapped in a synchronized view
deque)

Returns a synchronized (thread-safe) deque backed by the specified deque.

public static <E extends @Nullable Object> Queue<E>

Returns:

a synchronized view of the specified queue
synchronizedQueue(Queue<E>
the queue to be wrapped in a synchronized view
queue)

Returns a synchronized (thread-safe) queue backed by the specified queue.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Constructor Detail

Queuesback to summary
private Queues()

Method Detail

drainback to summary
public static <E> int drain(BlockingQueue<E> q, Collection<? super E> buffer, int numElements, Duration timeout) throws InterruptedException

Drains the queue as BlockingQueue#drainTo(Collection, int), but if the requested numElements elements are not available, it will wait for them up to the specified timeout.

Parameters
q:BlockingQueue<E>

the blocking queue to be drained

buffer:Collection<? super E>

where to add the transferred elements

numElements:int

the number of elements to be waited for

timeout:Duration

how long to wait before giving up

Returns:int

the number of elements transferred

Annotations
@CanIgnoreReturnValue
@J2ktIncompatible
@GwtIncompatible
Exceptions
InterruptedException:
if interrupted while waiting
Since
28.0
drainback to summary
public static <E> int drain(BlockingQueue<E> q, Collection<? super E> buffer, int numElements, long timeout, TimeUnit unit) throws InterruptedException

Drains the queue as BlockingQueue#drainTo(Collection, int), but if the requested numElements elements are not available, it will wait for them up to the specified timeout.

Parameters
q:BlockingQueue<E>

the blocking queue to be drained

buffer:Collection<? super E>

where to add the transferred elements

numElements:int

the number of elements to be waited for

timeout:long

how long to wait before giving up, in units of unit

unit:TimeUnit

a TimeUnit determining how to interpret the timeout parameter

Returns:int

the number of elements transferred

Annotations
@CanIgnoreReturnValue
@J2ktIncompatible
@GwtIncompatible
@SuppressWarnings:GoodTime
Exceptions
InterruptedException:
if interrupted while waiting
drainUninterruptiblyback to summary
public static <E> int drainUninterruptibly(BlockingQueue<E> q, Collection<? super E> buffer, int numElements, Duration timeout)

Drains the queue as drain(BlockingQueue, Collection, int, Duration), but with a different behavior in case it is interrupted while waiting. In that case, the operation will continue as usual, and in the end the thread's interruption status will be set (no InterruptedException is thrown).

Parameters
q:BlockingQueue<E>

the blocking queue to be drained

buffer:Collection<? super E>

where to add the transferred elements

numElements:int

the number of elements to be waited for

timeout:Duration

how long to wait before giving up

Returns:int

the number of elements transferred

Annotations
@CanIgnoreReturnValue
@J2ktIncompatible
@GwtIncompatible
Since
28.0
drainUninterruptiblyback to summary
public static <E> int drainUninterruptibly(BlockingQueue<E> q, Collection<? super E> buffer, int numElements, long timeout, TimeUnit unit)

Drains the queue as drain(BlockingQueue, Collection, int, long, TimeUnit), but with a different behavior in case it is interrupted while waiting. In that case, the operation will continue as usual, and in the end the thread's interruption status will be set (no InterruptedException is thrown).

Parameters
q:BlockingQueue<E>

the blocking queue to be drained

buffer:Collection<? super E>

where to add the transferred elements

numElements:int

the number of elements to be waited for

timeout:long

how long to wait before giving up, in units of unit

unit:TimeUnit

a TimeUnit determining how to interpret the timeout parameter

Returns:int

the number of elements transferred

Annotations
@CanIgnoreReturnValue
@J2ktIncompatible
@GwtIncompatible
@SuppressWarnings:GoodTime
newArrayBlockingQueueback to summary
public static <E> ArrayBlockingQueue<E> newArrayBlockingQueue(int capacity)

Creates an empty ArrayBlockingQueue with the given (fixed) capacity and nonfair access policy.

Annotations
@J2ktIncompatible
@GwtIncompatible
newArrayDequeback to summary
public static <E> ArrayDeque<E> newArrayDeque()

Creates an empty ArrayDeque.

Since
12.0
newArrayDequeback to summary
public static <E> ArrayDeque<E> newArrayDeque(Iterable<? extends E> elements)

Creates an ArrayDeque containing the elements of the specified iterable, in the order they are returned by the iterable's iterator.

Since
12.0
newConcurrentLinkedQueueback to summary
public static <E> ConcurrentLinkedQueue<E> newConcurrentLinkedQueue()

Creates an empty ConcurrentLinkedQueue.

Annotations
@J2ktIncompatible
@GwtIncompatible
newConcurrentLinkedQueueback to summary
public static <E> ConcurrentLinkedQueue<E> newConcurrentLinkedQueue(Iterable<? extends E> elements)

Creates a ConcurrentLinkedQueue containing the elements of the specified iterable, in the order they are returned by the iterable's iterator.

Annotations
@J2ktIncompatible
@GwtIncompatible
newLinkedBlockingDequeback to summary
public static <E> LinkedBlockingDeque<E> newLinkedBlockingDeque()

Creates an empty LinkedBlockingDeque with a capacity of Integer#MAX_VALUE.

Annotations
@J2ktIncompatible
@GwtIncompatible
Since
12.0
newLinkedBlockingDequeback to summary
public static <E> LinkedBlockingDeque<E> newLinkedBlockingDeque(int capacity)

Creates an empty LinkedBlockingDeque with the given (fixed) capacity.

Annotations
@J2ktIncompatible
@GwtIncompatible
Exceptions
IllegalArgumentException:
if capacity is less than 1
Since
12.0
newLinkedBlockingDequeback to summary
public static <E> LinkedBlockingDeque<E> newLinkedBlockingDeque(Iterable<? extends E> elements)

Creates a LinkedBlockingDeque with a capacity of Integer#MAX_VALUE, containing the elements of the specified iterable, in the order they are returned by the iterable's iterator.

Annotations
@J2ktIncompatible
@GwtIncompatible
Since
12.0
newLinkedBlockingQueueback to summary
public static <E> LinkedBlockingQueue<E> newLinkedBlockingQueue()

Creates an empty LinkedBlockingQueue with a capacity of Integer#MAX_VALUE.

Annotations
@J2ktIncompatible
@GwtIncompatible
newLinkedBlockingQueueback to summary
public static <E> LinkedBlockingQueue<E> newLinkedBlockingQueue(int capacity)

Creates an empty LinkedBlockingQueue with the given (fixed) capacity.

Annotations
@J2ktIncompatible
@GwtIncompatible
Exceptions
IllegalArgumentException:
if capacity is less than 1
newLinkedBlockingQueueback to summary
public static <E> LinkedBlockingQueue<E> newLinkedBlockingQueue(Iterable<? extends E> elements)

Creates a LinkedBlockingQueue with a capacity of Integer#MAX_VALUE, containing the elements of the specified iterable, in the order they are returned by the iterable's iterator.

Parameters
elements:Iterable<? extends E>

the elements that the queue should contain, in order

Returns:LinkedBlockingQueue<E>

a new LinkedBlockingQueue containing those elements

Annotations
@J2ktIncompatible
@GwtIncompatible
newPriorityBlockingQueueback to summary
public static <E extends Comparable<T>> PriorityBlockingQueue<E> newPriorityBlockingQueue()

Creates an empty PriorityBlockingQueue with the ordering given by its elements' natural ordering.

Annotations
@SuppressWarnings:rawtypes
@J2ktIncompatible
@GwtIncompatible
Since
11.0 (but the bound of E was changed from Object to Comparable in 15.0)
newPriorityBlockingQueueback to summary
public static <E extends Comparable<T>> PriorityBlockingQueue<E> newPriorityBlockingQueue(Iterable<? extends E> elements)

Creates a PriorityBlockingQueue containing the given elements.

Note

If the specified iterable is a SortedSet or a PriorityQueue, this priority queue will be ordered according to the same ordering.

Annotations
@SuppressWarnings:rawtypes
@J2ktIncompatible
@GwtIncompatible
Since
11.0 (but the bound of E was changed from Object to Comparable in 15.0)
newPriorityQueueback to summary
public static <E extends Comparable<T>> PriorityQueue<E> newPriorityQueue()

Creates an empty PriorityQueue with the ordering given by its elements' natural ordering.

Annotations
@SuppressWarnings:rawtypes
Since
11.0 (but the bound of E was changed from Object to Comparable in 15.0)
newPriorityQueueback to summary
public static <E extends Comparable<T>> PriorityQueue<E> newPriorityQueue(Iterable<? extends E> elements)

Creates a PriorityQueue containing the given elements.

Note

If the specified iterable is a SortedSet or a PriorityQueue, this priority queue will be ordered according to the same ordering.

Annotations
@SuppressWarnings:rawtypes
Since
11.0 (but the bound of E was changed from Object to Comparable in 15.0)
newSynchronousQueueback to summary
public static <E> SynchronousQueue<E> newSynchronousQueue()

Creates an empty SynchronousQueue with nonfair access policy.

Annotations
@J2ktIncompatible
@GwtIncompatible
synchronizedDequeback to summary
public static <E extends @Nullable Object> Deque<E> synchronizedDeque(Deque<E> deque)

Returns a synchronized (thread-safe) deque backed by the specified deque. In order to guarantee serial access, it is critical that all access to the backing deque is accomplished through the returned deque.

It is imperative that the user manually synchronize on the returned deque when accessing any of the deque's iterators: 

Deque<E> deque = Queues.synchronizedDeque(Queues.<E>newArrayDeque());
...
deque.add(element);  // Needn't be in synchronized block
...
synchronized (deque) {  // Must synchronize on deque!
  Iterator<E> i = deque.iterator(); // Must be in synchronized block
  while (i.hasNext()) {
    foo(i.next());
  }
}

Failure to follow this advice may result in non-deterministic behavior.

The returned deque will be serializable if the specified deque is serializable.

Parameters
deque:Deque<E>

the deque to be wrapped in a synchronized view

Returns:Deque<E>

a synchronized view of the specified deque

Since
15.0
synchronizedQueueback to summary
public static <E extends @Nullable Object> Queue<E> synchronizedQueue(Queue<E> queue)

Returns a synchronized (thread-safe) queue backed by the specified queue. In order to guarantee serial access, it is critical that all access to the backing queue is accomplished through the returned queue.

It is imperative that the user manually synchronize on the returned queue when accessing the queue's iterator: 

Queue<E> queue = Queues.synchronizedQueue(MinMaxPriorityQueue.<E>create());
...
queue.add(element);  // Needn't be in synchronized block
...
synchronized (queue) {  // Must synchronize on queue!
  Iterator<E> i = queue.iterator(); // Must be in synchronized block
  while (i.hasNext()) {
    foo(i.next());
  }
}

Failure to follow this advice may result in non-deterministic behavior.

The returned queue will be serializable if the specified queue is serializable.

Parameters
queue:Queue<E>

the queue to be wrapped in a synchronized view

Returns:Queue<E>

a synchronized view of the specified queue

Since
14.0