Package com.google.common.collect

Class Queues

java.lang.Object

com.google.common.collect.Queues

@GwtCompatible(emulated=true)
public final class Queues
extends Object

Static utility methods pertaining to Queue and Deque instances. Also see this class's counterparts Lists, Sets, and Maps.

Since:

11.0

Author:

Kurt Alfred Kluever

Method Summary

Modifier and Type	Method	Description
static <E> int	drain(BlockingQueue<E> q, Collection<? super E> buffer, int numElements, long timeout, TimeUnit 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.
static <E> int	drain(BlockingQueue<E> q, Collection<? super E> buffer, int numElements, Duration 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.
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.
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.
static <E> ArrayBlockingQueue<E>	newArrayBlockingQueue(int capacity)	Creates an empty ArrayBlockingQueue with the given (fixed) capacity and nonfair access policy.
static <E> ArrayDeque<E>	newArrayDeque()	Creates an empty ArrayDeque.
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.
static <E> ConcurrentLinkedQueue<E>	newConcurrentLinkedQueue()	Creates an empty ConcurrentLinkedQueue.
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.
static <E> LinkedBlockingDeque<E>	newLinkedBlockingDeque()	Creates an empty LinkedBlockingDeque with a capacity of Integer.MAX_VALUE.
static <E> LinkedBlockingDeque<E>	newLinkedBlockingDeque(int capacity)	Creates an empty LinkedBlockingDeque with the given (fixed) capacity.
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.
static <E> LinkedBlockingQueue<E>	newLinkedBlockingQueue()	Creates an empty LinkedBlockingQueue with a capacity of Integer.MAX_VALUE.
static <E> LinkedBlockingQueue<E>	newLinkedBlockingQueue(int capacity)	Creates an empty LinkedBlockingQueue with the given (fixed) capacity.
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.
static <E extends Comparable> PriorityBlockingQueue<E>	newPriorityBlockingQueue()	Creates an empty PriorityBlockingQueue with the ordering given by its elements' natural ordering.
static <E extends Comparable> PriorityBlockingQueue<E>	newPriorityBlockingQueue(Iterable<? extends E> elements)	Creates a PriorityBlockingQueue containing the given elements.
static <E extends Comparable> PriorityQueue<E>	newPriorityQueue()	Creates an empty PriorityQueue with the ordering given by its elements' natural ordering.
static <E extends Comparable> PriorityQueue<E>	newPriorityQueue(Iterable<? extends E> elements)	Creates a PriorityQueue containing the given elements.
static <E> SynchronousQueue<E>	newSynchronousQueue()	Creates an empty SynchronousQueue with nonfair access policy.
static <E extends @Nullable Object> Deque<E>	synchronizedDeque(Deque<E> deque)	Returns a synchronized (thread-safe) deque backed by the specified deque.
static <E extends @Nullable Object> Queue<E>	synchronizedQueue(Queue<E> queue)	Returns a synchronized (thread-safe) queue backed by the specified queue.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

newArrayBlockingQueue

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

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

newArrayDeque

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

Creates an empty ArrayDeque.

Since:

12.0

newArrayDeque

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

newConcurrentLinkedQueue

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

Creates an empty ConcurrentLinkedQueue.

newConcurrentLinkedQueue

@GwtIncompatible
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.

newLinkedBlockingDeque

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

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

Since:

12.0

newLinkedBlockingDeque

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

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

Throws:

IllegalArgumentException - if capacity is less than 1

Since:

12.0

newLinkedBlockingDeque

@GwtIncompatible
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.

Since:

12.0

newLinkedBlockingQueue

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

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

newLinkedBlockingQueue

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

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

Throws:

IllegalArgumentException - if capacity is less than 1

newLinkedBlockingQueue

@GwtIncompatible
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 - the elements that the queue should contain, in order

Returns:

a new LinkedBlockingQueue containing those elements

newPriorityBlockingQueue

@GwtIncompatible
public static <E extends Comparable> PriorityBlockingQueue<E> newPriorityBlockingQueue()

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

Since:

11.0 (but the bound of E was changed from Object to Comparable in 15.0)

newPriorityBlockingQueue

@GwtIncompatible
public static <E extends Comparable> 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.

Since:

11.0 (but the bound of E was changed from Object to Comparable in 15.0)

newPriorityQueue

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

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

Since:

11.0 (but the bound of E was changed from Object to Comparable in 15.0)

newPriorityQueue

public static <E extends Comparable> 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.

Since:

11.0 (but the bound of E was changed from Object to Comparable in 15.0)

newSynchronousQueue

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

Creates an empty SynchronousQueue with nonfair access policy.

drain

@CanIgnoreReturnValue
@GwtIncompatible
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 - the blocking queue to be drained

buffer - where to add the transferred elements

numElements - the number of elements to be waited for

timeout - how long to wait before giving up

Returns:

the number of elements transferred

Throws:

InterruptedException - if interrupted while waiting

Since:

33.4.0 (but since 28.0 in the JRE flavor)

drain

@CanIgnoreReturnValue
@GwtIncompatible
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 - the blocking queue to be drained

buffer - where to add the transferred elements

numElements - the number of elements to be waited for

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

unit - a TimeUnit determining how to interpret the timeout parameter

Returns:

the number of elements transferred

Throws:

InterruptedException - if interrupted while waiting

drainUninterruptibly

@CanIgnoreReturnValue
@GwtIncompatible
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 - the blocking queue to be drained

buffer - where to add the transferred elements

numElements - the number of elements to be waited for

timeout - how long to wait before giving up

Returns:

the number of elements transferred

Since:

33.4.0 (but since 28.0 in the JRE flavor)

drainUninterruptibly

@CanIgnoreReturnValue
@GwtIncompatible
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 - the blocking queue to be drained

buffer - where to add the transferred elements

numElements - the number of elements to be waited for

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

unit - a TimeUnit determining how to interpret the timeout parameter

Returns:

the number of elements transferred

synchronizedQueue

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 - the queue to be wrapped in a synchronized view

Returns:

a synchronized view of the specified queue

Since:

14.0

synchronizedDeque

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 - the deque to be wrapped in a synchronized view

Returns:

a synchronized view of the specified deque

Since:

15.0