Module  java.base
软件包  java.util.concurrent

Class PriorityBlockingQueue<E>

  • 参数类型
    E - 保存在此队列中的元素的类型
    All Implemented Interfaces:
    Serializable ， Iterable<E> ， Collection<E> ， BlockingQueue<E> ， Queue<E> 

    public class PriorityBlockingQueue<E>
extends AbstractQueue<E>
implements BlockingQueue<E>, Serializable
    无限blocking queue使用与PriorityQueue类相同的排序规则，并提供阻止检索操作。 虽然此队列在逻辑上是无界的，但由于资源耗尽，尝试添加可能会失败（导致OutOfMemoryError ）。 这个类不允许null元素。 依靠natural ordering的优先级队列也不允许插入不可比较的对象（这样做在ClassCastException ）。

    该类及其迭代器实现Collection和Iterator接口的所有可选方法。 方法iterator()中提供的迭代器和方法spliterator()中提供的分割器不能保证以任何特定的顺序遍历PriorityBlockingQueue的元素。 如果需要有序遍历，请考虑使用Arrays.sort(pq.toArray()) 。 此外，方法drainTo可以用于以优先级顺序移除一些或所有元素并将它们放置在另一集合中。

    这个类的操作不会保证等同优先级的元素的排序。 如果需要强制执行排序，您可以定义自定义类或比较器，它们使用辅助键来破坏主优先级值的关系。 例如，这里是一个适用于先进先出的打破破坏类似元素的课程。 要使用它，您将插入一个new FIFOEntry(anEntry)而不是一个简单的条目对象。 

       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; } }

    这个类是Java Collections Framework的成员。

    从以下版本开始：
    1.5
    另请参见：
    Serialized Form

    • 构造方法详细信息

      • PriorityBlockingQueue

        public PriorityBlockingQueue​()
        创建一个PriorityBlockingQueue ，其默认初始容量（11）根据其natural ordering对其元素进行排序 。

      • PriorityBlockingQueue

        public PriorityBlockingQueue​(int initialCapacity)
        创建一个PriorityBlockingQueue具有指定的初始容量，根据它们的natural ordering命令其元素。
        参数
        initialCapacity - 此优先级队列的初始容量
        异常
        IllegalArgumentException - 如果 initialCapacity小于1

      • PriorityBlockingQueue

        public PriorityBlockingQueue​(int initialCapacity,
                             Comparator<? super E> comparator)
        创建具有指定初始容量的 PriorityBlockingQueue ，根据指定的比较器对其元素进行排序。
        参数
        initialCapacity - 此优先级队列的初始容量
        comparator - 将用于排序此优先级队列的比较器。 如果是null ，将使用natural ordering的元素。
        异常
        IllegalArgumentException - 如果 initialCapacity小于1

      • PriorityBlockingQueue

        public PriorityBlockingQueue​(Collection<? extends E> c)
        创建一个包含指定集合中的元素的PriorityBlockingQueue 。 如果指定的集合是SortedSet或PriorityQueue ，则该优先级队列将按照相同的顺序进行排序。 否则，此优先级队列将根据其元素的natural ordering进行排序。
        参数
        c - c元素放入此优先级队列的集合
        异常
        ClassCastException - 如果指定集合的元素不能根据优先级队列的顺序相互比较
        NullPointerException - 如果指定的集合或其任何元素为空

    • 方法详细信息

      • offer

        public boolean offer​(E e)
        将指定的元素插入到此优先级队列中。 队列无限制，此方法永远不会返回false 。
        Specified by:
        offer在接口 BlockingQueue<E>
        Specified by:
        offer在接口 Queue<E>
        参数
        e - 要添加的元素
        结果
        true （由 Queue.offer(E)指定）
        异常
        ClassCastException - 如果指定的元素不能根据优先级队列的排序与当前优先级队列中的元素进行比较
        NullPointerException - 如果指定的元素为空

      • put

        public void put​(E e)
        将指定的元素插入到此优先级队列中。 由于队列无限制，此方法将永远不会阻止。
        Specified by:
        put在接口 BlockingQueue<E>
        参数
        e - 要添加的元素
        异常
        ClassCastException - 如果指定的元素不能根据优先级队列的顺序与当前优先级队列中的元素进行比较
        NullPointerException - 如果指定的元素为空

      • offer

        public boolean offer​(E e,
                     long timeout,
                     TimeUnit unit)
        将指定的元素插入到此优先级队列中。 由于队列无限制，此方法将永远不会阻止或返回false 。
        Specified by:
        offer在接口 BlockingQueue<E>
        参数
        e - 要添加的元素
        timeout - 该参数被忽略，因为该方法从不阻止
        unit - 该参数被忽略，因为该方法从不阻止
        结果
        true （由 BlockingQueue.offer指定）
        异常
        ClassCastException - 如果指定的元素不能根据优先级队列的顺序与当前在优先级队列中的元素进行比较
        NullPointerException - 如果指定的元素为空

      • poll

        public E poll​()
        说明从接口Queue复制
        检索并删除此队列的头部，如果此队列为空，则返回 null 。
        Specified by:
        poll在接口 Queue<E>
        结果
        这个队列的头，或 null如果这个队列是空的

      • poll

        public E poll​(long timeout,
              TimeUnit unit)
       throws InterruptedException
        说明从接口BlockingQueue复制
        检索并删除此队列的头，等待指定的等待时间（如有必要）使元素变为可用。
        Specified by:
        poll在接口 BlockingQueue<E>
        参数
        timeout - 放弃之前等待多长时间，以 unit为单位
        unit - a TimeUnit确定如何解释 timeout参数
        结果
        该队列的头部，如果在元素可用之前经过指定的等待时间， null
        异常
        InterruptedException - 如果在等待时中断

      • peek

        public E peek​()
        说明从界面Queue复制
        检索但不删除此队列的头，如果此队列为空，则返回 null 。
        Specified by:
        peek在接口 Queue<E>
        结果
        这个队列的头，或 null如果这个队列是空的

      • comparator

        public Comparator<? super E> comparator​()
        返回用于为了在这个队列中的元素，或比较null如果此队列使用natural ordering的元素。
        结果
        比较器用于排序此队列中的元素，如果此队列使用其元素的自然排序， null

      • size

        public int size​()
        描述从接口Collection复制
        返回此集合中的元素数。 如果此集合包含Integer.MAX_VALUE元素，则返回Integer.MAX_VALUE 。
        Specified by:
        size在接口 Collection<E>
        Specified by:
        size在 AbstractCollection<E>
        结果
        此集合中的元素数

      • remainingCapacity

        public int remainingCapacity​()
        总是返回 Integer.MAX_VALUE因为 PriorityBlockingQueue没有容量限制。
        Specified by:
        remainingCapacity在接口 BlockingQueue<E>
        结果
        总是这样的 Integer.MAX_VALUE

      • remove

        public boolean remove​(Object o)
        从该队列中删除指定元素的单个实例（如果存在）。 更正式地，删除元素e使得o.equals(e) ，如果该队列包含一个或多个这样的元素。 返回true当且仅当此队列包含指定元素（或等效地，如果此队列作为调用的结果而更改）。
        Specified by:
        remove在接口 BlockingQueue<E>
        Specified by:
        remove在接口 Collection<E>
        重写：
        remove在 AbstractCollection<E>
        参数
        o - 要从此队列中删除的元素（如果存在）
        结果
        true如果此队列由于调用而更改

      • contains

        public boolean contains​(Object o)
        如果此队列包含指定的元素，则返回true 。 更正式地，返回true当且仅当这个队列包含至少一个元素e这样o.equals(e) 。
        Specified by:
        contains在接口 BlockingQueue<E>
        Specified by:
        contains在接口 Collection<E>
        重写：
        contains在 AbstractCollection<E>
        参数
        o - 要检查此队列中的遏制的对象
        结果
        true如果此队列包含指定的元素

      • toString

        public String toString​()
        说明从类别复制AbstractCollection
        返回此集合的字符串表示形式。 字符串表示由集合的元素的列表按照它们的迭代器返回的顺序包含在方括号（ "[]" ）中。 相邻元素由字符", " （逗号和空格）分隔。 元素将转换为字符串，如String.valueOf(Object) 。
        重写：
        toString在 AbstractCollection<E>
        结果
        此集合的字符串表示形式

      • drainTo

        public int drainTo​(Collection<? super E> c)
        描述从接口BlockingQueue复制
        从该队列中删除所有可用的元素，并将它们添加到给定的集合中。 此操作可能比重复轮询此队列更有效。 尝试向集合c添加元素时遇到的失败可能会导致在抛出关联的异常时，元素既不在两个集合中，也可能不是两个集合。 尝试将队列排入自身会导致IllegalArgumentException 。 此外，如果在操作进行中修改了指定的集合，则此操作的行为是未定义的。
        Specified by:
        drainTo在接口 BlockingQueue<E>
        参数
        c - 将元素传输到的集合
        结果
        转移的元素数量
        异常
        UnsupportedOperationException - 如果指定集合不支持添加元素
        ClassCastException - 如果此队列的元素的类阻止将其添加到指定的集合
        NullPointerException - 如果指定的集合为空
        IllegalArgumentException - 如果指定的集合是此队列，或此队列的元素的某些属性会阻止将其添加到指定的集合

      • drainTo

        public int drainTo​(Collection<? super E> c,
                   int maxElements)
        描述从接口BlockingQueue复制
        最多从该队列中删除给定数量的可用元素，并将它们添加到给定的集合中。 尝试向集合c添加元素时遇到的失败可能会导致元素在抛出关联的异常时都不在两个集合中。 尝试将排队排队自身会导致IllegalArgumentException 。 此外，如果在操作进行中修改了指定的集合，则此操作的行为是未定义的。
        Specified by:
        drainTo在接口 BlockingQueue<E>
        参数
        c - 传输元素的集合
        maxElements - 要传输的元素的最大数量
        结果
        转移的元素数量
        异常
        UnsupportedOperationException - 如果指定的集合不支持元素的添加
        ClassCastException - 如果此队列的元素的类阻止将其添加到指定的集合
        NullPointerException - 如果指定的集合为空
        IllegalArgumentException - 如果指定的集合是此队列，或此队列的某个元素的某些属性会阻止将其添加到指定的集合

      • clear

        public void clear​()
        从这个队列中原子地删除所有的元素。 此呼叫返回后队列将为空。
        Specified by:
        clear在接口 Collection<E>
        重写：
        clear在 AbstractQueue<E>

      • toArray

        public Object[] toArray​()
        返回一个包含此队列中所有元素的数组。 返回的数组元素没有特定的顺序。

        返回的数组将是“安全的”，因为该队列不保留对它的引用。 （换句话说，这个方法必须分配一个新的数组）。 因此，调用者可以自由地修改返回的数组。

        此方法充当基于阵列和基于集合的API之间的桥梁。

        Specified by:
        toArray在接口 Collection<E>
        重写：
        toArray在 AbstractCollection<E>
        结果
        一个包含此队列中所有元素的数组

      • toArray

        public <T> T[] toArray​(T[] a)
        返回一个包含此队列中所有元素的数组; 返回的数组的运行时类型是指定数组的运行时类型。 返回的数组元素没有特定的顺序。 如果队列适合指定的数组，则返回其中。 否则，将为指定数组的运行时类型和此队列的大小分配一个新数组。

        如果这个队列适合指定的数组空间（即数组比此队列更多的元素），则队列结束后的数组中的元素设置为null 。

        像toArray()方法一样，此方法充当基于数组和基于集合的API之间的桥梁。 此外，该方法允许精确地控制输出阵列的运行时类型，并且在某些情况下可以用于节省分配成本。

        假设x是一个已知只包含字符串的队列。 以下代码可用于将队列转储到新分配的String数组中： 

          String[] y = x.toArray(new String[0]);
        请注意， toArray(new Object[0])功能与toArray()相同。
        Specified by:
        toArray在接口 Collection<E>
        重写：
        toArray在 AbstractCollection<E>
        参数类型
        T - 包含集合的数组的运行时类型
        参数
        a - 要存储队列的元素的阵列，如果它足够大; 否则，为此目的分配相同运行时类型的新数组
        结果
        一个包含此队列中所有元素的数组
        异常
        ArrayStoreException - 如果指定数组的运行时类型不是此队列中每个元素的运行时类型的超类型
        NullPointerException - 如果指定的数组为空