src/share/classes/java/util/stream/package-info.java

Print this page
rev 8940 : 8029696: Broken doc links to package-summary.html#NonInterference in java.util.stream
Reviewed-by: mduigou


 189  * orientation of the stream on which it is invoked.  Whether a stream will execute in serial or
 190  * parallel can be determined with the {@code isParallel()} method, and the
 191  * orientation of a stream can be modified with the
 192  * {@link java.util.stream.BaseStream#sequential()} and
 193  * {@link java.util.stream.BaseStream#parallel()} operations.  When the terminal
 194  * operation is initiated, the stream pipeline is executed sequentially or in
 195  * parallel depending on the mode of the stream on which it is invoked.
 196  *
 197  * <p>Except for operations identified as explicitly nondeterministic, such
 198  * as {@code findAny()}, whether a stream executes sequentially or in parallel
 199  * should not change the result of the computation.
 200  *
 201  * <p>Most stream operations accept parameters that describe user-specified
 202  * behavior, which are often lambda expressions.  To preserve correct behavior,
 203  * these <em>behavioral parameters</em> must be <em>non-interfering</em>, and in
 204  * most cases must be <em>stateless</em>.  Such parameters are always instances
 205  * of a <a href="../function/package-summary.html">functional interface</a> such
 206  * as {@link java.util.function.Function}, and are often lambda expressions or
 207  * method references.
 208  *
 209  * <h3><a name="Non-Interference">Non-interference</a></h3>
 210  *
 211  * Streams enable you to execute possibly-parallel aggregate operations over a
 212  * variety of data sources, including even non-thread-safe collections such as
 213  * {@code ArrayList}. This is possible only if we can prevent
 214  * <em>interference</em> with the data source during the execution of a stream
 215  * pipeline.  Except for the escape-hatch operations {@code iterator()} and
 216  * {@code spliterator()}, execution begins when the terminal operation is
 217  * invoked, and ends when the terminal operation completes.  For most data
 218  * sources, preventing interference means ensuring that the data source is
 219  * <em>not modified at all</em> during the execution of the stream pipeline.
 220  * The notable exception to this are streams whose sources are concurrent
 221  * collections, which are specifically designed to handle concurrent modification.
 222  * Concurrent stream sources are those whose {@code Spliterator} reports the
 223  * {@code CONCURRENT} characteristic.
 224  *
 225  * <p>Accordingly, behavioral parameters in stream pipelines whose source might
 226  * not be concurrent should never modify the stream's data source.
 227  * A behavioral parameter is said to <em>interfere</em> with a non-concurrent
 228  * data source if it modifies, or causes to be
 229  * modified, the stream's data source.  The need for non-interference applies


 712  * timing of binding to the data, since the data could change between the time
 713  * the spliterator is created and the time the stream pipeline is executed.
 714  * Ideally, a spliterator for a stream would report a characteristic of
 715 
 716  * {@code IMMUTABLE} or {@code CONCURRENT}; if not it should be
 717  * <a href="../Spliterator.html#binding"><em>late-binding</em></a>. If a source
 718  * cannot directly supply a recommended spliterator, it may indirectly supply
 719  * a spliterator using a {@code Supplier}, and construct a stream via the
 720  * {@code Supplier}-accepting versions of
 721  * {@link java.util.stream.StreamSupport#stream(Supplier, int, boolean) stream()}.
 722  * The spliterator is obtained from the supplier only after the terminal
 723  * operation of the stream pipeline commences.
 724  *
 725  * <p>These requirements significantly reduce the scope of potential
 726  * interference between mutations of the stream source and execution of stream
 727  * pipelines. Streams based on spliterators with the desired characteristics,
 728  * or those using the Supplier-based factory forms, are immune to
 729  * modifications of the data source prior to commencement of the terminal
 730  * operation (provided the behavioral parameters to the stream operations meet
 731  * the required criteria for non-interference and statelessness).  See
 732  * <a href="package-summary.html#Non-Interference">Non-Interference</a>
 733  * for more details.
 734  *
 735  * @since 1.8
 736  */
 737 package java.util.stream;
 738 
 739 import java.util.function.BinaryOperator;
 740 import java.util.function.UnaryOperator;


 189  * orientation of the stream on which it is invoked.  Whether a stream will execute in serial or
 190  * parallel can be determined with the {@code isParallel()} method, and the
 191  * orientation of a stream can be modified with the
 192  * {@link java.util.stream.BaseStream#sequential()} and
 193  * {@link java.util.stream.BaseStream#parallel()} operations.  When the terminal
 194  * operation is initiated, the stream pipeline is executed sequentially or in
 195  * parallel depending on the mode of the stream on which it is invoked.
 196  *
 197  * <p>Except for operations identified as explicitly nondeterministic, such
 198  * as {@code findAny()}, whether a stream executes sequentially or in parallel
 199  * should not change the result of the computation.
 200  *
 201  * <p>Most stream operations accept parameters that describe user-specified
 202  * behavior, which are often lambda expressions.  To preserve correct behavior,
 203  * these <em>behavioral parameters</em> must be <em>non-interfering</em>, and in
 204  * most cases must be <em>stateless</em>.  Such parameters are always instances
 205  * of a <a href="../function/package-summary.html">functional interface</a> such
 206  * as {@link java.util.function.Function}, and are often lambda expressions or
 207  * method references.
 208  *
 209  * <h3><a name="NonInterference">Non-interference</a></h3>
 210  *
 211  * Streams enable you to execute possibly-parallel aggregate operations over a
 212  * variety of data sources, including even non-thread-safe collections such as
 213  * {@code ArrayList}. This is possible only if we can prevent
 214  * <em>interference</em> with the data source during the execution of a stream
 215  * pipeline.  Except for the escape-hatch operations {@code iterator()} and
 216  * {@code spliterator()}, execution begins when the terminal operation is
 217  * invoked, and ends when the terminal operation completes.  For most data
 218  * sources, preventing interference means ensuring that the data source is
 219  * <em>not modified at all</em> during the execution of the stream pipeline.
 220  * The notable exception to this are streams whose sources are concurrent
 221  * collections, which are specifically designed to handle concurrent modification.
 222  * Concurrent stream sources are those whose {@code Spliterator} reports the
 223  * {@code CONCURRENT} characteristic.
 224  *
 225  * <p>Accordingly, behavioral parameters in stream pipelines whose source might
 226  * not be concurrent should never modify the stream's data source.
 227  * A behavioral parameter is said to <em>interfere</em> with a non-concurrent
 228  * data source if it modifies, or causes to be
 229  * modified, the stream's data source.  The need for non-interference applies


 712  * timing of binding to the data, since the data could change between the time
 713  * the spliterator is created and the time the stream pipeline is executed.
 714  * Ideally, a spliterator for a stream would report a characteristic of
 715 
 716  * {@code IMMUTABLE} or {@code CONCURRENT}; if not it should be
 717  * <a href="../Spliterator.html#binding"><em>late-binding</em></a>. If a source
 718  * cannot directly supply a recommended spliterator, it may indirectly supply
 719  * a spliterator using a {@code Supplier}, and construct a stream via the
 720  * {@code Supplier}-accepting versions of
 721  * {@link java.util.stream.StreamSupport#stream(Supplier, int, boolean) stream()}.
 722  * The spliterator is obtained from the supplier only after the terminal
 723  * operation of the stream pipeline commences.
 724  *
 725  * <p>These requirements significantly reduce the scope of potential
 726  * interference between mutations of the stream source and execution of stream
 727  * pipelines. Streams based on spliterators with the desired characteristics,
 728  * or those using the Supplier-based factory forms, are immune to
 729  * modifications of the data source prior to commencement of the terminal
 730  * operation (provided the behavioral parameters to the stream operations meet
 731  * the required criteria for non-interference and statelessness).  See
 732  * <a href="package-summary.html#NonInterference">Non-Interference</a>
 733  * for more details.
 734  *
 735  * @since 1.8
 736  */
 737 package java.util.stream;
 738 
 739 import java.util.function.BinaryOperator;
 740 import java.util.function.UnaryOperator;