RFR JDK-8010096 : Initial java.util.Spliterator putback
Hi, http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=8010096 Webrev: http://cr.openjdk.java.net/~psandoz/lambda/spliterator/jdk-8010096/webrev/ Spec diff: http://cr.openjdk.java.net/~psandoz/lambda/spliterator/jdk-8010096/specdiff/... Relevant JavaDoc generated from lambda repo (required for viewing @apiNote, @implSpec, @implNote declarations): http://cr.openjdk.java.net/~psandoz/lambda/spliterator/jdk-8010096/api/java/ Note: some of the JavaDoc generated from the lambda repo may contain additional methods or specification that is relevant to the stream framework. -- To enable bulk operations, in parallel, on a data source it is required that such a source efficiently partition itself into smaller parts, where parts are processed concurrently, and each part is traversed sequentially. A new data interface is required that defines the contract for efficient partitioning and traversal. Collections need to implement that new data interface so the JSR-335 stream library can support bulk operations on common collection implementations, such as List/Set and arrays, in addition to other forms of data source e.g. third party collections. java.util.Spliterator, and primitive specializations of, is the key data interface that enables partitioning and traversal. JSR-335 java.util.stream.Stream instances will be constructed from spliterators. Collection is extended to define the default method spliterator(). Implementations are expected to override this method. The default implementation utilizes the collection's iterator and size to provide a spliterator implementation that permits limited parallism. Default overriding implementations are also provided for List, Set and SortedSet that support additional properties associated with those collections. Together with Spliterator some implementations are provided for creating Spliterator instances from data sources that are iterators and arrays. Note: Optimal spliterator implementations for many collection implementations in java.util and java.util.concurrent are present in the lambda repository and will duly make their way into TL after this webrev has been reviewed and pushed. -- Once this webrev is reviewed and pushed then the Stream API can follow, and then the fun really begins :-) The class com.sun.tools.jdi/EventSetImpl has been modified but is likely to change when spliterator implementations are pushed. This class cannot decide if it wants to be a List or a Set!! The compiler cannot work out if the default implementation of spliterator() for List or Set should apply. When the concrete collection implementations of spliterator arrive this class will not need to implement spliterator() and will inherit the implementation from ArrayList (implementations on classes always win over default implementations on interfaces). Unfortunately to build TL with this patch applied requires one also apply: http://hg.openjdk.java.net/lambda/lambda/jdk/rev/fbcafacf92ef Which i suspect was lost in the wash and should have been pushed to TL a while ago. Will follow up with Robert on that one. A JPRT of TL with both patches applied did not show any abnormal test failures. Paul.
On 28/03/2013 15:59, Paul Sandoz wrote:
Hi,
http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=8010096
Webrev: http://cr.openjdk.java.net/~psandoz/lambda/spliterator/jdk-8010096/webrev/
Spec diff: http://cr.openjdk.java.net/~psandoz/lambda/spliterator/jdk-8010096/specdiff/...
Relevant JavaDoc generated from lambda repo (required for viewing @apiNote, @implSpec, @implNote declarations): http://cr.openjdk.java.net/~psandoz/lambda/spliterator/jdk-8010096/api/java/
Note: some of the JavaDoc generated from the lambda repo may contain additional methods or specification that is relevant to the stream framework.
Just a few small comments from a quick pass over the webrev. The @return for the Array.spliterator methods reads "A spliterator from an array", maybe this should be "the array". For Iterable.forEach (and the Spliterator methods that take a Consumer) then you might consider "Errors or runtime exceptions" rather than "Exceptions" so that it is clear that an Error thrown by the action's accept method will be propagated too. The class description for the PrimitiveIterator.OfXXX classes is the one-liner "Specialization for XXX elements". It might be nicer to have this as "A Spliterator specialized for XXX elements". Will you change the Tripwire utility class to use the platform logger before you push this? Another thing on Tripwire is that the property lookup will probably fail if the class is initalized with application code on the stack and there is a security manager set. I think this will need to be changed to get the property value in a privileged blocked. The copyright header on the tests is normally the GPL header (no "Classpath" exception). I assume you'll fix this before pushing. One question on the spliteratorDataProvider - what is the issue with IdentityHashMap or do we know yet? -Alan.
Hi Alan, Thanks for taking a look. On Apr 1, 2013, at 6:13 PM, Alan Bateman <Alan.Bateman@oracle.com> wrote:
On 28/03/2013 15:59, Paul Sandoz wrote:
Hi,
http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=8010096
Webrev: http://cr.openjdk.java.net/~psandoz/lambda/spliterator/jdk-8010096/webrev/
Spec diff: http://cr.openjdk.java.net/~psandoz/lambda/spliterator/jdk-8010096/specdiff/...
Relevant JavaDoc generated from lambda repo (required for viewing @apiNote, @implSpec, @implNote declarations): http://cr.openjdk.java.net/~psandoz/lambda/spliterator/jdk-8010096/api/java/
Note: some of the JavaDoc generated from the lambda repo may contain additional methods or specification that is relevant to the stream framework.
Just a few small comments from a quick pass over the webrev.
The @return for the Array.spliterator methods reads "A spliterator from an array", maybe this should be "the array".
OK.
For Iterable.forEach (and the Spliterator methods that take a Consumer) then you might consider "Errors or runtime exceptions" rather than "Exceptions" so that it is clear that an Error thrown by the action's accept method will be propagated too.
I thought that might be redundant but there is sometimes confusion around what things can be thrown from methods that don't declare they throw anything so it is probably worth being explicit.
The class description for the PrimitiveIterator.OfXXX classes is the one-liner "Specialization for XXX elements". It might be nicer to have this as "A Spliterator specialized for XXX elements".
Will you change the Tripwire utility class to use the platform logger before you push this?
Yes.
Another thing on Tripwire is that the property lookup will probably fail if the class is initalized with application code on the stack and there is a security manager set. I think this will need to be changed to get the property value in a privileged blocked.
Ah!
The copyright header on the tests is normally the GPL header (no "Classpath" exception). I assume you'll fix this before pushing.
OK, grr i always forget that (makes it harder to have an automated template in the IDE when creating a new class).
One question on the spliteratorDataProvider - what is the issue with IdentityHashMap or do we know yet?
I do not. I will need to update the equivalent test-ng test since the IdentityHashMap occasionally fails. (Keeping duplicates at the moment because it is very convenient to run the lambda test-ng tests.) Paul.
Nice work Paul, some small comments. - new javadocs tags, @implSpec, @apiNote, etc. I really like the use of implSpec to define the behavior of this implementations default methods. There is probably a separate thread, but any idea when these will be generated in the javadoc, not just the lambda docs? - Iterator.remove @since 1.8? I see there is a conflict here between when the method was originally added and its default - Spliterator class level examples are not showing in the specdiff. Are these really API Notes? Maybe they are. -Chris. On 03/28/2013 03:59 PM, Paul Sandoz wrote:
Hi,
http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=8010096
Webrev: http://cr.openjdk.java.net/~psandoz/lambda/spliterator/jdk-8010096/webrev/
Spec diff: http://cr.openjdk.java.net/~psandoz/lambda/spliterator/jdk-8010096/specdiff/...
Relevant JavaDoc generated from lambda repo (required for viewing @apiNote, @implSpec, @implNote declarations): http://cr.openjdk.java.net/~psandoz/lambda/spliterator/jdk-8010096/api/java/
Note: some of the JavaDoc generated from the lambda repo may contain additional methods or specification that is relevant to the stream framework.
--
To enable bulk operations, in parallel, on a data source it is required that such a source efficiently partition itself into smaller parts, where parts are processed concurrently, and each part is traversed sequentially.
A new data interface is required that defines the contract for efficient partitioning and traversal.
Collections need to implement that new data interface so the JSR-335 stream library can support bulk operations on common collection implementations, such as List/Set and arrays, in addition to other forms of data source e.g. third party collections.
java.util.Spliterator, and primitive specializations of, is the key data interface that enables partitioning and traversal. JSR-335 java.util.stream.Stream instances will be constructed from spliterators.
Collection is extended to define the default method spliterator(). Implementations are expected to override this method. The default implementation utilizes the collection's iterator and size to provide a spliterator implementation that permits limited parallism. Default overriding implementations are also provided for List, Set and SortedSet that support additional properties associated with those collections.
Together with Spliterator some implementations are provided for creating Spliterator instances from data sources that are iterators and arrays.
Note: Optimal spliterator implementations for many collection implementations in java.util and java.util.concurrent are present in the lambda repository and will duly make their way into TL after this webrev has been reviewed and pushed.
--
Once this webrev is reviewed and pushed then the Stream API can follow, and then the fun really begins :-)
The class com.sun.tools.jdi/EventSetImpl has been modified but is likely to change when spliterator implementations are pushed. This class cannot decide if it wants to be a List or a Set!! The compiler cannot work out if the default implementation of spliterator() for List or Set should apply. When the concrete collection implementations of spliterator arrive this class will not need to implement spliterator() and will inherit the implementation from ArrayList (implementations on classes always win over default implementations on interfaces).
Unfortunately to build TL with this patch applied requires one also apply:
http://hg.openjdk.java.net/lambda/lambda/jdk/rev/fbcafacf92ef
Which i suspect was lost in the wash and should have been pushed to TL a while ago. Will follow up with Robert on that one.
A JPRT of TL with both patches applied did not show any abnormal test failures.
Paul.
On Apr 2, 2013, at 2:37 PM, Chris Hegarty <chris.hegarty@oracle.com> wrote:
Nice work Paul, some small comments.
- new javadocs tags, @implSpec, @apiNote, etc. I really like the use of implSpec to define the behavior of this implementations default methods. There is probably a separate thread, but any idea when these will be generated in the javadoc, not just the lambda docs?
I do not know, Mike is the one who is very likely to know more.
- Iterator.remove @since 1.8? I see there is a conflict here between when the method was originally added and its default
Right, that is most likely a mistake. How can we express that the default method is there since 1.8?
- Spliterator class level examples are not showing in the specdiff. Are these really API Notes? Maybe they are.
The examples are non-normative so i think such docs can be categorized under @apiNote. See here for generated JavaDoc from the lambda repo: http://cr.openjdk.java.net/~psandoz/lambda/spliterator/jdk-8010096/api/java/... Paul.
On 04/02/2013 06:34 AM, Paul Sandoz wrote:
On Apr 2, 2013, at 2:37 PM, Chris Hegarty <chris.hegarty@oracle.com> wrote:
Nice work Paul, some small comments.
- new javadocs tags, @implSpec, @apiNote, etc. I really like the use of implSpec to define the behavior of this implementations default methods. There is probably a separate thread, but any idea when these will be generated in the javadoc, not just the lambda docs?
I do not know, Mike is the one who is very likely to know more.
- Iterator.remove @since 1.8? I see there is a conflict here between when the method was originally added and its default
Right, that is most likely a mistake. How can we express that the default method is there since 1.8?
That cannot the expressed in @since tags, but it is duly recorded by the JCK signature tests. There are other kinds of evolutions the @since tags cannot capture, such as a class being retrofitted to implement an interface in a release after the interface was added. -Joe
On Apr 2 2013, at 10:33 , Joe Darcy wrote:
On 04/02/2013 06:34 AM, Paul Sandoz wrote:
On Apr 2, 2013, at 2:37 PM, Chris Hegarty <chris.hegarty@oracle.com> wrote:
Nice work Paul, some small comments.
- new javadocs tags, @implSpec, @apiNote, etc. I really like the use of implSpec to define the behavior of this implementations default methods. There is probably a separate thread, but any idea when these will be generated in the javadoc, not just the lambda docs?
I do not know, Mike is the one who is very likely to know more.
I am waiting for resolution of "JDK-8008768 : Using {@inheritDoc} in simple tag defined via -tag fails" to move forward with this. Mike
participants (5)
-
Alan Bateman
-
Chris Hegarty
-
Joe Darcy
-
Mike Duigou
-
Paul Sandoz