/*

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code is distributed in the hope that it will be useful, but WITHOUT

 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

/*

 * This file is available under and governed by the GNU General Public

 * License version 2 only, as published by the Free Software Foundation.

 * However, the following notice accompanied the original version of this

 * file:

 *

 * Written by Doug Lea with assistance from members of JCP JSR-166

 * Expert Group and released to the public domain, as explained at

 * http://creativecommons.org/publicdomain/zero/1.0/

 */

package java.util.concurrent;

import java.util.concurrent.locks.*;

import java.util.*;

/**

 * An unbounded {@linkplain BlockingQueue blocking queue} that uses

 * the same ordering rules as class {@link PriorityQueue} and supplies

 * blocking retrieval operations.  While this queue is logically

 * unbounded, attempted additions may fail due to resource exhaustion

 * (causing {@code OutOfMemoryError}). This class does not permit

 * {@code null} elements.  A priority queue relying on {@linkplain

 * Comparable natural ordering} also does not permit insertion of

 * non-comparable objects (doing so results in

 * {@code ClassCastException}).

 *

 * <p>This class and its iterator implement all of the

 * <em>optional</em> methods of the {@link Collection} and {@link

 * Iterator} interfaces.  The Iterator provided in method {@link

 * #iterator()} is <em>not</em> guaranteed to traverse the elements of

 * the PriorityBlockingQueue in any particular order. If you need

 * ordered traversal, consider using

 * {@code Arrays.sort(pq.toArray())}.  Also, method {@code drainTo}

 * can be used to <em>remove</em> some or all elements in priority

 * order and place them in another collection.

 *

 * <p>Operations on this class make no guarantees about the ordering

 * of elements with equal priority. If you need to enforce an

 * ordering, you can define custom classes or comparators that use a

 * secondary key to break ties in primary priority values.  For

 * example, here is a class that applies first-in-first-out

 * tie-breaking to comparable elements. To use it, you would insert a

 * {@code new FIFOEntry(anEntry)} instead of a plain entry object.

 *

 *  <pre> {@code

 * class FIFOEntry<E extends Comparable<? super E>>

 *     implements Comparable<FIFOEntry<E>> {

 *   static final AtomicLong seq = new AtomicLong(0);

 *   final long seqNum;

 *   final E entry;

 *   public FIFOEntry(E entry) {

 *     seqNum = seq.getAndIncrement();

 *     this.entry = entry;

 *   }

 *   public E getEntry() { return entry; }

 *   public int compareTo(FIFOEntry<E> other) {

 *     int res = entry.compareTo(other.entry);

 *     if (res == 0 && other.entry != this.entry)

 *       res = (seqNum < other.seqNum ? -1 : 1);

 *     return res;

 *   }

 * }}</pre>

 *

 * <p>This class is a member of the

 * <a href="{@docRoot}/../technotes/guides/collections/index.html">

 * Java Collections Framework</a>.

 *

 * @since 1.5

 * @author Doug Lea

 * @param <E> the type of elements held in this collection

 */

