RFR 8130023 API java.util.stream: explicitly specify guaranteed execution of the pipeline

[Claes Redestad]

Hi,

the first block in Stream.java bothers me:

+ * <p>A stream implementation is permitted significant latitude in 
optimizing
+ * the computation of the result. For example, a stream implementation 
is free
+ * to elide operations (or entire stages) from a stream pipeline -- and
+ * therefore elide invocation of behavioral parameters -- if it can 
prove that
+ * it would not affect the result of the computation. This means, that 
unless
+ * otherwise specified (such as by the terminal operations {@code 
forEach} and
+ * {@code forEachOrdered}), that side-effects of behavioral parameters 
may not
+ * always be executed and should not be relied upon. (For a specific 
example of
+ * such an optimization, see the API note documented on the {@link #count}
+ * operation. For more detail, see the
+ * <a href="package-summary.html#SideEffects">side-effects</a> section 
of the
+ * strean package documentation.)
+ *


The first sentence in particular is hard to read and interpret, and 
after reading it twice I'm not sure if it's entirely redundant or if you 
need to better specify what other freedoms are given to a stream 
implementation?

How about this:

+ * <p>Astream implementation is free  to elide operations (or entire stages) + * from a stream pipeline -- 
andtherefore elide invocation of behavioral + * parameters -- if it can 
prove that  it would not affect the result of the + * computation. This means that 
side-effects of behavioral parameters may not + * always be executed and 
should not be relied upon, unless  otherwise specified + * (such as by the terminal operations {@code 
forEach} and
+ * {@code forEachOrdered}).(For a specific example ofsuch an 
optimization, + * see the API note documented on the {@link #count}  operation. For more + * details, see the  <a href="package-summary.html#SideEffects">side-effects</a> + * section 
of the  stream package documentation.)
+ *


Thanks!

/Claes

On 2016-05-17 22:23, Paul Sandoz wrote:
> Hi,
>
> Please review:
>
>    http://cr.openjdk.java.net/~psandoz/jdk9/JDK-8130023-stream-elide-ops-side-effects/webrev/ <http://cr.openjdk.java.net/~psandoz/jdk9/JDK-8130023-stream-elide-ops-side-effects/webrev/>
>
> This is a spec tweak to streams to state that implementations are free to elide some or all operations in a pipeline as long as it does not affect the result of the stream computation i.e. side-effects beware!
>
> Paul.