RFR 8164691 Stream specification clarifications for iterate and collect

[Tagir Valeev]

Hello!

Changes look ok to me, thanks.

With best regards,
Tagir Valeev.

On Mon, Aug 29, 2016 at 8:04 PM, Paul Sandoz <paul.sandoz at oracle.com> wrote:

> Thanks, updated in place,
> Paul.
>
> > On 26 Aug 2016, at 17:20, Stuart Marks <stuart.marks at oracle.com> wrote:
> >
> > Hi Paul,
> >
> > Overall looks good.
> >
> > A couple minor wording comments. For the 3-arg collectors, the combiner
> arg is defined as
> >
> > * @param combiner an <a href="package-summary.html#
> Associativity">associative</a>,
> > *                    <a href="package-summary.html#NonInterference">non-
> interfering</a>,
> > *                    <a href="package-summary.html#
> Statelessness">stateless</a>
> > *                    function that accepts two partial result containers
> and
> > *                    merges them, which must be compatible with the
> accumulator
> > *                    function.  The combiner function folds the elements
> in
> > *                    result container that is the second argument into
> the
> > *                    result container that is the first argument.
> >
> > I'd suggest replacing the last sentence with
> >
> >    The combiner function must fold the elements from the second
> >    result container into the first result container.
> >
> > I think it's implicitly pretty clear that the first and second result
> containers are the first and second arguments to the combiner function.
> >
> > If you're ok with the "must fold" style, then maybe also update the
> accumulator arg spec
> >
> > * @param accumulator an <a href="package-summary.html#
> Associativity">associative</a>,
> > *                    <a href="package-summary.html#NonInterference">non-
> interfering</a>,
> > *                    <a href="package-summary.html#
> Statelessness">stateless</a>
> > *                    function that folds an element into a result
> container.
> >
> > from "that folds" to "that must fold". That way all three args use the
> "must" style wording.
> >
> > I think the same wording is present in all four Stream types.
> >
> > s'marks
> >
> >
> > On 8/26/16 4:13 PM, Paul Sandoz wrote:
> >> Hi,
> >>
> >> Please review some minor tweaks to the stream specification:
> >>
> >>  http://cr.openjdk.java.net/~psandoz/jdk9/JDK-8164691-
> stream-iterate-collect-spec-updates/webrev/index.html <
> http://cr.openjdk.java.net/~psandoz/jdk9/JDK-8164691-
> stream-iterate-collect-spec-updates/webrev/index.html>
> >>
> >> The first tweak is to clarify the iterate methods and HB edges between
> function calls, the functions could potentially be stateful, they will
> never be called concurrently due to the nature of the source, but may be
> called in different threads.
> >>
> >> The second tweak is to the three-arg collect method. The combiner of
> result containers neglected to state how result containers should be merged.
> >>
> >> Thanks,
> >> Paul.
> >>
>
>