RFR 8132964 Spliterator documentation on Priority(Blocking)Queue (original) (raw)

Doug Lea dl at cs.oswego.edu
Mon Nov 21 21:16:36 UTC 2016

On 11/21/2016 03:52 PM, Paul Sandoz wrote:

Hi,

Please review specification clarifications to PriorityQueue and PriorityBlockingQueue for the spliterator. Ordinarily i would not specify what spliterator characteristics are not reported, but in this case given what is said about iterator I think it reasonable to say it about spliterator (a number of developers have got caught out regarding order, or lack thereof in this case, but i also suspect they never read the specification!)

Sure. It would be nice if there were something we could do to reduce confusion between ordered-but-destructive poll()-loops, vs unordered but-read-only iterators/spliterators. But clarifying here might help a little.

-Doug

Paul.

diff -r eb147f1f232d src/java.base/share/classes/java/util/PriorityQueue.java --- a/src/java.base/share/classes/java/util/PriorityQueue.java Mon Nov 21 12:00:46 2016 -0800 +++ b/src/java.base/share/classes/java/util/PriorityQueue.java Mon Nov 21 12:30:33 2016 -0800 @@ -54,7 +54,8 @@ *

This class and its iterator implement all of the

* optional methods of the {@link Collection} and {@link * Iterator} interfaces. The Iterator provided in method {@link - * #iterator()} is not guaranteed to traverse the elements of + * #iterator()} and the Spliterator provided in method {@link #spliterator()} + * are not guaranteed to traverse the elements of * the priority queue in any particular order. If you need ordered * traversal, consider using {@code Arrays.sort(pq.toArray())}. * @@ -799,7 +800,8 @@ /** * Creates a late-binding * and fail-fast {@link Spliterator} over the elements in this - * queue. + * queue. The spliterator does not traverse elements in any particular order + * (the {@link Spliterator#ORDERED ORDERED} characteristic is not reported). * *

The {@code Spliterator} reports {@link Spliterator#SIZED},

 * {@link Spliterator#SUBSIZED}, and {@link Spliterator#NONNULL}. diff -r eb147f1f232d src/java.base/share/classes/java/util/concurrent/PriorityBlockingQueue.java --- a/src/java.base/share/classes/java/util/concurrent/PriorityBlockingQueue.java Mon Nov 21 12:00:46 2016 -0800 +++ b/src/java.base/share/classes/java/util/concurrent/PriorityBlockingQueue.java Mon Nov 21 12:30:33 2016 -0800 @@ -65,7 +65,8 @@ *

This class and its iterator implement all of the

 * optional methods of the {@link Collection} and {@link * Iterator} interfaces. The Iterator provided in method {@link - * #iterator()} is not guaranteed to traverse the elements of + * #iterator()} and the Spliterator provided in method {@link #spliterator()} + * are is not 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} @@ -994,6 +995,8 @@ /** * Returns a {@link Spliterator} over the elements in this queue. + * The spliterator does not traverse elements in any particular order + * (the {@link Spliterator#ORDERED ORDERED} characteristic is not reported). * *

The returned spliterator is

 * weakly consistent.

More information about the core-libs-dev mailing list