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 @@
* <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
+ * #iterator()} and the Spliterator provided in method {@link #spliterator()}
+ * are <em>not</em> 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 <em><a href="Spliterator.html#binding">late-binding</a></em>
* and <em>fail-fast</em> {@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).
*
* <p>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 @@
* <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
+ * #iterator()} and the Spliterator provided in method {@link #spliterator()}
+ * are 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}
@@ -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).
*
* <p>The returned spliterator is
* <a href="package-summary.html#Weakly"><i>weakly consistent</i></a>.
