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 private static final String MSG_STREAM_LINKED = "stream has already been operated upon or closed";
75 private static final String MSG_CONSUMED = "source already consumed or closed";
76
77 /**
78 * Backlink to the head of the pipeline chain (self if this is the source
79 * stage).
80 */
81 @SuppressWarnings("rawtypes")
82 private final AbstractPipeline sourceStage;
83
84 /**
85 * The "upstream" pipeline, or null if this is the source stage.
86 */
87 @SuppressWarnings("rawtypes")
88 private final AbstractPipeline previousStage;
89
90 /**
91 * The operation flags for the intermediate operation represented by this
92 * pipeline object.
93 */
94 protected final int sourceOrOpFlags;
95
96 /**
97 * The next stage in the pipeline, or null if this is the last stage.
98 * Effectively final at the point of linking to the next pipeline.
99 */
100 @SuppressWarnings("rawtypes")
101 private AbstractPipeline nextStage;
102
103 /**
104 * The number of intermediate operations between this pipeline object
105 * and the stream source if sequential, or the previous stateful if parallel.
106 * Valid at the point of pipeline preparation for evaluation.
107 */
108 private int depth;
109
110 /**
111 * The combined source and operation flags for the source and all operations
112 * up to and including the operation represented by this pipeline object.
113 * Valid at the point of pipeline preparation for evaluation.
114 */
115 private int combinedFlags;
116
117 /**
118 * The source spliterator. Only valid for the head pipeline.
119 * Before the pipeline is consumed if non-null then {@code sourceSupplier}
120 * must be null. After the pipeline is consumed if non-null then is set to
121 * null.
122 */
123 private Spliterator<?> sourceSpliterator;
124
125 /**
126 * The source supplier. Only valid for the head pipeline. Before the
127 * pipeline is consumed if non-null then {@code sourceSpliterator} must be
128 * null. After the pipeline is consumed if non-null then is set to null.
129 */
130 private Supplier<? extends Spliterator<?>> sourceSupplier;
131
132 /**
133 * True if this pipeline has been linked or consumed
134 */
135 private boolean linkedOrConsumed;
136
137 /**
138 * True if there are any stateful ops in the pipeline; only valid for the
139 * source stage.
140 */
141 private boolean sourceAnyStateful;
142
143 private Runnable sourceCloseAction;
144
145 /**
146 * True if pipeline is parallel, otherwise the pipeline is sequential; only
147 * valid for the source stage.
148 */
149 private boolean parallel;
150
151 /**
152 * Constructor for the head of a stream pipeline.
153 *
154 * @param source {@code Supplier<Spliterator>} describing the stream source
155 * @param sourceFlags The source flags for the stream source, described in
156 * {@link StreamOpFlag}
157 * @param parallel True if the pipeline is parallel
158 */
159 AbstractPipeline(Supplier<? extends Spliterator<?>> source,
160 int sourceFlags, boolean parallel) {
161 this.previousStage = null;
162 this.sourceSupplier = source;
163 this.sourceStage = this;
164 this.sourceOrOpFlags = sourceFlags & StreamOpFlag.STREAM_MASK;
165 // The following is an optimization of:
166 // StreamOpFlag.combineOpFlags(sourceOrOpFlags, StreamOpFlag.INITIAL_OPS_VALUE);
167 this.combinedFlags = (~(sourceOrOpFlags << 1)) & StreamOpFlag.INITIAL_OPS_VALUE;
168 this.depth = 0;
169 this.parallel = parallel;
170 }
171
172 /**
173 * Constructor for the head of a stream pipeline.
174 *
175 * @param source {@code Spliterator} describing the stream source
176 * @param sourceFlags the source flags for the stream source, described in
177 * {@link StreamOpFlag}
178 * @param parallel {@code true} if the pipeline is parallel
179 */
180 AbstractPipeline(Spliterator<?> source,
181 int sourceFlags, boolean parallel) {
182 this.previousStage = null;
183 this.sourceSpliterator = source;
184 this.sourceStage = this;
185 this.sourceOrOpFlags = sourceFlags & StreamOpFlag.STREAM_MASK;
186 // The following is an optimization of:
187 // StreamOpFlag.combineOpFlags(sourceOrOpFlags, StreamOpFlag.INITIAL_OPS_VALUE);
188 this.combinedFlags = (~(sourceOrOpFlags << 1)) & StreamOpFlag.INITIAL_OPS_VALUE;
189 this.depth = 0;
190 this.parallel = parallel;
191 }
192
193 /**
194 * Constructor for appending an intermediate operation stage onto an
195 * existing pipeline.
196 *
197 * @param previousStage the upstream pipeline stage
198 * @param opFlags the operation flags for the new stage, described in
199 * {@link StreamOpFlag}
200 */
201 AbstractPipeline(AbstractPipeline<?, E_IN, ?> previousStage, int opFlags) {
202 if (previousStage.linkedOrConsumed)
203 throw new IllegalStateException(MSG_STREAM_LINKED);
204 previousStage.linkedOrConsumed = true;
205 previousStage.nextStage = this;
206
207 this.previousStage = previousStage;
208 this.sourceOrOpFlags = opFlags & StreamOpFlag.OP_MASK;
209 this.combinedFlags = StreamOpFlag.combineOpFlags(opFlags, previousStage.combinedFlags);
210 this.sourceStage = previousStage.sourceStage;
211 if (opIsStateful())
212 sourceStage.sourceAnyStateful = true;
213 this.depth = previousStage.depth + 1;
214 }
215
216
217 // Terminal evaluation methods
218
219 /**
220 * Evaluate the pipeline with a terminal operation to produce a result.
221 *
222 * @param <R> the type of result
223 * @param terminalOp the terminal operation to be applied to the pipeline.
224 * @return the result
225 */
226 final <R> R evaluate(TerminalOp<E_OUT, R> terminalOp) {
227 assert getOutputShape() == terminalOp.inputShape();
228 if (linkedOrConsumed)
229 throw new IllegalStateException(MSG_STREAM_LINKED);
230 linkedOrConsumed = true;
231
232 return isParallel()
233 ? terminalOp.evaluateParallel(this, sourceSpliterator(terminalOp.getOpFlags()))
234 : terminalOp.evaluateSequential(this, sourceSpliterator(terminalOp.getOpFlags()));
235 }
236
237 /**
238 * Collect the elements output from the pipeline stage.
239 *
240 * @param generator the array generator to be used to create array instances
241 * @return a flat array-backed Node that holds the collected output elements
242 */
243 @SuppressWarnings("unchecked")
244 final Node<E_OUT> evaluateToArrayNode(IntFunction<E_OUT[]> generator) {
245 if (linkedOrConsumed)
246 throw new IllegalStateException(MSG_STREAM_LINKED);
247 linkedOrConsumed = true;
248
249 // If the last intermediate operation is stateful then
250 // evaluate directly to avoid an extra collection step
251 if (isParallel() && previousStage != null && opIsStateful()) {
252 return opEvaluateParallel(previousStage, previousStage.sourceSpliterator(0), generator);
253 }
254 else {
255 return evaluate(sourceSpliterator(0), true, generator);
256 }
257 }
258
259 /**
260 * Gets the source stage spliterator if this pipeline stage is the source
261 * stage. The pipeline is consumed after this method is called and
262 * returns successfully.
263 *
264 * @return the source stage spliterator
265 * @throws IllegalStateException if this pipeline stage is not the source
266 * stage.
267 */
268 @SuppressWarnings("unchecked")
269 final Spliterator<E_OUT> sourceStageSpliterator() {
270 if (this != sourceStage)
271 throw new IllegalStateException();
272
273 if (linkedOrConsumed)
274 throw new IllegalStateException(MSG_STREAM_LINKED);
275 linkedOrConsumed = true;
276
277 if (sourceStage.sourceSpliterator != null) {
278 @SuppressWarnings("unchecked")
279 Spliterator<E_OUT> s = sourceStage.sourceSpliterator;
280 sourceStage.sourceSpliterator = null;
281 return s;
282 }
283 else if (sourceStage.sourceSupplier != null) {
284 @SuppressWarnings("unchecked")
285 Spliterator<E_OUT> s = (Spliterator<E_OUT>) sourceStage.sourceSupplier.get();
286 sourceStage.sourceSupplier = null;
287 return s;
288 }
289 else {
290 throw new IllegalStateException(MSG_CONSUMED);
291 }
292 }
293
294 // BaseStream
295
296 @Override
297 @SuppressWarnings("unchecked")
298 public final S sequential() {
299 sourceStage.parallel = false;
300 return (S) this;
301 }
302
303 @Override
304 @SuppressWarnings("unchecked")
305 public final S parallel() {
306 sourceStage.parallel = true;
307 return (S) this;
308 }
309
310 @Override
311 public void close() {
312 linkedOrConsumed = true;
313 sourceSupplier = null;
314 sourceSpliterator = null;
315 if (sourceStage.sourceCloseAction != null) {
316 Runnable closeAction = sourceStage.sourceCloseAction;
317 sourceStage.sourceCloseAction = null;
318 closeAction.run();
319 }
320 }
321
322 @Override
323 @SuppressWarnings("unchecked")
324 public S onClose(Runnable closeHandler) {
325 Runnable existingHandler = sourceStage.sourceCloseAction;
326 sourceStage.sourceCloseAction =
327 (existingHandler == null)
328 ? closeHandler
329 : Streams.composeWithExceptions(existingHandler, closeHandler);
330 return (S) this;
331 }
332
333 // Primitive specialization use co-variant overrides, hence is not final
334 @Override
335 @SuppressWarnings("unchecked")
336 public Spliterator<E_OUT> spliterator() {
337 if (linkedOrConsumed)
338 throw new IllegalStateException(MSG_STREAM_LINKED);
339 linkedOrConsumed = true;
340
341 if (this == sourceStage) {
342 if (sourceStage.sourceSpliterator != null) {
343 @SuppressWarnings("unchecked")
344 Spliterator<E_OUT> s = (Spliterator<E_OUT>) sourceStage.sourceSpliterator;
345 sourceStage.sourceSpliterator = null;
346 return s;
347 }
348 else if (sourceStage.sourceSupplier != null) {
349 @SuppressWarnings("unchecked")
350 Supplier<Spliterator<E_OUT>> s = (Supplier<Spliterator<E_OUT>>) sourceStage.sourceSupplier;
351 sourceStage.sourceSupplier = null;
352 return lazySpliterator(s);
353 }
354 else {
355 throw new IllegalStateException(MSG_CONSUMED);
356 }
357 }
358 else {
359 return wrap(this, () -> sourceSpliterator(0), isParallel());
360 }
361 }
362
363 @Override
364 public final boolean isParallel() {
365 return sourceStage.parallel;
366 }
367
368
369 /**
370 * Returns the composition of stream flags of the stream source and all
371 * intermediate operations.
372 *
373 * @return the composition of stream flags of the stream source and all
374 * intermediate operations
375 * @see StreamOpFlag
376 */
377 final int getStreamFlags() {
378 return StreamOpFlag.toStreamFlags(combinedFlags);
379 }
380
381 /**
382 * Prepare the pipeline for a parallel execution. As the pipeline is built,
383 * the flags and depth indicators are set up for a sequential execution.
384 * If the execution is parallel, and there are any stateful operations, then
385 * some of these need to be adjusted, as well as adjusting for flags from
386 * the terminal operation (such as back-propagating UNORDERED).
387 * Need not be called for a sequential execution.
388 *
389 * @param terminalFlags Operation flags for the terminal operation
390 */
391 private void parallelPrepare(int terminalFlags) {
392 @SuppressWarnings("rawtypes")
393 AbstractPipeline backPropagationHead = sourceStage;
394 if (sourceStage.sourceAnyStateful) {
395 int depth = 1;
396 for ( @SuppressWarnings("rawtypes") AbstractPipeline u = sourceStage, p = sourceStage.nextStage;
397 p != null;
398 u = p, p = p.nextStage) {
399 int thisOpFlags = p.sourceOrOpFlags;
400 if (p.opIsStateful()) {
401 // If the stateful operation is a short-circuit operation
402 // then move the back propagation head forwards
403 // NOTE: there are no size-injecting ops
404 if (StreamOpFlag.SHORT_CIRCUIT.isKnown(thisOpFlags)) {
405 backPropagationHead = p;
406 // Clear the short circuit flag for next pipeline stage
407 // This stage encapsulates short-circuiting, the next
408 // stage may not have any short-circuit operations, and
409 // if so spliterator.forEachRemaining should be be used
410 // for traversal
411 thisOpFlags = thisOpFlags & ~StreamOpFlag.IS_SHORT_CIRCUIT;
412 }
413
414 depth = 0;
415 // The following injects size, it is equivalent to:
416 // StreamOpFlag.combineOpFlags(StreamOpFlag.IS_SIZED, p.combinedFlags);
417 thisOpFlags = (thisOpFlags & ~StreamOpFlag.NOT_SIZED) | StreamOpFlag.IS_SIZED;
418 }
419 p.depth = depth++;
420 p.combinedFlags = StreamOpFlag.combineOpFlags(thisOpFlags, u.combinedFlags);
421 }
422 }
423
424 // Apply the upstream terminal flags
425 if (terminalFlags != 0) {
426 int upstreamTerminalFlags = terminalFlags & StreamOpFlag.UPSTREAM_TERMINAL_OP_MASK;
427 for ( @SuppressWarnings("rawtypes") AbstractPipeline p = backPropagationHead; p.nextStage != null; p = p.nextStage) {
428 p.combinedFlags = StreamOpFlag.combineOpFlags(upstreamTerminalFlags, p.combinedFlags);
429 }
430
431 combinedFlags = StreamOpFlag.combineOpFlags(terminalFlags, combinedFlags);
432 }
433 }
434
435 /**
436 * Get the source spliterator for this pipeline stage. For a sequential or
437 * stateless parallel pipeline, this is the source spliterator. For a
438 * stateful parallel pipeline, this is a spliterator describing the results
439 * of all computations up to and including the most recent stateful
440 * operation.
441 */
442 @SuppressWarnings("unchecked")
443 private Spliterator<?> sourceSpliterator(int terminalFlags) {
444 // Get the source spliterator of the pipeline
445 Spliterator<?> spliterator = null;
446 if (sourceStage.sourceSpliterator != null) {
447 spliterator = sourceStage.sourceSpliterator;
448 sourceStage.sourceSpliterator = null;
449 }
450 else if (sourceStage.sourceSupplier != null) {
451 spliterator = (Spliterator<?>) sourceStage.sourceSupplier.get();
452 sourceStage.sourceSupplier = null;
453 }
454 else {
455 throw new IllegalStateException(MSG_CONSUMED);
456 }
457
458 if (isParallel()) {
459 // @@@ Merge parallelPrepare with the loop below and use the
460 // spliterator characteristics to determine if SIZED
461 // should be injected
462 parallelPrepare(terminalFlags);
463
464 // Adapt the source spliterator, evaluating each stateful op
465 // in the pipeline up to and including this pipeline stage
466 for ( @SuppressWarnings("rawtypes") AbstractPipeline u = sourceStage, p = sourceStage.nextStage, e = this;
467 u != e;
468 u = p, p = p.nextStage) {
469
470 if (p.opIsStateful()) {
471 spliterator = p.opEvaluateParallelLazy(u, spliterator);
472 }
473 }
474 }
475 else if (terminalFlags != 0) {
476 combinedFlags = StreamOpFlag.combineOpFlags(terminalFlags, combinedFlags);
477 }
478
479 return spliterator;
480 }
481
482
483 // PipelineHelper
484
485 @Override
486 final StreamShape getSourceShape() {
487 @SuppressWarnings("rawtypes")
488 AbstractPipeline p = AbstractPipeline.this;
489 while (p.depth > 0) {
490 p = p.previousStage;
491 }
492 return p.getOutputShape();
493 }
494
495 @Override
496 final <P_IN> long exactOutputSizeIfKnown(Spliterator<P_IN> spliterator) {
497 return StreamOpFlag.SIZED.isKnown(getStreamAndOpFlags()) ? spliterator.getExactSizeIfKnown() : -1;
498 }
499
500 @Override
501 final <P_IN, S extends Sink<E_OUT>> S wrapAndCopyInto(S sink, Spliterator<P_IN> spliterator) {
502 copyInto(wrapSink(Objects.requireNonNull(sink)), spliterator);
503 return sink;
504 }
505
506 @Override
507 final <P_IN> void copyInto(Sink<P_IN> wrappedSink, Spliterator<P_IN> spliterator) {
508 Objects.requireNonNull(wrappedSink);
509
510 if (!StreamOpFlag.SHORT_CIRCUIT.isKnown(getStreamAndOpFlags())) {
511 wrappedSink.begin(spliterator.getExactSizeIfKnown());
512 spliterator.forEachRemaining(wrappedSink);
513 wrappedSink.end();
514 }
515 else {
516 copyIntoWithCancel(wrappedSink, spliterator);
517 }
518 }
519
520 @Override
521 @SuppressWarnings("unchecked")
522 final <P_IN> void copyIntoWithCancel(Sink<P_IN> wrappedSink, Spliterator<P_IN> spliterator) {
523 @SuppressWarnings({"rawtypes","unchecked"})
524 AbstractPipeline p = AbstractPipeline.this;
525 while (p.depth > 0) {
526 p = p.previousStage;
527 }
528 wrappedSink.begin(spliterator.getExactSizeIfKnown());
529 p.forEachWithCancel(spliterator, wrappedSink);
530 wrappedSink.end();
531 }
532
533 @Override
534 final int getStreamAndOpFlags() {
535 return combinedFlags;
536 }
537
538 final boolean isOrdered() {
539 return StreamOpFlag.ORDERED.isKnown(combinedFlags);
540 }
541
542 @Override
543 @SuppressWarnings("unchecked")
544 final <P_IN> Sink<P_IN> wrapSink(Sink<E_OUT> sink) {
545 Objects.requireNonNull(sink);
546
547 for ( @SuppressWarnings("rawtypes") AbstractPipeline p=AbstractPipeline.this; p.depth > 0; p=p.previousStage) {
548 sink = p.opWrapSink(p.previousStage.combinedFlags, sink);
549 }
550 return (Sink<P_IN>) sink;
551 }
552
553 @Override
554 @SuppressWarnings("unchecked")
555 final <P_IN> Spliterator<E_OUT> wrapSpliterator(Spliterator<P_IN> sourceSpliterator) {
556 if (depth == 0) {
557 return (Spliterator<E_OUT>) sourceSpliterator;
558 }
559 else {
560 return wrap(this, () -> sourceSpliterator, isParallel());
561 }
562 }
563
564 @Override
565 @SuppressWarnings("unchecked")
566 final <P_IN> Node<E_OUT> evaluate(Spliterator<P_IN> spliterator,
567 boolean flatten,
568 IntFunction<E_OUT[]> generator) {
569 if (isParallel()) {
570 // @@@ Optimize if op of this pipeline stage is a stateful op
571 return evaluateToNode(this, spliterator, flatten, generator);
572 }
573 else {
574 Node.Builder<E_OUT> nb = makeNodeBuilder(
575 exactOutputSizeIfKnown(spliterator), generator);
576 return wrapAndCopyInto(nb, spliterator).build();
577 }
578 }
579
580
581 // Shape-specific abstract methods, implemented by XxxPipeline classes
582
583 /**
584 * Get the output shape of the pipeline. If the pipeline is the head,
585 * then it's output shape corresponds to the shape of the source.
586 * Otherwise, it's output shape corresponds to the output shape of the
587 * associated operation.
588 *
589 * @return the output shape
590 */
591 abstract StreamShape getOutputShape();
592
593 /**
594 * Collect elements output from a pipeline into a Node that holds elements
595 * of this shape.
596 *
597 * @param helper the pipeline helper describing the pipeline stages
598 * @param spliterator the source spliterator
599 * @param flattenTree true if the returned node should be flattened
600 * @param generator the array generator
601 * @return a Node holding the output of the pipeline
602 */
603 abstract <P_IN> Node<E_OUT> evaluateToNode(PipelineHelper<E_OUT> helper,
604 Spliterator<P_IN> spliterator,
605 boolean flattenTree,
606 IntFunction<E_OUT[]> generator);
607
608 /**
609 * Create a spliterator that wraps a source spliterator, compatible with
610 * this stream shape, and operations associated with a {@link
611 * PipelineHelper}.
612 *
613 * @param ph the pipeline helper describing the pipeline stages
614 * @param supplier the supplier of a spliterator
615 * @return a wrapping spliterator compatible with this shape
616 */
617 abstract <P_IN> Spliterator<E_OUT> wrap(PipelineHelper<E_OUT> ph,
618 Supplier<Spliterator<P_IN>> supplier,
619 boolean isParallel);
620
621 /**
622 * Create a lazy spliterator that wraps and obtains the supplied the
623 * spliterator when a method is invoked on the lazy spliterator.
624 * @param supplier the supplier of a spliterator
625 */
626 abstract Spliterator<E_OUT> lazySpliterator(Supplier<? extends Spliterator<E_OUT>> supplier);
627
628 /**
629 * Traverse the elements of a spliterator compatible with this stream shape,
630 * pushing those elements into a sink. If the sink requests cancellation,
631 * no further elements will be pulled or pushed.
632 *
633 * @param spliterator the spliterator to pull elements from
634 * @param sink the sink to push elements to
635 */
636 abstract void forEachWithCancel(Spliterator<E_OUT> spliterator, Sink<E_OUT> sink);
637
638 /**
639 * Make a node builder compatible with this stream shape.
640 *
641 * @param exactSizeIfKnown if {@literal >=0}, then a node builder will be
642 * created that has a fixed capacity of at most sizeIfKnown elements. If
643 * {@literal < 0}, then the node builder has an unfixed capacity. A fixed
644 * capacity node builder will throw exceptions if an element is added after
645 * builder has reached capacity, or is built before the builder has reached
646 * capacity.
647 *
648 * @param generator the array generator to be used to create instances of a
649 * T[] array. For implementations supporting primitive nodes, this parameter
650 * may be ignored.
651 * @return a node builder
652 */
653 @Override
654 abstract Node.Builder<E_OUT> makeNodeBuilder(long exactSizeIfKnown,
655 IntFunction<E_OUT[]> generator);
656
657
658 // Op-specific abstract methods, implemented by the operation class
659
660 /**
661 * Returns whether this operation is stateful or not. If it is stateful,
662 * then the method
663 * {@link #opEvaluateParallel(PipelineHelper, java.util.Spliterator, java.util.function.IntFunction)}
664 * must be overridden.
665 *
666 * @return {@code true} if this operation is stateful
667 */
668 abstract boolean opIsStateful();
669
670 /**
671 * Accepts a {@code Sink} which will receive the results of this operation,
672 * and return a {@code Sink} which accepts elements of the input type of
673 * this operation and which performs the operation, passing the results to
674 * the provided {@code Sink}.
675 *
676 * @apiNote
677 * The implementation may use the {@code flags} parameter to optimize the
678 * sink wrapping. For example, if the input is already {@code DISTINCT},
679 * the implementation for the {@code Stream#distinct()} method could just
680 * return the sink it was passed.
681 *
682 * @param flags The combined stream and operation flags up to, but not
683 * including, this operation
684 * @param sink sink to which elements should be sent after processing
685 * @return a sink which accepts elements, perform the operation upon
686 * each element, and passes the results (if any) to the provided
687 * {@code Sink}.
688 */
689 abstract Sink<E_IN> opWrapSink(int flags, Sink<E_OUT> sink);
690
691 /**
692 * Performs a parallel evaluation of the operation using the specified
693 * {@code PipelineHelper} which describes the upstream intermediate
694 * operations. Only called on stateful operations. If {@link
695 * #opIsStateful()} returns true then implementations must override the
696 * default implementation.
697 *
698 * @implSpec The default implementation always throw
699 * {@code UnsupportedOperationException}.
700 *
701 * @param helper the pipeline helper describing the pipeline stages
702 * @param spliterator the source {@code Spliterator}
703 * @param generator the array generator
704 * @return a {@code Node} describing the result of the evaluation
705 */
706 <P_IN> Node<E_OUT> opEvaluateParallel(PipelineHelper<E_OUT> helper,
707 Spliterator<P_IN> spliterator,
708 IntFunction<E_OUT[]> generator) {
709 throw new UnsupportedOperationException("Parallel evaluation is not supported");
710 }
711
712 /**
713 * Returns a {@code Spliterator} describing a parallel evaluation of the
714 * operation, using the specified {@code PipelineHelper} which describes the
715 * upstream intermediate operations. Only called on stateful operations.
716 * It is not necessary (though acceptable) to do a full computation of the
717 * result here; it is preferable, if possible, to describe the result via a
718 * lazily evaluated spliterator.
719 *
720 * @implSpec The default implementation behaves as if:
721 * <pre>{@code
722 * return evaluateParallel(helper, i -> (E_OUT[]) new
723 * Object[i]).spliterator();
724 * }</pre>
725 * and is suitable for implementations that cannot do better than a full
726 * synchronous evaluation.
727 *
728 * @param helper the pipeline helper
729 * @param spliterator the source {@code Spliterator}
730 * @return a {@code Spliterator} describing the result of the evaluation
731 */
732 @SuppressWarnings("unchecked")
733 <P_IN> Spliterator<E_OUT> opEvaluateParallelLazy(PipelineHelper<E_OUT> helper,
734 Spliterator<P_IN> spliterator) {
735 return opEvaluateParallel(helper, spliterator, i -> (E_OUT[]) new Object[i]).spliterator();
736 }
737 }