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

8130023: API java.util.stream: explicitly specify guaranteed execution of the pipeline

Browse Source 
Reviewed-by: briangoetz, redestad
This commit is contained in:
Paul Sandoz 2016-05-20 11:47:39 +02:00
parent e988331331
commit 53ef4fecbf
5 changed files with 58 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
jdk/src/java.base/share/classes/java/util/stream/DoubleStream.java
View File

@ -211,6 +211,11 @@ public interface DoubleStream extends BaseStream<Double, DoubleStream> {
* .sum();
* }</pre>
*
* <p>In cases where stream implementation is able to optimize away the
* production of some or all the elements (such as with short-circuiting
* operations like {@code findFirst}, or in the example described in
* {@link #count}), the action will not be invoked for those elements.
*
* @param action a <a href="package-summary.html#NonInterference">
* non-interfering</a> action to perform on the elements as
* they are consumed from the stream

5
jdk/src/java.base/share/classes/java/util/stream/IntStream.java
View File

@ -209,6 +209,11 @@ public interface IntStream extends BaseStream<Integer, IntStream> {
* .sum();
* }</pre>
*
* <p>In cases where stream implementation is able to optimize away the
* production of some or all the elements (such as with short-circuiting
* operations like {@code findFirst}, or in the example described in
* {@link #count}), the action will not be invoked for those elements.
*
* @param action a <a href="package-summary.html#NonInterference">
* non-interfering</a> action to perform on the elements as
* they are consumed from the stream

5
jdk/src/java.base/share/classes/java/util/stream/LongStream.java
View File

@ -209,6 +209,11 @@ public interface LongStream extends BaseStream<Long, LongStream> {
* .sum();
* }</pre>
*
* <p>In cases where stream implementation is able to optimize away the
* production of some or all the elements (such as with short-circuiting
* operations like {@code findFirst}, or in the example described in
* {@link #count}), the action will not be invoked for those elements.
*
* @param action a <a href="package-summary.html#NonInterference">
* non-interfering</a> action to perform on the elements as
* they are consumed from the stream

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

@ -82,6 +82,19 @@ import java.util.function.UnaryOperator;
* terminal operation is initiated, and source elements are consumed only
* as needed.
*
* <p>A stream implementation is permitted significant latitude in optimizing
* the computation of the result. For example, a stream implementation is free
* to elide operations (or entire stages) from a stream pipeline -- and
* therefore elide invocation of behavioral parameters -- if it can prove that
* it would not affect the result of the computation. This means that
* side-effects of behavioral parameters may not always be executed and should
* not be relied upon, unless otherwise specified (such as by the terminal
* operations {@code forEach} and {@code forEachOrdered}). (For a specific
* example of such an optimization, see the API note documented on the
* {@link #count} operation. For more detail, see the
* <a href="package-summary.html#SideEffects">side-effects</a> section of the
* strean package documentation.)
*
* <p>Collections and streams, while bearing some superficial similarities,
* have different goals. Collections are primarily concerned with the efficient
* management of, and access to, their elements. By contrast, streams do not
@ -415,6 +428,11 @@ public interface Stream<T> extends BaseStream<T, Stream<T>> {
* .collect(Collectors.toList());
* }</pre>
*
* <p>In cases where stream implementation is able to optimize away the
* production of some or all the elements (such as with short-circuiting
* operations like {@code findFirst}, or in the example described in
* {@link #count}), the action will not be invoked for those elements.
*
* @param action a <a href="package-summary.html#NonInterference">
* non-interfering</a> action to perform on the elements as
* they are consumed from the stream

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

@ -287,18 +287,35 @@
* statelessness requirement, as well as other thread-safety hazards.
*
* <p>If the behavioral parameters do have side-effects, unless explicitly
* stated, there are no guarantees as to the
* <a href="../concurrent/package-summary.html#MemoryVisibility"><i>visibility</i></a>
* of those side-effects to other threads, nor are there any guarantees that
* different operations on the "same" element within the same stream pipeline
* are executed in the same thread. Further, the ordering of those effects
* may be surprising. Even when a pipeline is constrained to produce a
* <em>result</em> that is consistent with the encounter order of the stream
* source (for example, {@code IntStream.range(0,5).parallel().map(x -> x*2).toArray()}
* stated, there are no guarantees as to:
* <ul>
* <li>the <a href="../concurrent/package-summary.html#MemoryVisibility">
* <i>visibility</i></a> of those side-effects to other threads;</li>
* <li>that different operations on the "same" element within the same stream
* pipeline are executed in the same thread; and</li>
* <li>that behavioral parameters are always invoked, since a stream
* implementation is free to elide operations (or entire stages) from a
* stream pipeline if it can prove that it would not affect the result of the
* computation.
* </li>
* </ul>
* <p>The ordering of side-effects may be surprising. Even when a pipeline is
* constrained to produce a <em>result</em> that is consistent with the
* encounter order of the stream source (for example,
* {@code IntStream.range(0,5).parallel().map(x -> x*2).toArray()}
* must produce {@code [0, 2, 4, 6, 8]}), no guarantees are made as to the order
* in which the mapper function is applied to individual elements, or in what
* thread any behavioral parameter is executed for a given element.
*
* <p>The eliding of side-effects may also be surprising. With the exception of
* terminal operations {@link java.util.stream.Stream#forEach forEach} and
* {@link java.util.stream.Stream#forEachOrdered forEachOrdered}, side-effects
* of behavioral parameters may not always be executed when the stream
* implementation can optimize away the execution of behavioral parameters
* without affecting the result of the computation. (For a specific example
* see the API note documented on the {@link java.util.stream.Stream#count count}
* operation.)
*
* <p>Many computations where one might be tempted to use side effects can be more
* safely and efficiently expressed without side-effects, such as using
* <a href="package-summary.html#Reduction">reduction</a> instead of mutable