stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

8132800: clarify stream package documentation regarding sequential vs parallel modes

Browse Source 
Reviewed-by: psandoz
This commit is contained in:
Stuart Marks 2015-08-04 14:45:38 -07:00
parent 9c9b37de81
commit e6d9c734ec
2 changed files with 14 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
jdk/src/java.base/share/classes/java/util/stream/Stream.java
View File

@ -1232,6 +1232,9 @@ public interface Stream<T> extends BaseStream<T, Stream<T>> {
* Accessing an element of a deeply concatenated stream can result in deep * Accessing an element of a deeply concatenated stream can result in deep
* call chains, or even {@code StackOverflowError}. * call chains, or even {@code StackOverflowError}.
* *
* <p>Subsequent changes to the sequential/parallel execution mode of the
* returned stream are not guaranteed to be propagated to the input streams.
*
* @param <T> The type of stream elements * @param <T> The type of stream elements
* @param a the first stream * @param a the first stream
* @param b the second stream * @param b the second stream

22
jdk/src/java.base/share/classes/java/util/stream/package-info.java
View File

@ -1,5 +1,5 @@
/* /*
* Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved. * Copyright (c) 2012, 2015, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
* *
* This code is free software; you can redistribute it and/or modify it * This code is free software; you can redistribute it and/or modify it
@ -159,7 +159,7 @@
* is a necessary, but not sufficient, condition for the processing of an infinite * is a necessary, but not sufficient, condition for the processing of an infinite
* stream to terminate normally in finite time. * stream to terminate normally in finite time.
* *
* <h3>Parallelism</h3> * <h3><a name="Parallelism">Parallelism</a></h3>
* *
* <p>Processing elements with an explicit {@code for-}loop is inherently serial. * <p>Processing elements with an explicit {@code for-}loop is inherently serial.
* Streams facilitate parallel execution by reframing the computation as a pipeline of * Streams facilitate parallel execution by reframing the computation as a pipeline of
@ -184,15 +184,15 @@
* *
* <p>The only difference between the serial and parallel versions of this * <p>The only difference between the serial and parallel versions of this
* example is the creation of the initial stream, using "{@code parallelStream()}" * example is the creation of the initial stream, using "{@code parallelStream()}"
* instead of "{@code stream()}". When the terminal operation is initiated, * instead of "{@code stream()}". The stream pipeline is executed sequentially or
* the stream pipeline is executed sequentially or in parallel depending on the * in parallel depending on the mode of the stream on which the terminal operation
* orientation of the stream on which it is invoked. Whether a stream will execute in serial or * is invoked. The sequential or parallel mode of a stream can be determined with the
* parallel can be determined with the {@code isParallel()} method, and the * {@link java.util.stream.BaseStream#isParallel()} method, and the
* orientation of a stream can be modified with the * stream's mode can be modified with the
* {@link java.util.stream.BaseStream#sequential()} and * {@link java.util.stream.BaseStream#sequential()} and
* {@link java.util.stream.BaseStream#parallel()} operations. When the terminal * {@link java.util.stream.BaseStream#parallel()} operations.
* operation is initiated, the stream pipeline is executed sequentially or in * The most recent sequential or parallel mode setting applies to the
* parallel depending on the mode of the stream on which it is invoked. * execution of the entire stream pipeline.
* *
* <p>Except for operations identified as explicitly nondeterministic, such * <p>Except for operations identified as explicitly nondeterministic, such
* as {@code findAny()}, whether a stream executes sequentially or in parallel * as {@code findAny()}, whether a stream executes sequentially or in parallel
@ -280,7 +280,7 @@
* parameters to stream operations entirely; there is usually a way to * parameters to stream operations entirely; there is usually a way to
* restructure the stream pipeline to avoid statefulness. * restructure the stream pipeline to avoid statefulness.
* *
* <h3>Side-effects</h3> * <h3><a name="SideEffects">Side-effects</a></h3>
* *
* Side-effects in behavioral parameters to stream operations are, in general, * Side-effects in behavioral parameters to stream operations are, in general,
* discouraged, as they can often lead to unwitting violations of the * discouraged, as they can often lead to unwitting violations of the