1 /*
2 * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25 package java.util.stream;
26
27 import java.util.Objects;
28 import java.util.Spliterator;
29 import java.util.function.IntFunction;
30 import java.util.function.Supplier;
31
32 /**
33 * Abstract base class for "pipeline" classes, which are the core
34 * implementations of the Stream interface and its primitive specializations.
35 * Manages construction and evaluation of stream pipelines.
36 *
37 * <p>An {@code AbstractPipeline} represents an initial portion of a stream
38 * pipeline, encapsulating a stream source and zero or more intermediate
39 * operations. The individual {@code AbstractPipeline} objects are often
40 * referred to as <em>stages</em>, where each stage describes either the stream
41 * source or an intermediate operation.
42 *
43 * <p>A concrete intermediate stage is generally built from an
44 * {@code AbstractPipeline}, a shape-specific pipeline class which extends it
45 * (e.g., {@code IntPipeline}) which is also abstract, and an operation-specific
46 * concrete class which extends that. {@code AbstractPipeline} contains most of
47 * the mechanics of evaluating the pipeline, and implements methods that will be
48 * used by the operation; the shape-specific classes add helper methods for
49 * dealing with collection of results into the appropriate shape-specific
50 * containers.
51 *
52 * <p>After chaining a new intermediate operation, or executing a terminal
53 * operation, the stream is considered to be consumed, and no more intermediate
54 * or terminal operations are permitted on this stream instance.
55 *
56 * @implNote
57 * <p>For sequential streams, and parallel streams without
58 * <a href="package-summary.html#StreamOps">stateful intermediate
59 * operations</a>, parallel streams, pipeline evaluation is done in a single
60 * pass that "jams" all the operations together. For parallel streams with
61 * stateful operations, execution is divided into segments, where each
62 * stateful operations marks the end of a segment, and each segment is
63 * evaluated separately and the result used as the input to the next
64 * segment. In all cases, the source data is not consumed until a terminal
65 * operation begins.
66 *
67 * @param <E_IN> type of input elements
68 * @param <E_OUT> type of output elements
69 * @param <S> type of the subclass implementing {@code BaseStream}
70 * @since 1.8
71 */
72 abstract class AbstractPipeline<E_IN, E_OUT, S extends BaseStream<E_OUT, S>>
73 extends PipelineHelper<E_OUT> implements BaseStream<E_OUT, S> {
74 /**
75 * Backlink to the head of the pipeline chain (self if this is the source
76 * stage).
77 */
78 @SuppressWarnings("rawtypes")
79 private final AbstractPipeline sourceStage;
80
81 /**
82 * The "upstream" pipeline, or null if this is the source stage.
83 */
84 @SuppressWarnings("rawtypes")
85 private final AbstractPipeline previousStage;
86
87 /**
88 * The operation flags for the intermediate operation represented by this
89 * pipeline object.
90 */
91 protected final int sourceOrOpFlags;
92
93 /**
94 * The next stage in the pipeline, or null if this is the last stage.
95 * Effectively final at the point of linking to the next pipeline.
96 */
97 @SuppressWarnings("rawtypes")
98 private AbstractPipeline nextStage;
99
100 /**
101 * The number of intermediate operations between this pipeline object
102 * and the stream source if sequential, or the previous stateful if parallel.
103 * Valid at the point of pipeline preparation for evaluation.
104 */
105 private int depth;
106
107 /**
108 * The combined source and operation flags for the source and all operations
109 * up to and including the operation represented by this pipeline object.
110 * Valid at the point of pipeline preparation for evaluation.
111 */
112 private int combinedFlags;
113
114 /**
115 * The source spliterator. Only valid for the head pipeline.
116 * Before the pipeline is consumed if non-null then {@code sourceSupplier}
117 * must be null. After the pipeline is consumed if non-null then is set to
118 * null.
119 */
120 private Spliterator<?> sourceSpliterator;
121
122 /**
123 * The source supplier. Only valid for the head pipeline. Before the
124 * pipeline is consumed if non-null then {@code sourceSpliterator} must be
125 * null. After the pipeline is consumed if non-null then is set to null.
126 */
127 private Supplier<? extends Spliterator<?>> sourceSupplier;
128
129 /**
130 * True if this pipeline has been linked or consumed
131 */
132 private boolean linkedOrConsumed;
133
134 /**
135 * True if there are any stateful ops in the pipeline; only valid for the
136 * source stage.
137 */
138 private boolean sourceAnyStateful;
139
140 /**
141 * True if pipeline is parallel, otherwise the pipeline is sequential; only
142 * valid for the source stage.
143 */
144 private boolean parallel;
145
146 /**
147 * Constructor for the head of a stream pipeline.
148 *
149 * @param source {@code Supplier<Spliterator>} describing the stream source
150 * @param sourceFlags The source flags for the stream source, described in
151 * {@link StreamOpFlag}
152 * @param parallel True if the pipeline is parallel
153 */
154 AbstractPipeline(Supplier<? extends Spliterator<?>> source,
155 int sourceFlags, boolean parallel) {
156 this.previousStage = null;
157 this.sourceSupplier = source;
158 this.sourceStage = this;
159 this.sourceOrOpFlags = sourceFlags & StreamOpFlag.STREAM_MASK;
160 // The following is an optimization of:
161 // StreamOpFlag.combineOpFlags(sourceOrOpFlags, StreamOpFlag.INITIAL_OPS_VALUE);
162 this.combinedFlags = (~(sourceOrOpFlags << 1)) & StreamOpFlag.INITIAL_OPS_VALUE;
163 this.depth = 0;
164 this.parallel = parallel;
165 }
166
167 /**
168 * Constructor for the head of a stream pipeline.
169 *
170 * @param source {@code Spliterator} describing the stream source
171 * @param sourceFlags the source flags for the stream source, described in
172 * {@link StreamOpFlag}
173 * @param parallel {@code true} if the pipeline is parallel
174 */
175 AbstractPipeline(Spliterator<?> source,
176 int sourceFlags, boolean parallel) {
177 this.previousStage = null;
178 this.sourceSpliterator = source;
179 this.sourceStage = this;
180 this.sourceOrOpFlags = sourceFlags & StreamOpFlag.STREAM_MASK;
181 // The following is an optimization of:
182 // StreamOpFlag.combineOpFlags(sourceOrOpFlags, StreamOpFlag.INITIAL_OPS_VALUE);
183 this.combinedFlags = (~(sourceOrOpFlags << 1)) & StreamOpFlag.INITIAL_OPS_VALUE;
184 this.depth = 0;
185 this.parallel = parallel;
186 }
187
188 /**
189 * Constructor for appending an intermediate operation stage onto an
190 * existing pipeline.
191 *
192 * @param previousStage the upstream pipeline stage
193 * @param opFlags the operation flags for the new stage, described in
194 * {@link StreamOpFlag}
195 */
196 AbstractPipeline(AbstractPipeline<?, E_IN, ?> previousStage, int opFlags) {
197 if (previousStage.linkedOrConsumed)
198 throw new IllegalStateException("stream has already been operated upon");
199 previousStage.linkedOrConsumed = true;
200 previousStage.nextStage = this;
201
202 this.previousStage = previousStage;
203 this.sourceOrOpFlags = opFlags & StreamOpFlag.OP_MASK;
204 this.combinedFlags = StreamOpFlag.combineOpFlags(opFlags, previousStage.combinedFlags);
205 this.sourceStage = previousStage.sourceStage;
206 if (opIsStateful())
207 sourceStage.sourceAnyStateful = true;
208 this.depth = previousStage.depth + 1;
209 }
210
211
212 // Terminal evaluation methods
213
214 /**
215 * Evaluate the pipeline with a terminal operation to produce a result.
216 *
217 * @param <R> the type of result
218 * @param terminalOp the terminal operation to be applied to the pipeline.
219 * @return the result
220 */
221 final <R> R evaluate(TerminalOp<E_OUT, R> terminalOp) {
222 assert getOutputShape() == terminalOp.inputShape();
223 if (linkedOrConsumed)
224 throw new IllegalStateException("stream has already been operated upon");
225 linkedOrConsumed = true;
226
227 return isParallel()
228 ? terminalOp.evaluateParallel(this, sourceSpliterator(terminalOp.getOpFlags()))
229 : terminalOp.evaluateSequential(this, sourceSpliterator(terminalOp.getOpFlags()));
230 }
231
232 /**
233 * Collect the elements output from the pipeline stage.
234 *
235 * @param generator the array generator to be used to create array instances
236 * @return a flat array-backed Node that holds the collected output elements
237 */
238 @SuppressWarnings("unchecked")
239 final Node<E_OUT> evaluateToArrayNode(IntFunction<E_OUT[]> generator) {
240 if (linkedOrConsumed)
241 throw new IllegalStateException("stream has already been operated upon");
242 linkedOrConsumed = true;
243
244 // If the last intermediate operation is stateful then
245 // evaluate directly to avoid an extra collection step
246 if (isParallel() && previousStage != null && opIsStateful()) {
247 return opEvaluateParallel(previousStage, previousStage.sourceSpliterator(0), generator);
248 }
249 else {
250 return evaluate(sourceSpliterator(0), true, generator);
251 }
252 }
253
254 /**
255 * Gets the source stage spliterator if this pipeline stage is the source
256 * stage. The pipeline is consumed after this method is called and
257 * returns successfully.
258 *
259 * @return the source stage spliterator
260 * @throws IllegalStateException if this pipeline stage is not the source
261 * stage.
262 */
263 @SuppressWarnings("unchecked")
264 final Spliterator<E_OUT> sourceStageSpliterator() {
265 if (this != sourceStage)
266 throw new IllegalStateException();
267
268 if (linkedOrConsumed)
269 throw new IllegalStateException("stream has already been operated upon");
270 linkedOrConsumed = true;
271
272 if (sourceStage.sourceSpliterator != null) {
273 @SuppressWarnings("unchecked")
274 Spliterator<E_OUT> s = sourceStage.sourceSpliterator;
275 sourceStage.sourceSpliterator = null;
276 return s;
277 }
278 else if (sourceStage.sourceSupplier != null) {
279 @SuppressWarnings("unchecked")
280 Spliterator<E_OUT> s = (Spliterator<E_OUT>) sourceStage.sourceSupplier.get();
281 sourceStage.sourceSupplier = null;
282 return s;
283 }
284 else {
285 throw new IllegalStateException("source already consumed");
286 }
287 }
288
289 // BaseStream
290
291 @Override
292 @SuppressWarnings("unchecked")
293 public final S sequential() {
294 sourceStage.parallel = false;
295 return (S) this;
296 }
297
298 @Override
299 @SuppressWarnings("unchecked")
300 public final S parallel() {
301 sourceStage.parallel = true;
302 return (S) this;
303 }
304
305 // Primitive specialization use co-variant overrides, hence is not final
306 @Override
307 @SuppressWarnings("unchecked")
308 public Spliterator<E_OUT> spliterator() {
309 if (linkedOrConsumed)
310 throw new IllegalStateException("stream has already been operated upon");
311 linkedOrConsumed = true;
312
313 if (this == sourceStage) {
314 if (sourceStage.sourceSpliterator != null) {
315 @SuppressWarnings("unchecked")
316 Spliterator<E_OUT> s = (Spliterator<E_OUT>) sourceStage.sourceSpliterator;
317 sourceStage.sourceSpliterator = null;
318 return s;
319 }
320 else if (sourceStage.sourceSupplier != null) {
321 @SuppressWarnings("unchecked")
322 Supplier<Spliterator<E_OUT>> s = (Supplier<Spliterator<E_OUT>>) sourceStage.sourceSupplier;
323 sourceStage.sourceSupplier = null;
324 return lazySpliterator(s);
325 }
326 else {
327 throw new IllegalStateException("source already consumed");
328 }
329 }
330 else {
331 return wrap(this, () -> sourceSpliterator(0), isParallel());
332 }
333 }
334
335 @Override
336 public final boolean isParallel() {
337 return sourceStage.parallel;
338 }
339
340
341 /**
342 * Returns the composition of stream flags of the stream source and all
343 * intermediate operations.
344 *
345 * @return the composition of stream flags of the stream source and all
346 * intermediate operations
347 * @see StreamOpFlag
348 */
349 final int getStreamFlags() {
350 return StreamOpFlag.toStreamFlags(combinedFlags);
351 }
352
353 /**
354 * Prepare the pipeline for a parallel execution. As the pipeline is built,
355 * the flags and depth indicators are set up for a sequential execution.
356 * If the execution is parallel, and there are any stateful operations, then
357 * some of these need to be adjusted, as well as adjusting for flags from
358 * the terminal operation (such as back-propagating UNORDERED).
359 * Need not be called for a sequential execution.
360 *
361 * @param terminalFlags Operation flags for the terminal operation
362 */
363 private void parallelPrepare(int terminalFlags) {
364 @SuppressWarnings("rawtypes")
365 AbstractPipeline backPropagationHead = sourceStage;
366 if (sourceStage.sourceAnyStateful) {
367 int depth = 1;
368 for ( @SuppressWarnings("rawtypes") AbstractPipeline u = sourceStage, p = sourceStage.nextStage;
369 p != null;
370 u = p, p = p.nextStage) {
371 int thisOpFlags = p.sourceOrOpFlags;
372 if (p.opIsStateful()) {
373 // If the stateful operation is a short-circuit operation
374 // then move the back propagation head forwards
375 // NOTE: there are no size-injecting ops
376 if (StreamOpFlag.SHORT_CIRCUIT.isKnown(thisOpFlags)) {
377 backPropagationHead = p;
378 // Clear the short circuit flag for next pipeline stage
379 // This stage encapsulates short-circuiting, the next
380 // stage may not have any short-circuit operations, and
381 // if so spliterator.forEachRemaining should be be used
382 // for traversal
383 thisOpFlags = thisOpFlags & ~StreamOpFlag.IS_SHORT_CIRCUIT;
384 }
385
386 depth = 0;
387 // The following injects size, it is equivalent to:
388 // StreamOpFlag.combineOpFlags(StreamOpFlag.IS_SIZED, p.combinedFlags);
389 thisOpFlags = (thisOpFlags & ~StreamOpFlag.NOT_SIZED) | StreamOpFlag.IS_SIZED;
390 }
391 p.depth = depth++;
392 p.combinedFlags = StreamOpFlag.combineOpFlags(thisOpFlags, u.combinedFlags);
393 }
394 }
395
396 // Apply the upstream terminal flags
397 if (terminalFlags != 0) {
398 int upstreamTerminalFlags = terminalFlags & StreamOpFlag.UPSTREAM_TERMINAL_OP_MASK;
399 for ( @SuppressWarnings("rawtypes") AbstractPipeline p = backPropagationHead; p.nextStage != null; p = p.nextStage) {
400 p.combinedFlags = StreamOpFlag.combineOpFlags(upstreamTerminalFlags, p.combinedFlags);
401 }
402
403 combinedFlags = StreamOpFlag.combineOpFlags(terminalFlags, combinedFlags);
404 }
405 }
406
407 /**
408 * Get the source spliterator for this pipeline stage. For a sequential or
409 * stateless parallel pipeline, this is the source spliterator. For a
410 * stateful parallel pipeline, this is a spliterator describing the results
411 * of all computations up to and including the most recent stateful
412 * operation.
413 */
414 @SuppressWarnings("unchecked")
415 private Spliterator<?> sourceSpliterator(int terminalFlags) {
416 // Get the source spliterator of the pipeline
417 Spliterator<?> spliterator = null;
418 if (sourceStage.sourceSpliterator != null) {
419 spliterator = sourceStage.sourceSpliterator;
420 sourceStage.sourceSpliterator = null;
421 }
422 else if (sourceStage.sourceSupplier != null) {
423 spliterator = (Spliterator<?>) sourceStage.sourceSupplier.get();
424 sourceStage.sourceSupplier = null;
425 }
426 else {
427 throw new IllegalStateException("source already consumed");
428 }
429
430 if (isParallel()) {
431 // @@@ Merge parallelPrepare with the loop below and use the
432 // spliterator characteristics to determine if SIZED
433 // should be injected
434 parallelPrepare(terminalFlags);
435
436 // Adapt the source spliterator, evaluating each stateful op
437 // in the pipeline up to and including this pipeline stage
438 for ( @SuppressWarnings("rawtypes") AbstractPipeline u = sourceStage, p = sourceStage.nextStage, e = this;
439 u != e;
440 u = p, p = p.nextStage) {
441
442 if (p.opIsStateful()) {
443 spliterator = p.opEvaluateParallelLazy(u, spliterator);
444 }
445 }
446 }
447 else if (terminalFlags != 0) {
448 combinedFlags = StreamOpFlag.combineOpFlags(terminalFlags, combinedFlags);
449 }
450
451 return spliterator;
452 }
453
454
455 // PipelineHelper
456
457 @Override
458 final StreamShape getSourceShape() {
459 @SuppressWarnings("rawtypes")
460 AbstractPipeline p = AbstractPipeline.this;
461 while (p.depth > 0) {
462 p = p.previousStage;
463 }
464 return p.getOutputShape();
465 }
466
467 @Override
468 final <P_IN> long exactOutputSizeIfKnown(Spliterator<P_IN> spliterator) {
469 return StreamOpFlag.SIZED.isKnown(getStreamAndOpFlags()) ? spliterator.getExactSizeIfKnown() : -1;
470 }
471
472 @Override
473 final <P_IN, S extends Sink<E_OUT>> S wrapAndCopyInto(S sink, Spliterator<P_IN> spliterator) {
474 copyInto(wrapSink(Objects.requireNonNull(sink)), spliterator);
475 return sink;
476 }
477
478 @Override
479 final <P_IN> void copyInto(Sink<P_IN> wrappedSink, Spliterator<P_IN> spliterator) {
480 Objects.requireNonNull(wrappedSink);
481
482 if (!StreamOpFlag.SHORT_CIRCUIT.isKnown(getStreamAndOpFlags())) {
483 wrappedSink.begin(spliterator.getExactSizeIfKnown());
484 spliterator.forEachRemaining(wrappedSink);
485 wrappedSink.end();
486 }
487 else {
488 copyIntoWithCancel(wrappedSink, spliterator);
489 }
490 }
491
492 @Override
493 @SuppressWarnings("unchecked")
494 final <P_IN> void copyIntoWithCancel(Sink<P_IN> wrappedSink, Spliterator<P_IN> spliterator) {
495 @SuppressWarnings({"rawtypes","unchecked"})
496 AbstractPipeline p = AbstractPipeline.this;
497 while (p.depth > 0) {
498 p = p.previousStage;
499 }
500 wrappedSink.begin(spliterator.getExactSizeIfKnown());
501 p.forEachWithCancel(spliterator, wrappedSink);
502 wrappedSink.end();
503 }
504
505 @Override
506 final int getStreamAndOpFlags() {
507 return combinedFlags;
508 }
509
510 final boolean isOrdered() {
511 return StreamOpFlag.ORDERED.isKnown(combinedFlags);
512 }
513
514 @Override
515 @SuppressWarnings("unchecked")
516 final <P_IN> Sink<P_IN> wrapSink(Sink<E_OUT> sink) {
517 Objects.requireNonNull(sink);
518
519 for ( @SuppressWarnings("rawtypes") AbstractPipeline p=AbstractPipeline.this; p.depth > 0; p=p.previousStage) {
520 sink = p.opWrapSink(p.previousStage.combinedFlags, sink);
521 }
522 return (Sink<P_IN>) sink;
523 }
524
525 @Override
526 @SuppressWarnings("unchecked")
527 final <P_IN> Spliterator<E_OUT> wrapSpliterator(Spliterator<P_IN> sourceSpliterator) {
528 if (depth == 0) {
529 return (Spliterator<E_OUT>) sourceSpliterator;
530 }
531 else {
532 return wrap(this, () -> sourceSpliterator, isParallel());
533 }
534 }
535
536 @Override
537 @SuppressWarnings("unchecked")
538 final <P_IN> Node<E_OUT> evaluate(Spliterator<P_IN> spliterator,
539 boolean flatten,
540 IntFunction<E_OUT[]> generator) {
541 if (isParallel()) {
542 // @@@ Optimize if op of this pipeline stage is a stateful op
543 return evaluateToNode(this, spliterator, flatten, generator);
544 }
545 else {
546 Node.Builder<E_OUT> nb = makeNodeBuilder(
547 exactOutputSizeIfKnown(spliterator), generator);
548 return wrapAndCopyInto(nb, spliterator).build();
549 }
550 }
551
552
553 // Shape-specific abstract methods, implemented by XxxPipeline classes
554
555 /**
556 * Get the output shape of the pipeline. If the pipeline is the head,
557 * then it's output shape corresponds to the shape of the source.
558 * Otherwise, it's output shape corresponds to the output shape of the
559 * associated operation.
560 *
561 * @return the output shape
562 */
563 abstract StreamShape getOutputShape();
564
565 /**
566 * Collect elements output from a pipeline into a Node that holds elements
567 * of this shape.
568 *
569 * @param helper the pipeline helper describing the pipeline stages
570 * @param spliterator the source spliterator
571 * @param flattenTree true if the returned node should be flattened
572 * @param generator the array generator
573 * @return a Node holding the output of the pipeline
574 */
575 abstract <P_IN> Node<E_OUT> evaluateToNode(PipelineHelper<E_OUT> helper,
576 Spliterator<P_IN> spliterator,
577 boolean flattenTree,
578 IntFunction<E_OUT[]> generator);
579
580 /**
581 * Create a spliterator that wraps a source spliterator, compatible with
582 * this stream shape, and operations associated with a {@link
583 * PipelineHelper}.
584 *
585 * @param ph the pipeline helper describing the pipeline stages
586 * @param supplier the supplier of a spliterator
587 * @return a wrapping spliterator compatible with this shape
588 */
589 abstract <P_IN> Spliterator<E_OUT> wrap(PipelineHelper<E_OUT> ph,
590 Supplier<Spliterator<P_IN>> supplier,
591 boolean isParallel);
592
593 /**
594 * Create a lazy spliterator that wraps and obtains the supplied the
595 * spliterator when a method is invoked on the lazy spliterator.
596 * @param supplier the supplier of a spliterator
597 */
598 abstract Spliterator<E_OUT> lazySpliterator(Supplier<? extends Spliterator<E_OUT>> supplier);
599
600 /**
601 * Traverse the elements of a spliterator compatible with this stream shape,
602 * pushing those elements into a sink. If the sink requests cancellation,
603 * no further elements will be pulled or pushed.
604 *
605 * @param spliterator the spliterator to pull elements from
606 * @param sink the sink to push elements to
607 */
608 abstract void forEachWithCancel(Spliterator<E_OUT> spliterator, Sink<E_OUT> sink);
609
610 /**
611 * Make a node builder compatible with this stream shape.
612 *
613 * @param exactSizeIfKnown if {@literal >=0}, then a node builder will be
614 * created that has a fixed capacity of at most sizeIfKnown elements. If
615 * {@literal < 0}, then the node builder has an unfixed capacity. A fixed
616 * capacity node builder will throw exceptions if an element is added after
617 * builder has reached capacity, or is built before the builder has reached
618 * capacity.
619 *
620 * @param generator the array generator to be used to create instances of a
621 * T[] array. For implementations supporting primitive nodes, this parameter
622 * may be ignored.
623 * @return a node builder
624 */
625 @Override
626 abstract Node.Builder<E_OUT> makeNodeBuilder(long exactSizeIfKnown,
627 IntFunction<E_OUT[]> generator);
628
629
630 // Op-specific abstract methods, implemented by the operation class
631
632 /**
633 * Returns whether this operation is stateful or not. If it is stateful,
634 * then the method
635 * {@link #opEvaluateParallel(PipelineHelper, java.util.Spliterator, java.util.function.IntFunction)}
636 * must be overridden.
637 *
638 * @return {@code true} if this operation is stateful
639 */
640 abstract boolean opIsStateful();
641
642 /**
643 * Accepts a {@code Sink} which will receive the results of this operation,
644 * and return a {@code Sink} which accepts elements of the input type of
645 * this operation and which performs the operation, passing the results to
646 * the provided {@code Sink}.
647 *
648 * @apiNote
649 * The implementation may use the {@code flags} parameter to optimize the
650 * sink wrapping. For example, if the input is already {@code DISTINCT},
651 * the implementation for the {@code Stream#distinct()} method could just
652 * return the sink it was passed.
653 *
654 * @param flags The combined stream and operation flags up to, but not
655 * including, this operation
656 * @param sink sink to which elements should be sent after processing
657 * @return a sink which accepts elements, perform the operation upon
658 * each element, and passes the results (if any) to the provided
659 * {@code Sink}.
660 */
661 abstract Sink<E_IN> opWrapSink(int flags, Sink<E_OUT> sink);
662
663 /**
664 * Performs a parallel evaluation of the operation using the specified
665 * {@code PipelineHelper} which describes the upstream intermediate
666 * operations. Only called on stateful operations. If {@link
667 * #opIsStateful()} returns true then implementations must override the
668 * default implementation.
669 *
670 * @implSpec The default implementation always throw
671 * {@code UnsupportedOperationException}.
672 *
673 * @param helper the pipeline helper describing the pipeline stages
674 * @param spliterator the source {@code Spliterator}
675 * @param generator the array generator
676 * @return a {@code Node} describing the result of the evaluation
677 */
678 <P_IN> Node<E_OUT> opEvaluateParallel(PipelineHelper<E_OUT> helper,
679 Spliterator<P_IN> spliterator,
680 IntFunction<E_OUT[]> generator) {
681 throw new UnsupportedOperationException("Parallel evaluation is not supported");
682 }
683
684 /**
685 * Returns a {@code Spliterator} describing a parallel evaluation of the
686 * operation, using the specified {@code PipelineHelper} which describes the
687 * upstream intermediate operations. Only called on stateful operations.
688 * It is not necessary (though acceptable) to do a full computation of the
689 * result here; it is preferable, if possible, to describe the result via a
690 * lazily evaluated spliterator.
691 *
692 * @implSpec The default implementation behaves as if:
693 * <pre>{@code
694 * return evaluateParallel(helper, i -> (E_OUT[]) new
695 * Object[i]).spliterator();
696 * }</pre>
697 * and is suitable for implementations that cannot do better than a full
698 * synchronous evaluation.
699 *
700 * @param helper the pipeline helper
701 * @param spliterator the source {@code Spliterator}
702 * @return a {@code Spliterator} describing the result of the evaluation
703 */
704 @SuppressWarnings("unchecked")
705 <P_IN> Spliterator<E_OUT> opEvaluateParallelLazy(PipelineHelper<E_OUT> helper,
706 Spliterator<P_IN> spliterator) {
707 return opEvaluateParallel(helper, spliterator, i -> (E_OUT[]) new Object[i]).spliterator();
708 }
709 }