RFR: JDK-8319123 : Implementation of JEP-461: Stream Gatherers (Preview) [v5]

[Paul Sandoz]

On Mon, 13 Nov 2023 09:22:13 GMT, Viktor Klang <vklang at openjdk.org> wrote:

>> This Pull-Request implements [JEP-461](https://openjdk.org/jeps/461)
>
> Viktor Klang has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Minor improvements to Gatherer Javadoc

src/java.base/share/classes/java/util/stream/Gatherer.java line 40:

> 38:  * stream of output elements, optionally applying a final action when the end of
> 39:  * the upstream is reached. The transformation may be stateless or stateful,
> 40:  * and a Gatherer may buffer arbitrarily much input before producing any output.

Suggestion:

 * and may buffer input before producing any output.

src/java.base/share/classes/java/util/stream/Gatherer.java line 63:

> 61:  * </ul>
> 62:  *
> 63:  * <p>Each invocation to {@link #initializer()}, {@link #integrator()},

Suggestion:

 * <p>Each invocation of {@link #initializer()}, {@link #integrator()},

src/java.base/share/classes/java/util/stream/Gatherer.java line 119:

> 117:  *
> 118:  * <p>As an example, in order to create a gatherer to implement a sequential
> 119:  * Prefix Scan as a Gatherer, it could be done the following way:

Suggestion:

 * <p>As an example, a Gatherer implementing a sequential Prefix Scan 
 * could be done the following way:

src/java.base/share/classes/java/util/stream/Gatherer.java line 152:

> 150:  * }
> 151:  *
> 152:  * @implSpec Libraries that implement transformation based on {@code Gatherer},

Suggestion:

 * @implSpec Libraries that implement transformations based on {@code Gatherer},

src/java.base/share/classes/java/util/stream/Gatherer.java line 166:

> 164:  *     arguments passed to the combiner function, and the argument passed to the
> 165:  *     finisher function must be the result of a previous invocation of the
> 166:  *     initializer, integrator, or combiner functions.</li>

the integrator returns a boolean, so is it just the result of a previous invocation of the initializer or combiner functions? (Similarly for the next clause.)

src/java.base/share/classes/java/util/stream/Gatherer.java line 185:

> 183:  *     partitions state using the combiner, and then invoking the finisher on
> 184:  *     the joined state. Outputs and state later in the input sequence will
> 185:  *     be discarded if processing an earlier segment short-circuits.</li>

Suggestion:

 *     be discarded if processing an earlier partition short-circuits.</li>

src/java.base/share/classes/java/util/stream/Gatherer.java line 501:

> 499: 
> 500:         /**
> 501:          * Allows for checking whether the next stage is known to not want

Suggestion:

         * Checks whether the next stage is known to not want

src/java.base/share/classes/java/util/stream/Gatherer.java line 558:

> 556: 
> 557:         /**
> 558:          * Factory method for turning Integrator-shaped lambdas into

Suggestion:

         * Targets Integrator-shaped lambdas to

It's not a factory, as it does produce anything, it's an identity function that aids in the targeting of the lambda expression to the integrator when there would otherwise be ambiguity as to the target.

src/java.base/share/classes/java/util/stream/Gatherers.java line 47:

> 45: 
> 46: /**
> 47:  * Implementations of {@link Gatherer} that implement various useful intermediate

Suggestion:

 * Implementations of {@link Gatherer} that provide useful intermediate

src/java.base/share/classes/java/util/stream/Gatherers.java line 80:

> 78:      *          and eagerly. This means that choosing large window sizes for
> 79:      *          small streams may use excessive memory for the duration of
> 80:      *          evaluation of this operation.

Suggestion:

     *          small streams may use excessive memory during
     *          evaluation of this operation.

(Same for other methods.)

src/java.base/share/classes/java/util/stream/Gatherers.java line 329:

> 327: 
> 328:     /**
> 329:      * An operation which executes operations concurrently

Suggestion:

     * An operation which executes a function concurrently

src/java.base/share/classes/java/util/stream/Gatherers.java line 340:

> 338:      * <p>If the mapper throws an exception during evaluation of this Gatherer,
> 339:      * and the result of that invocation is to be produced to the downstream,
> 340:      * then that exception will instead be rethrown as a {@link RuntimeException}.

Suggestion:

     * <p>If a result of the function is to be pushed downstream but instead the function completed
     * exceptionally then the corresponding exception will instead be rethrown by this method as an 
     * instance of {@link RuntimeException}. After which any remaining tasks are canceled.

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/16420#discussion_r1391814346
PR Review Comment: https://git.openjdk.org/jdk/pull/16420#discussion_r1391815675
PR Review Comment: https://git.openjdk.org/jdk/pull/16420#discussion_r1391818520
PR Review Comment: https://git.openjdk.org/jdk/pull/16420#discussion_r1391818887
PR Review Comment: https://git.openjdk.org/jdk/pull/16420#discussion_r1391821170
PR Review Comment: https://git.openjdk.org/jdk/pull/16420#discussion_r1391822409
PR Review Comment: https://git.openjdk.org/jdk/pull/16420#discussion_r1391826169
PR Review Comment: https://git.openjdk.org/jdk/pull/16420#discussion_r1391829649
PR Review Comment: https://git.openjdk.org/jdk/pull/16420#discussion_r1391830903
PR Review Comment: https://git.openjdk.org/jdk/pull/16420#discussion_r1391832936
PR Review Comment: https://git.openjdk.org/jdk/pull/16420#discussion_r1391840780
PR Review Comment: https://git.openjdk.org/jdk/pull/16420#discussion_r1391849458