--- /dev/null 2013-03-09 17:25:01.184291984 -0500 +++ new/src/share/classes/java/util/stream/StatefulOp.java 2013-03-11 17:44:02.000000000 -0400 @@ -0,0 +1,49 @@ +package java.util.stream; + +/** + * A stateful intermediate stream operation ({@link IntermediateOp}). + * Stateful means that state is accumulated as elements are processed. + * Examples of stateful operations are sorting, extracting a subsequence of the + * input, or removing duplicates. Statefulness has an effect on how the + * operation can be parallelized. Stateless operations parallelize trivially + * because they are homomorphisms under concatenation: + * + *
+ *     statelessOp(a || b) = statelessOp(a) || statelessOp(b)
+ * 
+ * + * where {@code ||} denotes concatenation. Stateful operations may still be + * parallelizable, but are not amenable to the automatic parallelization of + * stateless operations. Accordingly, a stateful operation must provide its + * own parallel execution implementation + * ({@link #evaluateParallel(PipelineHelper)}). + * + * @param Type of input and output elements. + * + * @see IntermediateOp + * @see TerminalOp + * @since 1.8 + */ +interface StatefulOp extends IntermediateOp { + + /** + * Returns {@code true}. Any overriding implementations must also return + * {@code true} + * @implSpec The default implementation returns {@code true} + * @return {@code true} + */ + @Override + default boolean isStateful() { + return true; + } + + /** + * {@inheritDoc} + * + * An implementation of this method must be provided, but it is acceptable + * if the implementation is sequential. A generic sequential implementation + * is available as + * {@link PipelineHelper#evaluateSequential(IntermediateOp)}. + */ + Node evaluateParallel(PipelineHelper helper); +}