net.tribe7.common.collect

Class Queues

java.lang.Object

net.tribe7.common.collect.Queues

public final class Queues
extends java.lang.Object

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

Since:

11.0

Method Summary

Methods

Modifier and Type	Method and Description
static <E> int	drain(java.util.concurrent.BlockingQueue<E> q, java.util.Collection<? super E> buffer, int numElements, long timeout, java.util.concurrent.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	drainUninterruptibly(java.util.concurrent.BlockingQueue<E> q, java.util.Collection<? super E> buffer, int numElements, long timeout, java.util.concurrent.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> java.util.concurrent.ArrayBlockingQueue<E>	newArrayBlockingQueue(int capacity) Creates an empty ArrayBlockingQueue instance.
static <E> java.util.ArrayDeque<E>	newArrayDeque() Creates an empty ArrayDeque instance.
static <E> java.util.ArrayDeque<E>	newArrayDeque(java.lang.Iterable<? extends E> elements) Creates an ArrayDeque instance containing the given elements.
static <E> java.util.concurrent.ConcurrentLinkedQueue<E>	newConcurrentLinkedQueue() Creates an empty ConcurrentLinkedQueue instance.
static <E> java.util.concurrent.ConcurrentLinkedQueue<E>	newConcurrentLinkedQueue(java.lang.Iterable<? extends E> elements) Creates an ConcurrentLinkedQueue instance containing the given elements.
static <E> java.util.concurrent.LinkedBlockingDeque<E>	newLinkedBlockingDeque() Creates an empty LinkedBlockingDeque instance.
static <E> java.util.concurrent.LinkedBlockingDeque<E>	newLinkedBlockingDeque(int capacity) Creates a LinkedBlockingDeque with the given (fixed) capacity.
static <E> java.util.concurrent.LinkedBlockingDeque<E>	newLinkedBlockingDeque(java.lang.Iterable<? extends E> elements) Creates an LinkedBlockingDeque instance containing the given elements.
static <E> java.util.concurrent.LinkedBlockingQueue<E>	newLinkedBlockingQueue() Creates an empty LinkedBlockingQueue instance.
static <E> java.util.concurrent.LinkedBlockingQueue<E>	newLinkedBlockingQueue(int capacity) Creates a LinkedBlockingQueue with the given (fixed) capacity.
static <E> java.util.concurrent.LinkedBlockingQueue<E>	newLinkedBlockingQueue(java.lang.Iterable<? extends E> elements) Creates an LinkedBlockingQueue instance containing the given elements.
static <E> java.util.concurrent.PriorityBlockingQueue<E>	newPriorityBlockingQueue() Creates an empty PriorityBlockingQueue instance.
static <E> java.util.concurrent.PriorityBlockingQueue<E>	newPriorityBlockingQueue(java.lang.Iterable<? extends E> elements) Creates an PriorityBlockingQueue instance containing the given elements.
static <E> java.util.PriorityQueue<E>	newPriorityQueue() Creates an empty PriorityQueue instance.
static <E> java.util.PriorityQueue<E>	newPriorityQueue(java.lang.Iterable<? extends E> elements) Creates an PriorityQueue instance containing the given elements.
static <E> java.util.concurrent.SynchronousQueue<E>	newSynchronousQueue() Creates an empty SynchronousQueue instance.
static <E> java.util.Queue<E>	synchronizedQueue(java.util.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

public static <E> java.util.concurrent.ArrayBlockingQueue<E> newArrayBlockingQueue(int capacity)

Creates an empty ArrayBlockingQueue instance.

Returns:

a new, empty ArrayBlockingQueue

newArrayDeque

public static <E> java.util.ArrayDeque<E> newArrayDeque()

Creates an empty ArrayDeque instance.

Returns:

a new, empty ArrayDeque

Since:

12.0

newArrayDeque

public static <E> java.util.ArrayDeque<E> newArrayDeque(java.lang.Iterable<? extends E> elements)

Creates an ArrayDeque instance containing the given elements.

Parameters:

elements - the elements that the queue should contain, in order

Returns:

a new ArrayDeque containing those elements

Since:

12.0

newConcurrentLinkedQueue

public static <E> java.util.concurrent.ConcurrentLinkedQueue<E> newConcurrentLinkedQueue()

Creates an empty ConcurrentLinkedQueue instance.

Returns:

a new, empty ConcurrentLinkedQueue

newConcurrentLinkedQueue

public static <E> java.util.concurrent.ConcurrentLinkedQueue<E> newConcurrentLinkedQueue(java.lang.Iterable<? extends E> elements)

Creates an ConcurrentLinkedQueue instance containing the given elements.

Parameters:

elements - the elements that the queue should contain, in order

Returns:

a new ConcurrentLinkedQueue containing those elements

newLinkedBlockingDeque

public static <E> java.util.concurrent.LinkedBlockingDeque<E> newLinkedBlockingDeque()

Creates an empty LinkedBlockingDeque instance.

Returns:

a new, empty LinkedBlockingDeque

Since:

12.0

newLinkedBlockingDeque

public static <E> java.util.concurrent.LinkedBlockingDeque<E> newLinkedBlockingDeque(int capacity)

Creates a LinkedBlockingDeque with the given (fixed) capacity.

Parameters:

capacity - the capacity of this deque

Returns:

a new, empty LinkedBlockingDeque

Throws:

java.lang.IllegalArgumentException - if capacity is less than 1

Since:

12.0

newLinkedBlockingDeque

public static <E> java.util.concurrent.LinkedBlockingDeque<E> newLinkedBlockingDeque(java.lang.Iterable<? extends E> elements)

Creates an LinkedBlockingDeque instance containing the given elements.

Parameters:

elements - the elements that the queue should contain, in order

Returns:

a new LinkedBlockingDeque containing those elements

Since:

12.0

newLinkedBlockingQueue

public static <E> java.util.concurrent.LinkedBlockingQueue<E> newLinkedBlockingQueue()

Creates an empty LinkedBlockingQueue instance.

Returns:

a new, empty LinkedBlockingQueue

newLinkedBlockingQueue

public static <E> java.util.concurrent.LinkedBlockingQueue<E> newLinkedBlockingQueue(int capacity)

Creates a LinkedBlockingQueue with the given (fixed) capacity.

Parameters:

capacity - the capacity of this queue

Returns:

a new, empty LinkedBlockingQueue

Throws:

java.lang.IllegalArgumentException - if capacity is less than 1

newLinkedBlockingQueue

public static <E> java.util.concurrent.LinkedBlockingQueue<E> newLinkedBlockingQueue(java.lang.Iterable<? extends E> elements)

Creates an LinkedBlockingQueue instance containing the given elements.

Parameters:

elements - the elements that the queue should contain, in order

Returns:

a new LinkedBlockingQueue containing those elements

newPriorityBlockingQueue

public static <E> java.util.concurrent.PriorityBlockingQueue<E> newPriorityBlockingQueue()

Creates an empty PriorityBlockingQueue instance.

Returns:

a new, empty PriorityBlockingQueue

newPriorityBlockingQueue

public static <E> java.util.concurrent.PriorityBlockingQueue<E> newPriorityBlockingQueue(java.lang.Iterable<? extends E> elements)

Creates an PriorityBlockingQueue instance containing the given elements.

Parameters:

elements - the elements that the queue should contain, in order

Returns:

a new PriorityBlockingQueue containing those elements

newPriorityQueue

public static <E> java.util.PriorityQueue<E> newPriorityQueue()

Creates an empty PriorityQueue instance.

Returns:

a new, empty PriorityQueue

newPriorityQueue

public static <E> java.util.PriorityQueue<E> newPriorityQueue(java.lang.Iterable<? extends E> elements)

Creates an PriorityQueue instance containing the given elements.

Parameters:

elements - the elements that the queue should contain, in order

Returns:

a new PriorityQueue containing those elements

newSynchronousQueue

public static <E> java.util.concurrent.SynchronousQueue<E> newSynchronousQueue()

Creates an empty SynchronousQueue instance.

Returns:

a new, empty SynchronousQueue

drain

@Beta
public static <E> int drain(java.util.concurrent.BlockingQueue<E> q,
                 java.util.Collection<? super E> buffer,
                 int numElements,
                 long timeout,
                 java.util.concurrent.TimeUnit unit)
                 throws java.lang.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:

java.lang.InterruptedException - if interrupted while waiting

drainUninterruptibly

@Beta
public static <E> int drainUninterruptibly(java.util.concurrent.BlockingQueue<E> q,
                                java.util.Collection<? super E> buffer,
                                int numElements,
                                long timeout,
                                java.util.concurrent.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

@Beta
public static <E> java.util.Queue<E> synchronizedQueue(java.util.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