RFR: 8279361: Error in documentation of third Stream.reduce method
Stuart Marks
smarks at openjdk.org
Fri Sep 30 00:46:25 UTC 2022
On Wed, 28 Sep 2022 15:36:50 GMT, Viktor Klang <duke at openjdk.org> wrote:
> This JavaDoc change attempts to shine some light on the `combiner`-function as it relates to the third variant of `Stream.reduce` since it according to the bug submission in JBS can be confusing that the `combiner` is not mentioned in the code example in the documentation.
One of the problems with pseudo-code is that people can interpret it too literally. Even though we say things like "the result is as if..." it still invites confusion. For example, the proposed chunk code invokes the combiner even in the case where there is only one chunk. However, the clause that follows says:
> In the case where there are less than two chunks, invoking the
> combiner is not needed as there is no merging to be done.
seems to be quasi-normative in that it implies (or does it?) that the combiner _won't_ be called if there is only a single chunk. While that's true of the current implementation, the current spec doesn't guarantee it, and I don't think we want to add such a requirement even though it might be desirable. (At least, we shouldn't add a requirement without good reason.)
So there's still a question of whether or not the combiner is called in sequential cases, and also about its fundamental role in the reduce operation. I've answered a couple Stack Overflow questions on it:
https://stackoverflow.com/questions/24308146/why-is-a-combiner-needed-for-reduce-method-that-converts-type-in-java-8/24316429#24316429
https://stackoverflow.com/questions/29210176/can-a-collectors-combiner-function-ever-be-used-on-sequential-streams/29295055#29295055
(And maybe @amaembo has too. And yes Tagir we're still thinking about ordered reduce or fold operations.)
So maybe a prose description of the splitting and combining process would be preferable. Or possibly a more-pseudo pseudo-code example that doesn't have as much detail, so people don't read into it so much.
-------------
PR: https://git.openjdk.org/jdk/pull/10469
More information about the core-libs-dev
mailing list