1 package java.util.stream;
   2 
   3 /**
   4  * A stateful intermediate stream operation ({@link IntermediateOp}).
   5  * <em>Stateful</em> means that state is accumulated as elements are processed.
   6  * Examples of stateful operations are sorting, extracting a subsequence of the
   7  * input, or removing duplicates.  Statefulness has an effect on how the
   8  * operation can be parallelized.  Stateless operations parallelize trivially
   9  * because they are homomorphisms under concatenation:
  10  *
  11  * <pre>
  12  *     statelessOp(a || b) = statelessOp(a) || statelessOp(b)
  13  * </pre>
  14  *
  15  * where {@code ||} denotes concatenation.  Stateful operations may still be
  16  * parallelizable, but are not amenable to the automatic parallelization of
  17  * stateless operations.  Accordingly, a stateful operation must provide its
  18  * own parallel execution implementation
  19  * ({@link #evaluateParallel(PipelineHelper)}).
  20  *
  21  * @param <E> Type of input and output elements.
  22  *
  23  * @see IntermediateOp
  24  * @see TerminalOp
  25  * @since 1.8
  26  */
  27 interface StatefulOp<E> extends IntermediateOp<E, E> {
  28 
  29     /**
  30      * Returns {@code true}.  Any overriding implementations must also return
  31      * {@code true}
  32      * @implSpec The default implementation returns {@code true}
  33      * @return {@code true}
  34      */
  35     @Override
  36     default boolean isStateful() {
  37         return true;
  38     }
  39 
  40     /**
  41      * {@inheritDoc}
  42      *
  43      * An implementation of this method must be provided, but it is acceptable
  44      * if the implementation is sequential.  A generic sequential implementation
  45      * is available as
  46      * {@link PipelineHelper#evaluateSequential(IntermediateOp)}.
  47      */
  48     <P_IN> Node<E> evaluateParallel(PipelineHelper<P_IN, E> helper);
  49 }