> On 19 May 2016, at 12:02, Paul Sandoz <paul.san...@oracle.com> wrote:
>
>
>> On 17 May 2016, at 23:15, Claes Redestad <claes.redes...@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 ….” ?
>
Since it’s getting really really close to FC deadlines i left this paragraph as
is and pushed, sorry to steam roll this though a little. We can revisit later,
if necessary, as i expect any such updates should not change the meaning (or be
non-normative).
>
>> 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.
>
I included that.
Thanks,
Paul.
