Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8132964

Spliterator documentation on Priority(Blocking)Queue

XMLWordPrintable

      A DESCRIPTION OF THE REQUEST :
      The PriorityQueue class iterator() returns elements in no particular order. This is explicitly stated in JavaDoc for iterator() method [1] as well as in class description [2]. However it's not mentioned that spliterator() method also traverses the queue in no particular order. Well, the user might guess that the order is not specified, because the spliterator does not have ORDERED characteristic, but it's not so obvious for any user. Probably it's would be good to add an explicit note like it's done for iterator. The same thing is for PriorityBlockingQueue.

      [1] http://hg.openjdk.java.net/jdk9/dev/jdk/file/022d45d94d0a/src/java.base/share/classes/java/util/PriorityQueue.java#l477
      [2] http://hg.openjdk.java.net/jdk9/dev/jdk/file/022d45d94d0a/src/java.base/share/classes/java/util/PriorityQueue.java#l54

      JUSTIFICATION :
      This will reduce the possible confusion when Priority(Blocking)Queue.spliterator(), stream() and parallelStream() methods are used. Users might expect that the order of created spliterator is based on queue comparator (or elements natural order) which is wrong.

      EXPECTED VERSUS ACTUAL BEHAVIOR :
      EXPECTED -
      The ProrityQueue.spliterator() documentation should state something like this:

      Please note that the returned spliterator is not ORDERED and traverses the queue in no particular order.

      Also the statement like the following should be added to the class description:

      The stream created by stream() method is not ORDERED and not guaranteed to traverse the queue elements in any particular order. If you need an ordered stream, use stream().sorted().

            psandoz Paul Sandoz
            webbuggrp Webbug Group
            Votes:
            0 Vote for this issue
            Watchers:
            4 Start watching this issue

              Created:
              Updated:
              Resolved: