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

[Paul Sandoz]

> On 17 May 2016, at 23:15, Claes Redestad <claes.redestad at oracle.com> wrote:
> 
> 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?
> 

The first sentence is setting the stage that it is the result and not the computation that is key and we want to get across that this is not a limitation but a feature, since streams are about specifying a computation declaratively (and if side-effects are present then watch out!).

We cannot specify the degrees of freedom, we can only specify the result be the same. Perhaps the "For example, “ in the following sentence can be removed or replaced with “As such ….” ?


> 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.)
> + *
> 

I like the move of the “unless …” to the end of the sentence, that reads better.

Thanks,
Paul.