public class PriorityBlockingQueue<E> extends AbstractQueue<E>

    implements BlockingQueue<E>, java.io.Serializable {

    private static final long serialVersionUID = 5595510919245408276L;

    /*

     * The implementation uses an array-based binary heap, with public

     * operations protected with a single lock. However, allocation

     * during resizing uses a simple spinlock (used only while not

     * holding main lock) in order to allow takes to operate

     * concurrently with allocation.  This avoids repeated

     * postponement of waiting consumers and consequent element

     * build-up. The need to back away from lock during allocation

     * makes it impossible to simply wrap delegated

     * java.util.PriorityQueue operations within a lock, as was done

     * in a previous version of this class. To maintain

     * interoperability, a plain PriorityQueue is still used during

     * serialization, which maintains compatibility at the espense of

     * transiently doubling overhead.

     */

    /**

     * Default array capacity.

     */

    private static final int DEFAULT_INITIAL_CAPACITY = 11;

    /**

     * The maximum size of array to allocate.

     * Some VMs reserve some header words in an array.

     * Attempts to allocate larger arrays may result in

     * OutOfMemoryError: Requested array size exceeds VM limit

     */

    private static final int MAX_ARRAY_SIZE = Integer.MAX_VALUE - 8;

    /**

     * Priority queue represented as a balanced binary heap: the two

     * children of queue[n] are queue[2*n+1] and queue[2*(n+1)].  The

     * priority queue is ordered by comparator, or by the elements'

     * natural ordering, if comparator is null: For each node n in the

     * heap and each descendant d of n, n <= d.  The element with the

     * lowest value is in queue[0], assuming the queue is nonempty.

     */

    private transient Object[] queue;

    /**

     * The number of elements in the priority queue.

     */

    private transient int size;

    /**

     * The comparator, or null if priority queue uses elements'

     * natural ordering.

     */

    private transient Comparator<? super E> comparator;

    /**

     * Lock used for all public operations

     */

    private final ReentrantLock lock;

    /**

     * Condition for blocking when empty

     */

    private final Condition notEmpty;

    /**

     * Spinlock for allocation, acquired via CAS.

     */

    private transient volatile int allocationSpinLock;

    /**

     * A plain PriorityQueue used only for serialization,

     * to maintain compatibility with previous versions

     * of this class. Non-null only during serialization/deserialization.

     */

    private PriorityQueue q;

    /**

     * Creates a {@code PriorityBlockingQueue} with the default

     * initial capacity (11) that orders its elements according to

     * their {@linkplain Comparable natural ordering}.

     */

    public PriorityBlockingQueue() {

        this(DEFAULT_INITIAL_CAPACITY, null);

    }

    /**

     * Creates a {@code PriorityBlockingQueue} with the specified

     * initial capacity that orders its elements according to their

     * {@linkplain Comparable natural ordering}.

     *

     * @param initialCapacity the initial capacity for this priority queue

     * @throws IllegalArgumentException if {@code initialCapacity} is less

     *         than 1

     */

    public PriorityBlockingQueue(int initialCapacity) {

        this(initialCapacity, null);

    }

    /**

     * Creates a {@code PriorityBlockingQueue} with the specified initial

     * capacity that orders its elements according to the specified

     * comparator.

     *

     * @param initialCapacity the initial capacity for this priority queue

     * @param  comparator the comparator that will be used to order this

     *         priority queue.  If {@code null}, the {@linkplain Comparable

     *         natural ordering} of the elements will be used.

     * @throws IllegalArgumentException if {@code initialCapacity} is less

     *         than 1

     */

    public PriorityBlockingQueue(int initialCapacity,

                                 Comparator<? super E> comparator) {

        if (initialCapacity < 1)

            throw new IllegalArgumentException();

        this.lock = new ReentrantLock();

        this.notEmpty = lock.newCondition();

        this.comparator = comparator;

        this.queue = new Object[initialCapacity];

    }

    /**

     * Creates a {@code PriorityBlockingQueue} containing the elements

     * in the specified collection.  If the specified collection is a

     * {@link SortedSet} or a {@link PriorityQueue},  this

     * priority queue will be ordered according to the same ordering.

     * Otherwise, this priority queue will be ordered according to the

     * {@linkplain Comparable natural ordering} of its elements.

     *

     * @param  c the collection whose elements are to be placed

     *         into this priority queue

     * @throws ClassCastException if elements of the specified collection

     *         cannot be compared to one another according to the priority

     *         queue's ordering

     * @throws NullPointerException if the specified collection or any

     *         of its elements are null

     */

    public PriorityBlockingQueue(Collection<? extends E> c) {

        this.lock = new ReentrantLock();

        this.notEmpty = lock.newCondition();

        boolean heapify = true; // true if not known to be in heap order

        boolean screen = true;  // true if must screen for nulls

        if (c instanceof SortedSet<?>) {

            SortedSet<? extends E> ss = (SortedSet<? extends E>) c;

            this.comparator = (Comparator<? super E>) ss.comparator();

            heapify = false;

        }

        else if (c instanceof PriorityBlockingQueue<?>) {

            PriorityBlockingQueue<? extends E> pq =

                (PriorityBlockingQueue<? extends E>) c;

            this.comparator = (Comparator<? super E>) pq.comparator();

            screen = false;

            if (pq.getClass() == PriorityBlockingQueue.class) // exact match

                heapify = false;

        }

        Object[] a = c.toArray();

        int n = a.length;

        // If c.toArray incorrectly doesn't return Object[], copy it.

        if (a.getClass() != Object[].class)

            a = Arrays.copyOf(a, n, Object[].class);

        if (screen && (n == 1 || this.comparator != null)) {

            for (int i = 0; i < n; ++i)

                if (a[i] == null)

                    throw new NullPointerException();

        }

        this.queue = a;

        this.size = n;

        if (heapify)

            heapify();

    }

    /**

     * Tries to grow array to accommodate at least one more element

     * (but normally expand by about 50%), giving up (allowing retry)

     * on contention (which we expect to be rare). Call only while

     * holding lock.

     *

     * @param array the heap array

     * @param oldCap the length of the array

     */

    private void tryGrow(Object[] array, int oldCap) {

        lock.unlock(); // must release and then re-acquire main lock

        Object[] newArray = null;

        if (allocationSpinLock == 0) {

            allocationSpinLock = 1;

            try {

                int newCap = oldCap + ((oldCap < 64) ?

                                       (oldCap + 2) : // grow faster if small

                                       (oldCap >> 1));

                if (newCap - MAX_ARRAY_SIZE > 0) {    // possible overflow

                    int minCap = oldCap + 1;

                    if (minCap < 0 || minCap > MAX_ARRAY_SIZE)

                        throw new OutOfMemoryError();

                    newCap = MAX_ARRAY_SIZE;

                }

                if (newCap > oldCap && queue == array)

                    newArray = new Object[newCap];

            } finally {

                allocationSpinLock = 0;

            }

        }

        if (newArray == null) // back off if another thread is allocating

            Thread.yield();

        lock.lock();

        if (newArray != null && queue == array) {

            queue = newArray;

            System.arraycopy(array, 0, newArray, 0, oldCap);

        }

    }

    /**

     * Mechanics for poll().  Call only while holding lock.

     */

    private E extract() {

        E result;

        int n = size - 1;

        if (n < 0)

            result = null;

        else {

            Object[] array = queue;

            result = (E) array[0];

            E x = (E) array[n];

            array[n] = null;

            Comparator<? super E> cmp = comparator;

            if (cmp == null)

                siftDownComparable(0, x, array, n);

            else

                siftDownUsingComparator(0, x, array, n, cmp);

            size = n;

        }

        return result;

    }

    /**

     * Inserts item x at position k, maintaining heap invariant by

     * promoting x up the tree until it is greater than or equal to

     * its parent, or is the root.

     *

     * To simplify and speed up coercions and comparisons. the

     * Comparable and Comparator versions are separated into different

     * methods that are otherwise identical. (Similarly for siftDown.)

     * These methods are static, with heap state as arguments, to

     * simplify use in light of possible comparator exceptions.

     *

     * @param k the position to fill

     * @param x the item to insert

     * @param array the heap array

     * @param n heap size

     */

    private static <T> void siftUpComparable(int k, T x, Object[] array) {

        Comparable<? super T> key = (Comparable<? super T>) x;

        while (k > 0) {

            int parent = (k - 1) >>> 1;

            Object e = array[parent];

            if (key.compareTo((T) e) >= 0)

                break;

            array[k] = e;

            k = parent;

        }

        array[k] = key;

    }

    private static <T> void siftUpUsingComparator(int k, T x, Object[] array,

                                       Comparator<? super T> cmp) {

        while (k > 0) {

            int parent = (k - 1) >>> 1;

            Object e = array[parent];

            if (cmp.compare(x, (T) e) >= 0)

                break;

            array[k] = e;

            k = parent;

        }

        array[k] = x;

    }

    /**

     * Inserts item x at position k, maintaining heap invariant by

     * demoting x down the tree repeatedly until it is less than or

     * equal to its children or is a leaf.

     *

     * @param k the position to fill

     * @param x the item to insert

     * @param array the heap array

     * @param n heap size

     */

    private static <T> void siftDownComparable(int k, T x, Object[] array,

                                               int n) {

        Comparable<? super T> key = (Comparable<? super T>)x;

        int half = n >>> 1;           // loop while a non-leaf

        while (k < half) {

            int child = (k << 1) + 1; // assume left child is least

            Object c = array[child];

            int right = child + 1;

            if (right < n &&

                ((Comparable<? super T>) c).compareTo((T) array[right]) > 0)

                c = array[child = right];

            if (key.compareTo((T) c) <= 0)

                break;

            array[k] = c;

            k = child;

        }

        array[k] = key;

    }

    private static <T> void siftDownUsingComparator(int k, T x, Object[] array,

                                                    int n,

                                                    Comparator<? super T> cmp) {

        int half = n >>> 1;

        while (k < half) {

            int child = (k << 1) + 1;

            Object c = array[child];

            int right = child + 1;

            if (right < n && cmp.compare((T) c, (T) array[right]) > 0)

                c = array[child = right];

            if (cmp.compare(x, (T) c) <= 0)

                break;

            array[k] = c;

            k = child;

        }

        array[k] = x;

    }

    /**

     * Establishes the heap invariant (described above) in the entire tree,

     * assuming nothing about the order of the elements prior to the call.

     */

    private void heapify() {

        Object[] array = queue;

        int n = size;

        int half = (n >>> 1) - 1;

        Comparator<? super E> cmp = comparator;

        if (cmp == null) {

            for (int i = half; i >= 0; i--)

                siftDownComparable(i, (E) array[i], array, n);

        }

        else {

            for (int i = half; i >= 0; i--)

                siftDownUsingComparator(i, (E) array[i], array, n, cmp);

        }

    }

    /**

     * Inserts the specified element into this priority queue.

     *

     * @param e the element to add

     * @return {@code true} (as specified by {@link Collection#add})

     * @throws ClassCastException if the specified element cannot be compared

     *         with elements currently in the priority queue according to the

     *         priority queue's ordering

     * @throws NullPointerException if the specified element is null

     */

    public boolean add(E e) {

        return offer(e);

    }

    /**

     * Inserts the specified element into this priority queue.

     * As the queue is unbounded, this method will never return {@code false}.

     *

     * @param e the element to add

     * @return {@code true} (as specified by {@link Queue#offer})

     * @throws ClassCastException if the specified element cannot be compared

     *         with elements currently in the priority queue according to the

     *         priority queue's ordering

     * @throws NullPointerException if the specified element is null

     */

    public boolean offer(E e) {

        if (e == null)

            throw new NullPointerException();

        final ReentrantLock lock = this.lock;

        lock.lock();

        int n, cap;

        Object[] array;

        while ((n = size) >= (cap = (array = queue).length))

            tryGrow(array, cap);

        try {

            Comparator<? super E> cmp = comparator;

            if (cmp == null)

                siftUpComparable(n, e, array);

            else

                siftUpUsingComparator(n, e, array, cmp);

            size = n + 1;

            notEmpty.signal();

        } finally {

            lock.unlock();

        }

        return true;

    }

    /**

     * Inserts the specified element into this priority queue.

     * As the queue is unbounded, this method will never block.

     *

     * @param e the element to add

     * @throws ClassCastException if the specified element cannot be compared

     *         with elements currently in the priority queue according to the

     *         priority queue's ordering

     * @throws NullPointerException if the specified element is null

     */

    public void put(E e) {

        offer(e); // never need to block

    }

    /**

     * Inserts the specified element into this priority queue.

     * As the queue is unbounded, this method will never block or

     * return {@code false}.

     *

     * @param e the element to add

     * @param timeout This parameter is ignored as the method never blocks

     * @param unit This parameter is ignored as the method never blocks

     * @return {@code true} (as specified by

     *  {@link BlockingQueue#offer(Object,long,TimeUnit) BlockingQueue.offer})

     * @throws ClassCastException if the specified element cannot be compared

     *         with elements currently in the priority queue according to the

     *         priority queue's ordering

     * @throws NullPointerException if the specified element is null

     */

    public boolean offer(E e, long timeout, TimeUnit unit) {

        return offer(e); // never need to block

    }

    public E poll() {

        final ReentrantLock lock = this.lock;

        lock.lock();

        E result;

        try {

            result = extract();

        } finally {

            lock.unlock();

        }

        return result;

    }

    public E take() throws InterruptedException {

        final ReentrantLock lock = this.lock;

        lock.lockInterruptibly();

        E result;

        try {

            while ( (result = extract()) == null)

                notEmpty.await();

        } finally {

            lock.unlock();

        }

        return result;

    }

    public E poll(long timeout, TimeUnit unit) throws InterruptedException {

        long nanos = unit.toNanos(timeout);

        final ReentrantLock lock = this.lock;

        lock.lockInterruptibly();

        E result;

        try {

            while ( (result = extract()) == null && nanos > 0)

                nanos = notEmpty.awaitNanos(nanos);

        } finally {

            lock.unlock();

        }

        return result;

    }

    public E peek() {

        final ReentrantLock lock = this.lock;

        lock.lock();

        E result;

        try {

            result = size > 0 ? (E) queue[0] : null;

        } finally {

            lock.unlock();

        }

        return result;

    }

    /**

     * Returns the comparator used to order the elements in this queue,

     * or {@code null} if this queue uses the {@linkplain Comparable

     * natural ordering} of its elements.

     *

     * @return the comparator used to order the elements in this queue,

     *         or {@code null} if this queue uses the natural

     *         ordering of its elements

     */

    public Comparator<? super E> comparator() {

        return comparator;

    }

    public int size() {

        final ReentrantLock lock = this.lock;

        lock.lock();

        try {

            return size;

        } finally {

            lock.unlock();

        }

    }

    /**

     * Always returns {@code Integer.MAX_VALUE} because

     * a {@code PriorityBlockingQueue} is not capacity constrained.

     * @return {@code Integer.MAX_VALUE} always

     */

    public int remainingCapacity() {

        return Integer.MAX_VALUE;

    }

    private int indexOf(Object o) {

        if (o != null) {

            Object[] array = queue;

            int n = size;

            for (int i = 0; i < n; i++)

                if (o.equals(array[i]))

                    return i;

        }

        return -1;

    }

    /**

     * Removes the ith element from queue.

     */

    private void removeAt(int i) {

        Object[] array = queue;

        int n = size - 1;

        if (n == i) // removed last element

            array[i] = null;

        else {

            E moved = (E) array[n];

            array[n] = null;

            Comparator<? super E> cmp = comparator;

            if (cmp == null)

                siftDownComparable(i, moved, array, n);

            else

                siftDownUsingComparator(i, moved, array, n, cmp);

            if (array[i] == moved) {

                if (cmp == null)

                    siftUpComparable(i, moved, array);

                else

                    siftUpUsingComparator(i, moved, array, cmp);

            }

        }

        size = n;

    }

    /**

     * Removes a single instance of the specified element from this queue,

     * if it is present.  More formally, removes an element {@code e} such

     * that {@code o.equals(e)}, if this queue contains one or more such

     * elements.  Returns {@code true} if and only if this queue contained

     * the specified element (or equivalently, if this queue changed as a

     * result of the call).

     *

     * @param o element to be removed from this queue, if present

     * @return {@code true} if this queue changed as a result of the call

     */

    public boolean remove(Object o) {

        boolean removed = false;

        final ReentrantLock lock = this.lock;

        lock.lock();

        try {

            int i = indexOf(o);

            if (i != -1) {

                removeAt(i);

                removed = true;

            }

        } finally {

            lock.unlock();

        }

        return removed;

    }

    /**

     * Identity-based version for use in Itr.remove

     */

    private void removeEQ(Object o) {

        final ReentrantLock lock = this.lock;

        lock.lock();

        try {

            Object[] array = queue;

            int n = size;

            for (int i = 0; i < n; i++) {

                if (o == array[i]) {

                    removeAt(i);

                    break;

                }

            }

        } finally {

            lock.unlock();

        }

    }

    /**

     * Returns {@code true} if this queue contains the specified element.

     * More formally, returns {@code true} if and only if this queue contains

     * at least one element {@code e} such that {@code o.equals(e)}.

     *

     * @param o object to be checked for containment in this queue

     * @return {@code true} if this queue contains the specified element

     */

    public boolean contains(Object o) {

        int index;

        final ReentrantLock lock = this.lock;

        lock.lock();

        try {

            index = indexOf(o);

        } finally {

            lock.unlock();

        }

        return index != -1;

    }

    /**

     * Returns an array containing all of the elements in this queue.

     * The returned array elements are in no particular order.

     *

     * <p>The returned array will be "safe" in that no references to it are

     * maintained by this queue.  (In other words, this method must allocate

     * a new array).  The caller is thus free to modify the returned array.

     *

     * <p>This method acts as bridge between array-based and collection-based

     * APIs.

     *

     * @return an array containing all of the elements in this queue

     */

    public Object[] toArray() {

        final ReentrantLock lock = this.lock;

        lock.lock();

        try {

            return Arrays.copyOf(queue, size);

        } finally {

            lock.unlock();

        }

    }

    public String toString() {

        final ReentrantLock lock = this.lock;

        lock.lock();

        try {

            int n = size;

            if (n == 0)

                return "[]";

            StringBuilder sb = new StringBuilder();

            sb.append('[');

            for (int i = 0; i < n; ++i) {

                E e = (E)queue[i];

                sb.append(e == this ? "(this Collection)" : e);

                if (i != n - 1)

                    sb.append(',').append(' ');

            }

            return sb.append(']').toString();

        } finally {

            lock.unlock();

        }

    }

    /**

     * @throws UnsupportedOperationException {@inheritDoc}

     * @throws ClassCastException            {@inheritDoc}

     * @throws NullPointerException          {@inheritDoc}

     * @throws IllegalArgumentException      {@inheritDoc}

     */

    public int drainTo(Collection<? super E> c) {

        if (c == null)

            throw new NullPointerException();

        if (c == this)

            throw new IllegalArgumentException();

        final ReentrantLock lock = this.lock;

        lock.lock();

        try {

            int n = 0;

            E e;

            while ( (e = extract()) != null) {

                c.add(e);

                ++n;

            }

            return n;

        } finally {

            lock.unlock();

        }

    }

    /**

     * @throws UnsupportedOperationException {@inheritDoc}

     * @throws ClassCastException            {@inheritDoc}

     * @throws NullPointerException          {@inheritDoc}

     * @throws IllegalArgumentException      {@inheritDoc}

     */

    public int drainTo(Collection<? super E> c, int maxElements) {

        if (c == null)

            throw new NullPointerException();

        if (c == this)

            throw new IllegalArgumentException();

        if (maxElements <= 0)

            return 0;

        final ReentrantLock lock = this.lock;

        lock.lock();

        try {

            int n = 0;

            E e;

            while (n < maxElements && (e = extract()) != null) {

                c.add(e);

                ++n;

            }

            return n;

        } finally {

            lock.unlock();

        }

    }

    /**

     * Atomically removes all of the elements from this queue.

     * The queue will be empty after this call returns.

     */

    public void clear() {

        final ReentrantLock lock = this.lock;

        lock.lock();

        try {

            Object[] array = queue;

            int n = size;

            size = 0;

            for (int i = 0; i < n; i++)

                array[i] = null;

        } finally {

            lock.unlock();

        }

    }

    /**

     * Returns an array containing all of the elements in this queue; the

     * runtime type of the returned array is that of the specified array.

     * The returned array elements are in no particular order.

     * If the queue fits in the specified array, it is returned therein.

     * Otherwise, a new array is allocated with the runtime type of the

     * specified array and the size of this queue.

     *

     * <p>If this queue fits in the specified array with room to spare

     * (i.e., the array has more elements than this queue), the element in

     * the array immediately following the end of the queue is set to

     * {@code null}.

     *

     * <p>Like the {@link #toArray()} method, this method acts as bridge between

     * array-based and collection-based APIs.  Further, this method allows

     * precise control over the runtime type of the output array, and may,

     * under certain circumstances, be used to save allocation costs.

     *

     * <p>Suppose {@code x} is a queue known to contain only strings.

     * The following code can be used to dump the queue into a newly

     * allocated array of {@code String}:

     *

     * <pre>

     *     String[] y = x.toArray(new String[0]);</pre>

     *

     * Note that {@code toArray(new Object[0])} is identical in function to

     * {@code toArray()}.

     *

     * @param a the array into which the elements of the queue are to

     *          be stored, if it is big enough; otherwise, a new array of the

     *          same runtime type is allocated for this purpose

     * @return an array containing all of the elements in this queue

     * @throws ArrayStoreException if the runtime type of the specified array

     *         is not a supertype of the runtime type of every element in

     *         this queue

     * @throws NullPointerException if the specified array is null

     */

    public <T> T[] toArray(T[] a) {

        final ReentrantLock lock = this.lock;

        lock.lock();

        try {

            int n = size;

            if (a.length < n)

                // Make a new array of a's runtime type, but my contents:

                return (T[]) Arrays.copyOf(queue, size, a.getClass());

            System.arraycopy(queue, 0, a, 0, n);

            if (a.length > n)

                a[n] = null;

            return a;

        } finally {

            lock.unlock();

        }

    }

    /**

     * Returns an iterator over the elements in this queue. The

     * iterator does not return the elements in any particular order.

     *

     * <p>The returned iterator is a "weakly consistent" iterator that

     * will never throw {@link java.util.ConcurrentModificationException

     * ConcurrentModificationException}, and guarantees to traverse

     * elements as they existed upon construction of the iterator, and

     * may (but is not guaranteed to) reflect any modifications

     * subsequent to construction.

     *

     * @return an iterator over the elements in this queue

     */

    public Iterator<E> iterator() {

        return new Itr(toArray());

    }

    /**

     * Snapshot iterator that works off copy of underlying q array.

     */

    final class Itr implements Iterator<E> {

        final Object[] array; // Array of all elements

        int cursor;           // index of next element to return;

        int lastRet;          // index of last element, or -1 if no such

        Itr(Object[] array) {

            lastRet = -1;

            this.array = array;

        }

        public boolean hasNext() {

            return cursor < array.length;

        }

        public E next() {

            if (cursor >= array.length)

                throw new NoSuchElementException();

            lastRet = cursor;

            return (E)array[cursor++];

        }

        public void remove() {

            if (lastRet < 0)

                throw new IllegalStateException();

            removeEQ(array[lastRet]);

            lastRet = -1;

        }

    }

    /**

     * Saves the state to a stream (that is, serializes it).  For

     * compatibility with previous version of this class,

     * elements are first copied to a java.util.PriorityQueue,

     * which is then serialized.

     */

    private void writeObject(java.io.ObjectOutputStream s)

        throws java.io.IOException {

        lock.lock();

        try {

            int n = size; // avoid zero capacity argument

            q = new PriorityQueue<E>(n == 0 ? 1 : n, comparator);

            q.addAll(this);

            s.defaultWriteObject();

        } finally {

            q = null;

            lock.unlock();

        }

    }

    /**

     * Reconstitutes the {@code PriorityBlockingQueue} instance from a stream

     * (that is, deserializes it).

     *

     * @param s the stream

     */

    private void readObject(java.io.ObjectInputStream s)

        throws java.io.IOException, ClassNotFoundException {

        try {

            s.defaultReadObject();

            this.queue = new Object[q.size()];

            comparator = q.comparator();

            addAll(q);

        } finally {

            q = null;

        }

    }

}