Queues
Date: 2016-05-24

com.google.common.collect

## Class Queues

- java.lang.Object
- - com.google.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` with the given (fixed) capacity and nonfair access policy.
    `static <E> java.util.ArrayDeque<E>` | `newArrayDeque()` Creates an empty `ArrayDeque`.
    `static <E> java.util.ArrayDeque<E>` | `newArrayDeque(java.lang.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> java.util.concurrent.ConcurrentLinkedQueue<E>` | `newConcurrentLinkedQueue()` Creates an empty `ConcurrentLinkedQueue`.
    `static <E> java.util.concurrent.ConcurrentLinkedQueue<E>` | `newConcurrentLinkedQueue(java.lang.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> java.util.concurrent.LinkedBlockingDeque<E>` | `newLinkedBlockingDeque()` Creates an empty `LinkedBlockingDeque` with a capacity of `Integer.MAX_VALUE`.
    `static <E> java.util.concurrent.LinkedBlockingDeque<E>` | `newLinkedBlockingDeque(int capacity)` Creates an empty `LinkedBlockingDeque` with the given (fixed) capacity.
    `static <E> java.util.concurrent.LinkedBlockingDeque<E>` | `newLinkedBlockingDeque(java.lang.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> java.util.concurrent.LinkedBlockingQueue<E>` | `newLinkedBlockingQueue()` Creates an empty `LinkedBlockingQueue` with a capacity of `Integer.MAX_VALUE`.
    `static <E> java.util.concurrent.LinkedBlockingQueue<E>` | `newLinkedBlockingQueue(int capacity)` Creates an empty `LinkedBlockingQueue` with the given (fixed) capacity.
    `static <E> java.util.concurrent.LinkedBlockingQueue<E>` | `newLinkedBlockingQueue(java.lang.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 java.lang.Comparable> java.util.concurrent.PriorityBlockingQueue<E>` | `newPriorityBlockingQueue()` Creates an empty `PriorityBlockingQueue` with the ordering given by its elements' natural ordering.
    `static <E extends java.lang.Comparable> java.util.concurrent.PriorityBlockingQueue<E>` | `newPriorityBlockingQueue(java.lang.Iterable<? extends E> elements)` Creates a `PriorityBlockingQueue` containing the given elements.
    `static <E extends java.lang.Comparable> java.util.PriorityQueue<E>` | `newPriorityQueue()` Creates an empty `PriorityQueue` with the ordering given by its elements' natural ordering.
    `static <E extends java.lang.Comparable> java.util.PriorityQueue<E>` | `newPriorityQueue(java.lang.Iterable<? extends E> elements)` Creates a `PriorityQueue` containing the given elements.
    `static <E> java.util.concurrent.SynchronousQueue<E>` | `newSynchronousQueue()` Creates an empty `SynchronousQueue` with nonfair access policy.
    `static <E> java.util.Deque<E>` | `synchronizedDeque(java.util.Deque<E> deque)` Returns a synchronized (thread-safe) deque backed by the specified deque.
    `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` with the given (fixed) capacity and nonfair access policy.

    - #### newArrayDeque

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

      Creates an empty `ArrayDeque`.
      Since:
        12.0

    - #### newArrayDeque

          public static <E> java.util.ArrayDeque<E> newArrayDeque(java.lang.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

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

      Creates an empty `ConcurrentLinkedQueue`.

    - #### newConcurrentLinkedQueue

          public static <E> java.util.concurrent.ConcurrentLinkedQueue<E> newConcurrentLinkedQueue(java.lang.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

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

      Creates an empty `LinkedBlockingDeque` with a capacity of `Integer.MAX_VALUE`.
      Since:
        12.0

    - #### newLinkedBlockingDeque

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

      Creates an empty `LinkedBlockingDeque` with the given (fixed) capacity.
      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 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

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

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

    - #### newLinkedBlockingQueue

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

      Creates an empty `LinkedBlockingQueue` with the given (fixed) capacity.
      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 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

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

      Creates an empty `PriorityBlockingQueue` with the ordering given by its elements' natural ordering.
      Since:
        11.0 (requires that `E` be `Comparable` since 15.0).

    - #### newPriorityBlockingQueue

          public static <E extends java.lang.Comparable> java.util.concurrent.PriorityBlockingQueue<E> newPriorityBlockingQueue(java.lang.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 (requires that `E` be `Comparable` since 15.0).

    - #### newPriorityQueue

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

      Creates an empty `PriorityQueue` with the ordering given by its elements' natural ordering.
      Since:
        11.0 (requires that `E` be `Comparable` since 15.0).

    - #### newPriorityQueue

          public static <E extends java.lang.Comparable> java.util.PriorityQueue<E> newPriorityQueue(java.lang.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 (requires that `E` be `Comparable` since 15.0).

    - #### newSynchronousQueue

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

      Creates an empty `SynchronousQueue` with nonfair access policy.

    - #### 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

          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

    - #### synchronizedDeque

          public static <E> java.util.Deque<E> synchronizedDeque(java.util.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