On Fri, 30 Sep 2022 00:44:01 GMT, Stuart Marks <sma...@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. @stuart-marks Since there is no contract requiring the use of the `combiner`, all the documentation can say is that "it will be used if the implementation needs it"—which still doesn't answer (deterministically) *when* it will be applied, as even in the parallel case, presuming that the source is small enough not to warrant more than one chunk. I've taken a couple of stabs at trying to word this in a clear manner, but to be honest, perhaps the most confusion-reducing action is to delete the pseudocode altogether? 🤔 ------------- PR: https://git.openjdk.org/jdk/pull/10469
