From 054b70c41b58d911829057872eac08f92b6db66f Mon Sep 17 00:00:00 2001 From: Konrad Malawski Date: Wed, 18 Apr 2018 11:44:37 +0200 Subject: [PATCH] Move stream documentation to their own files And generate the index --- .../additional-sink-and-source-converters.md | 21 + .../asynchronous-processing-stages.md | 2 + .../categories/backpressure-aware-stages.md | 1 + .../src/main/categories/fan-in-stages.md | 2 + .../src/main/categories/fan-out-stages.md | 2 + .../categories/file-io-sinks-and-sources.md | 1 + ...ow-stages-composed-of-sinks-and-sources.md | 0 .../nesting-and-flattening-stages.md | 4 + .../categories/simple-processing-stages.md | 5 + akka-docs/src/main/categories/sink-stages.md | 1 + .../src/main/categories/source-stages.md | 1 + .../src/main/categories/time-aware-stages.md | 1 + .../main/categories/timer-driven-stages.md | 1 + .../main/categories/watching-status-stages.md | 0 akka-docs/src/main/paradox/.htaccess | 1 + akka-docs/src/main/paradox/stream/index.md | 2 +- .../stream/operators/FileIO/fromPath.md | 18 + .../paradox/stream/operators/FileIO/toPath.md | 14 + .../operators/Flow/fromSinkAndSource.md | 22 + .../Flow/fromSinkAndSourceCoupled.md | 33 + .../Flow}/lazyInitAsync.md | 12 +- .../{reference => operators/Sink}/actorRef.md | 3 +- .../Sink}/actorRefWithAck.md | 7 +- .../Sink}/asPublisher.md | 10 +- .../stream/operators/Sink/cancelled.md | 26 + .../paradox/stream/operators/Sink/combine.md | 27 + .../paradox/stream/operators/Sink/fold.md | 32 + .../{reference => operators/Sink}/foreach.md | 9 +- .../Sink}/foreachParallel.md | 10 +- .../stream/operators/Sink/fromSubscriber.md | 14 + .../{reference => operators/Sink}/head.md | 13 +- .../Sink}/headOption.md | 14 +- .../{reference => operators/Sink}/ignore.md | 11 +- .../{reference => operators/Sink}/last.md | 14 +- .../Sink}/lastOption.md | 15 +- .../stream/operators/Sink/lazyInitAsync.md | 33 + .../Sink}/onComplete.md | 11 +- .../stream/operators/Sink/preMaterialize.md | 18 + .../{reference => operators/Sink}/queue.md | 12 +- .../paradox/stream/operators/Sink/reduce.md | 29 + .../{reference => operators/Sink}/seq.md | 14 +- .../Source-or-Flow}/alsoTo.md | 3 +- .../Source-or-Flow}/apply.md | 18 +- .../Source-or-Flow}/ask.md | 4 +- .../Source-or-Flow}/backpressureTimeout.md | 7 +- .../Source-or-Flow}/balance.md | 4 +- .../Source-or-Flow}/batch.md | 7 +- .../Source-or-Flow}/batchWeighted.md | 7 +- .../Source-or-Flow}/broadcast.md | 3 +- .../Source-or-Flow}/buffer.md | 7 +- .../Source-or-Flow}/collect.md | 13 +- .../operators/Source-or-Flow/collectType.md | 16 + .../Source-or-Flow}/completionTimeout.md | 13 +- .../Source-or-Flow}/concat.md | 10 +- .../Source-or-Flow}/conflate.md | 13 +- .../Source-or-Flow}/conflateWithSeed.md | 12 +- .../Source-or-Flow}/delay.md | 10 +- .../Source-or-Flow}/detach.md | 10 +- .../Source-or-Flow}/divertTo.md | 10 +- .../Source-or-Flow}/drop.md | 10 +- .../Source-or-Flow}/dropWhile.md | 12 +- .../Source-or-Flow}/dropWithin.md | 12 +- .../Source-or-Flow}/expand.md | 15 +- .../Source-or-Flow}/extrapolate.md | 12 +- .../Source-or-Flow}/filter.md | 10 +- .../Source-or-Flow}/filterNot.md | 10 +- .../Source-or-Flow}/flatMapConcat.md | 13 +- .../Source-or-Flow}/flatMapMerge.md | 12 +- .../Source-or-Flow}/fold.md | 13 +- .../Source-or-Flow}/foldAsync.md | 10 +- .../Source-or-Flow}/groupBy.md | 10 +- .../Source-or-Flow}/grouped.md | 13 +- .../Source-or-Flow}/groupedWeightedWithin.md | 13 +- .../Source-or-Flow}/groupedWithin.md | 13 +- .../Source-or-Flow}/idleTimeout.md | 13 +- .../Source-or-Flow}/initialDelay.md | 10 +- .../Source-or-Flow}/initialTimeout.md | 13 +- .../Source-or-Flow}/interleave.md | 10 +- .../Source-or-Flow}/intersperse.md | 12 +- .../Source-or-Flow}/keepAlive.md | 10 +- .../Source-or-Flow}/limit.md | 10 +- .../Source-or-Flow}/limitWeighted.md | 10 +- .../Source-or-Flow}/log.md | 10 +- .../Source-or-Flow}/map.md | 9 +- .../Source-or-Flow}/mapAsync.md | 10 +- .../Source-or-Flow}/mapAsyncUnordered.md | 13 +- .../Source-or-Flow}/mapConcat.md | 10 +- .../Source-or-Flow}/mapError.md | 13 +- .../Source-or-Flow}/merge.md | 10 +- .../Source-or-Flow}/mergePreferred.md | 4 +- .../Source-or-Flow}/mergePrioritized.md | 4 +- .../Source-or-Flow}/mergeSorted.md | 10 +- .../Source-or-Flow}/monitor.md | 10 +- .../Source-or-Flow}/orElse.md | 13 +- .../Source-or-Flow}/partition.md | 4 +- .../Source-or-Flow}/prefixAndTail.md | 12 +- .../Source-or-Flow}/prepend.md | 10 +- .../Source-or-Flow}/recover.md | 10 +- .../Source-or-Flow}/recoverWith.md | 10 +- .../Source-or-Flow}/recoverWithRetries.md | 10 +- .../Source-or-Flow}/reduce.md | 13 +- .../Source-or-Flow}/scan.md | 13 +- .../Source-or-Flow}/scanAsync.md | 10 +- .../Source-or-Flow}/sliding.md | 10 +- .../Source-or-Flow}/splitAfter.md | 10 +- .../Source-or-Flow}/splitWhen.md | 10 +- .../Source-or-Flow}/statefulMapConcat.md | 10 +- .../Source-or-Flow}/take.md | 12 +- .../Source-or-Flow}/takeWhile.md | 13 +- .../Source-or-Flow}/takeWithin.md | 10 +- .../Source-or-Flow}/throttle.md | 13 +- .../Source-or-Flow}/unzip.md | 4 +- .../Source-or-Flow}/unzipWith.md | 5 +- .../Source-or-Flow}/watch.md | 10 +- .../Source-or-Flow}/watchTermination.md | 10 +- .../Source-or-Flow}/wireTap.md | 13 +- .../Source-or-Flow}/zip.md | 10 +- .../Source-or-Flow}/zipWith.md | 13 +- .../Source-or-Flow}/zipWithIndex.md | 10 +- .../stream/operators/Source/actorRef.md | 26 + .../Source}/asSubscriber.md | 4 +- .../stream/operators/Source/combine.md | 25 + .../{reference => operators/Source}/cycle.md | 10 +- .../{reference => operators/Source}/empty.md | 10 +- .../{reference => operators/Source}/failed.md | 10 +- .../paradox/stream/operators/Source/from.md | 19 + .../Source}/fromCompletionStage.md | 10 +- .../Source}/fromFuture.md | 10 +- .../Source}/fromFutureSource.md | 10 +- .../Source}/fromIterator.md | 11 +- .../stream/operators/Source/fromPublisher.md | 14 + .../Source}/fromSourceCompletionStage.md | 4 +- .../{reference => operators/Source}/lazily.md | 10 +- .../Source}/lazilyAsync.md | 4 +- .../{reference => operators/Source}/maybe.md | 13 +- .../paradox/stream/operators/Source/queue.md | 30 + .../{reference => operators/Source}/range.md | 6 +- .../paradox/stream/operators/Source/repeat.md | 27 + .../paradox/stream/operators/Source/single.md | 27 + .../{reference => operators/Source}/tick.md | 12 +- .../{reference => operators/Source}/unfold.md | 18 +- .../Source}/unfoldAsync.md | 15 +- .../Source}/unfoldResource.md | 12 +- .../Source}/unfoldResourceAsync.md | 12 +- .../{reference => operators/Source}/zipN.md | 12 +- .../Source}/zipWithN.md | 11 +- .../StreamConverters}/asInputStream.md | 6 +- .../StreamConverters}/asJavaStream.md | 6 +- .../StreamConverters}/asOutputStream.md | 6 +- .../StreamConverters/fromInputStream.md | 22 + .../StreamConverters/fromJavaStream.md | 14 + .../StreamConverters/fromOutputStream.md | 14 + .../StreamConverters/javaCollector.md | 22 + .../javaCollectorParallelUnordered.md | 22 + .../main/paradox/stream/operators/index.md | 387 +++ .../reference/Flow.fromSinkAndSource.md | 17 - .../Flow.fromSinkAndSourceCoupled.md | 16 - .../paradox/stream/reference/cancelled.md | 19 - .../paradox/stream/reference/collectType.md | 17 - .../main/paradox/stream/reference/combine.md | 21 - .../stream/reference/fromInputStream.md | 16 - .../stream/reference/fromJavaStream.md | 16 - .../stream/reference/fromOutputStream.md | 16 - .../main/paradox/stream/reference/fromPath.md | 17 - .../paradox/stream/reference/fromPublisher.md | 16 - .../stream/reference/fromSubscriber.md | 16 - .../paradox/stream/reference/javaCollector.md | 17 - .../javaCollectorParallelUnordered.md | 17 - .../stream/reference/preMaterialize.md | 16 - .../main/paradox/stream/reference/repeat.md | 21 - .../main/paradox/stream/reference/single.md | 21 - .../main/paradox/stream/reference/toPath.md | 16 - .../main/paradox/stream/stages-overview.md | 2128 ----------------- .../main/paradox/stream/stream-cookbook.md | 2 +- .../paradox/stream/stream-flows-and-basics.md | 2 +- .../src/main/paradox/stream/stream-graphs.md | 2 +- .../paradox/stream/stream-introduction.md | 4 +- .../main/paradox/stream/stream-quickstart.md | 2 +- .../main/paradox/stream/stream-substream.md | 2 +- .../akka/stream/DocsStageCoverageSpec.scala | 97 - build.sbt | 5 +- project/ParadoxSupport.scala | 2 +- project/StreamOperatorsIndexGenerator.scala | 207 ++ 183 files changed, 2025 insertions(+), 2864 deletions(-) create mode 100644 akka-docs/src/main/categories/additional-sink-and-source-converters.md create mode 100644 akka-docs/src/main/categories/asynchronous-processing-stages.md create mode 100644 akka-docs/src/main/categories/backpressure-aware-stages.md create mode 100644 akka-docs/src/main/categories/fan-in-stages.md create mode 100644 akka-docs/src/main/categories/fan-out-stages.md create mode 100644 akka-docs/src/main/categories/file-io-sinks-and-sources.md create mode 100644 akka-docs/src/main/categories/flow-stages-composed-of-sinks-and-sources.md create mode 100644 akka-docs/src/main/categories/nesting-and-flattening-stages.md create mode 100644 akka-docs/src/main/categories/simple-processing-stages.md create mode 100644 akka-docs/src/main/categories/sink-stages.md create mode 100644 akka-docs/src/main/categories/source-stages.md create mode 100644 akka-docs/src/main/categories/time-aware-stages.md create mode 100644 akka-docs/src/main/categories/timer-driven-stages.md create mode 100644 akka-docs/src/main/categories/watching-status-stages.md create mode 100644 akka-docs/src/main/paradox/stream/operators/FileIO/fromPath.md create mode 100644 akka-docs/src/main/paradox/stream/operators/FileIO/toPath.md create mode 100644 akka-docs/src/main/paradox/stream/operators/Flow/fromSinkAndSource.md create mode 100644 akka-docs/src/main/paradox/stream/operators/Flow/fromSinkAndSourceCoupled.md rename akka-docs/src/main/paradox/stream/{reference => operators/Flow}/lazyInitAsync.md (85%) rename akka-docs/src/main/paradox/stream/{reference => operators/Sink}/actorRef.md (90%) rename akka-docs/src/main/paradox/stream/{reference => operators/Sink}/actorRefWithAck.md (74%) rename akka-docs/src/main/paradox/stream/{reference => operators/Sink}/asPublisher.md (83%) create mode 100644 akka-docs/src/main/paradox/stream/operators/Sink/cancelled.md create mode 100644 akka-docs/src/main/paradox/stream/operators/Sink/combine.md create mode 100644 akka-docs/src/main/paradox/stream/operators/Sink/fold.md rename akka-docs/src/main/paradox/stream/{reference => operators/Sink}/foreach.md (76%) rename akka-docs/src/main/paradox/stream/{reference => operators/Sink}/foreachParallel.md (65%) create mode 100644 akka-docs/src/main/paradox/stream/operators/Sink/fromSubscriber.md rename akka-docs/src/main/paradox/stream/{reference => operators/Sink}/head.md (62%) rename akka-docs/src/main/paradox/stream/{reference => operators/Sink}/headOption.md (60%) rename akka-docs/src/main/paradox/stream/{reference => operators/Sink}/ignore.md (59%) rename akka-docs/src/main/paradox/stream/{reference => operators/Sink}/last.md (60%) rename akka-docs/src/main/paradox/stream/{reference => operators/Sink}/lastOption.md (59%) create mode 100644 akka-docs/src/main/paradox/stream/operators/Sink/lazyInitAsync.md rename akka-docs/src/main/paradox/stream/{reference => operators/Sink}/onComplete.md (52%) create mode 100644 akka-docs/src/main/paradox/stream/operators/Sink/preMaterialize.md rename akka-docs/src/main/paradox/stream/{reference => operators/Sink}/queue.md (68%) create mode 100644 akka-docs/src/main/paradox/stream/operators/Sink/reduce.md rename akka-docs/src/main/paradox/stream/{reference => operators/Sink}/seq.md (64%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/alsoTo.md (90%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/apply.md (60%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/ask.md (94%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/backpressureTimeout.md (84%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/balance.md (91%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/batch.md (84%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/batchWeighted.md (84%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/broadcast.md (90%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/buffer.md (83%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/collect.md (66%) create mode 100644 akka-docs/src/main/paradox/stream/operators/Source-or-Flow/collectType.md rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/completionTimeout.md (65%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/concat.md (71%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/conflate.md (71%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/conflateWithSeed.md (68%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/delay.md (68%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/detach.md (65%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/divertTo.md (75%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/drop.md (67%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/dropWhile.md (54%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/dropWithin.md (52%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/expand.md (50%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/extrapolate.md (69%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/filter.md (70%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/filterNot.md (70%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/flatMapConcat.md (66%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/flatMapMerge.md (65%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/fold.md (58%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/foldAsync.md (73%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/groupBy.md (70%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/grouped.md (63%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/groupedWeightedWithin.md (73%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/groupedWithin.md (73%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/idleTimeout.md (70%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/initialDelay.md (68%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/initialTimeout.md (65%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/interleave.md (74%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/intersperse.md (57%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/keepAlive.md (71%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/limit.md (67%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/limitWeighted.md (73%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/log.md (73%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/map.md (68%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/mapAsync.md (84%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/mapAsyncUnordered.md (77%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/mapConcat.md (74%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/mapError.md (76%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/merge.md (70%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/mergePreferred.md (91%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/mergePrioritized.md (93%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/mergeSorted.md (66%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/monitor.md (74%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/orElse.md (80%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/partition.md (92%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/prefixAndTail.md (62%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/prepend.md (75%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/recover.md (74%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/recoverWith.md (74%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/recoverWithRetries.md (83%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/reduce.md (59%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/scan.md (68%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/scanAsync.md (74%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/sliding.md (73%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/splitAfter.md (77%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/splitWhen.md (75%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/statefulMapConcat.md (77%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/take.md (57%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/takeWhile.md (61%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/takeWithin.md (62%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/throttle.md (60%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/unzip.md (90%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/unzipWith.md (73%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/watch.md (74%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/watchTermination.md (74%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/wireTap.md (67%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/zip.md (73%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/zipWith.md (63%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source-or-Flow}/zipWithIndex.md (63%) create mode 100644 akka-docs/src/main/paradox/stream/operators/Source/actorRef.md rename akka-docs/src/main/paradox/stream/{reference => operators/Source}/asSubscriber.md (86%) create mode 100644 akka-docs/src/main/paradox/stream/operators/Source/combine.md rename akka-docs/src/main/paradox/stream/{reference => operators/Source}/cycle.md (74%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source}/empty.md (62%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source}/failed.md (57%) create mode 100644 akka-docs/src/main/paradox/stream/operators/Source/from.md rename akka-docs/src/main/paradox/stream/{reference => operators/Source}/fromCompletionStage.md (66%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source}/fromFuture.md (65%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source}/fromFutureSource.md (67%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source}/fromIterator.md (77%) create mode 100644 akka-docs/src/main/paradox/stream/operators/Source/fromPublisher.md rename akka-docs/src/main/paradox/stream/{reference => operators/Source}/fromSourceCompletionStage.md (91%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source}/lazily.md (62%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source}/lazilyAsync.md (87%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source}/maybe.md (65%) create mode 100644 akka-docs/src/main/paradox/stream/operators/Source/queue.md rename akka-docs/src/main/paradox/stream/{reference => operators/Source}/range.md (82%) create mode 100644 akka-docs/src/main/paradox/stream/operators/Source/repeat.md create mode 100644 akka-docs/src/main/paradox/stream/operators/Source/single.md rename akka-docs/src/main/paradox/stream/{reference => operators/Source}/tick.md (63%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source}/unfold.md (71%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source}/unfoldAsync.md (71%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source}/unfoldResource.md (68%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source}/unfoldResourceAsync.md (73%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source}/zipN.md (60%) rename akka-docs/src/main/paradox/stream/{reference => operators/Source}/zipWithN.md (63%) rename akka-docs/src/main/paradox/stream/{reference => operators/StreamConverters}/asInputStream.md (86%) rename akka-docs/src/main/paradox/stream/{reference => operators/StreamConverters}/asJavaStream.md (88%) rename akka-docs/src/main/paradox/stream/{reference => operators/StreamConverters}/asOutputStream.md (84%) create mode 100644 akka-docs/src/main/paradox/stream/operators/StreamConverters/fromInputStream.md create mode 100644 akka-docs/src/main/paradox/stream/operators/StreamConverters/fromJavaStream.md create mode 100644 akka-docs/src/main/paradox/stream/operators/StreamConverters/fromOutputStream.md create mode 100644 akka-docs/src/main/paradox/stream/operators/StreamConverters/javaCollector.md create mode 100644 akka-docs/src/main/paradox/stream/operators/StreamConverters/javaCollectorParallelUnordered.md create mode 100644 akka-docs/src/main/paradox/stream/operators/index.md delete mode 100644 akka-docs/src/main/paradox/stream/reference/Flow.fromSinkAndSource.md delete mode 100644 akka-docs/src/main/paradox/stream/reference/Flow.fromSinkAndSourceCoupled.md delete mode 100644 akka-docs/src/main/paradox/stream/reference/cancelled.md delete mode 100644 akka-docs/src/main/paradox/stream/reference/collectType.md delete mode 100644 akka-docs/src/main/paradox/stream/reference/combine.md delete mode 100644 akka-docs/src/main/paradox/stream/reference/fromInputStream.md delete mode 100644 akka-docs/src/main/paradox/stream/reference/fromJavaStream.md delete mode 100644 akka-docs/src/main/paradox/stream/reference/fromOutputStream.md delete mode 100644 akka-docs/src/main/paradox/stream/reference/fromPath.md delete mode 100644 akka-docs/src/main/paradox/stream/reference/fromPublisher.md delete mode 100644 akka-docs/src/main/paradox/stream/reference/fromSubscriber.md delete mode 100644 akka-docs/src/main/paradox/stream/reference/javaCollector.md delete mode 100644 akka-docs/src/main/paradox/stream/reference/javaCollectorParallelUnordered.md delete mode 100644 akka-docs/src/main/paradox/stream/reference/preMaterialize.md delete mode 100644 akka-docs/src/main/paradox/stream/reference/repeat.md delete mode 100644 akka-docs/src/main/paradox/stream/reference/single.md delete mode 100644 akka-docs/src/main/paradox/stream/reference/toPath.md delete mode 100644 akka-docs/src/main/paradox/stream/stages-overview.md delete mode 100644 akka-stream-tests/src/test/scala/akka/stream/DocsStageCoverageSpec.scala create mode 100644 project/StreamOperatorsIndexGenerator.scala diff --git a/akka-docs/src/main/categories/additional-sink-and-source-converters.md b/akka-docs/src/main/categories/additional-sink-and-source-converters.md new file mode 100644 index 0000000000..db9fdc0f6e --- /dev/null +++ b/akka-docs/src/main/categories/additional-sink-and-source-converters.md @@ -0,0 +1,21 @@ +Sources and sinks for integrating with `java.io.InputStream` and `java.io.OutputStream` can be found on +`StreamConverters`. As they are blocking APIs the implementations of these stages are run on a separate +dispatcher configured through the `akka.stream.blocking-io-dispatcher`. + +@@@ warning + +Be aware that `asInputStream` and `asOutputStream` materialize `InputStream` and `OutputStream` respectively as +blocking API implementation. They will block tread until data will be available from upstream. +Because of blocking nature these objects cannot be used in `mapMaterializeValue` section as it causes deadlock +of the stream materialization process. +For example, following snippet will fall with timeout exception: + +```scala +... +.toMat(StreamConverters.asInputStream().mapMaterializedValue { inputStream ⇒ + inputStream.read() // this could block forever + ... +}).run() +``` + +@@@ \ No newline at end of file diff --git a/akka-docs/src/main/categories/asynchronous-processing-stages.md b/akka-docs/src/main/categories/asynchronous-processing-stages.md new file mode 100644 index 0000000000..2fd69d6dbf --- /dev/null +++ b/akka-docs/src/main/categories/asynchronous-processing-stages.md @@ -0,0 +1,2 @@ +These stages encapsulate an asynchronous computation, properly handling backpressure while taking care of the asynchronous +operation at the same time (usually handling the completion of a @scala[`Future`] @java[`CompletionStage`]). \ No newline at end of file diff --git a/akka-docs/src/main/categories/backpressure-aware-stages.md b/akka-docs/src/main/categories/backpressure-aware-stages.md new file mode 100644 index 0000000000..32f899d893 --- /dev/null +++ b/akka-docs/src/main/categories/backpressure-aware-stages.md @@ -0,0 +1 @@ +These stages are aware of the backpressure provided by their downstreams and able to adapt their behavior to that signal. \ No newline at end of file diff --git a/akka-docs/src/main/categories/fan-in-stages.md b/akka-docs/src/main/categories/fan-in-stages.md new file mode 100644 index 0000000000..6516c7082e --- /dev/null +++ b/akka-docs/src/main/categories/fan-in-stages.md @@ -0,0 +1,2 @@ +These stages take multiple streams as their input and provide a single output combining the elements from all of +the inputs in different ways. \ No newline at end of file diff --git a/akka-docs/src/main/categories/fan-out-stages.md b/akka-docs/src/main/categories/fan-out-stages.md new file mode 100644 index 0000000000..3bfc844c78 --- /dev/null +++ b/akka-docs/src/main/categories/fan-out-stages.md @@ -0,0 +1,2 @@ +These have one input and multiple outputs. They might route the elements between different outputs, or emit elements on +multiple outputs at the same time. \ No newline at end of file diff --git a/akka-docs/src/main/categories/file-io-sinks-and-sources.md b/akka-docs/src/main/categories/file-io-sinks-and-sources.md new file mode 100644 index 0000000000..2776d81d74 --- /dev/null +++ b/akka-docs/src/main/categories/file-io-sinks-and-sources.md @@ -0,0 +1 @@ +Sources and sinks for reading and writing files can be found on `FileIO`. \ No newline at end of file diff --git a/akka-docs/src/main/categories/flow-stages-composed-of-sinks-and-sources.md b/akka-docs/src/main/categories/flow-stages-composed-of-sinks-and-sources.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/akka-docs/src/main/categories/nesting-and-flattening-stages.md b/akka-docs/src/main/categories/nesting-and-flattening-stages.md new file mode 100644 index 0000000000..530c879b24 --- /dev/null +++ b/akka-docs/src/main/categories/nesting-and-flattening-stages.md @@ -0,0 +1,4 @@ +These stages either take a stream and turn it into a stream of streams (nesting) or they take a stream that contains +nested streams and turn them into a stream of elements instead (flattening). + +See the [Substreams](stream-substream.md) page for more detail and code samples. \ No newline at end of file diff --git a/akka-docs/src/main/categories/simple-processing-stages.md b/akka-docs/src/main/categories/simple-processing-stages.md new file mode 100644 index 0000000000..caaf4b719a --- /dev/null +++ b/akka-docs/src/main/categories/simple-processing-stages.md @@ -0,0 +1,5 @@ +These stages can transform the rate of incoming elements since there are stages that emit multiple elements for a +single input (e.g. `mapConcat`) or consume multiple elements before emitting one output (e.g. `filter`). +However, these rate transformations are data-driven, i.e. it is the incoming elements that define how the +rate is affected. This is in contrast with [detached stages](#backpressure-aware-stages) which can change their processing behavior +depending on being backpressured by downstream or not. \ No newline at end of file diff --git a/akka-docs/src/main/categories/sink-stages.md b/akka-docs/src/main/categories/sink-stages.md new file mode 100644 index 0000000000..756796870b --- /dev/null +++ b/akka-docs/src/main/categories/sink-stages.md @@ -0,0 +1 @@ +These built-in sinks are available from @scala[`akka.stream.scaladsl.Sink`] @java[`akka.stream.javadsl.Sink`]: diff --git a/akka-docs/src/main/categories/source-stages.md b/akka-docs/src/main/categories/source-stages.md new file mode 100644 index 0000000000..4643818531 --- /dev/null +++ b/akka-docs/src/main/categories/source-stages.md @@ -0,0 +1 @@ +These built-in sources are available from @scala[`akka.stream.scaladsl.Source`] @java[`akka.stream.javadsl.Source`]: \ No newline at end of file diff --git a/akka-docs/src/main/categories/time-aware-stages.md b/akka-docs/src/main/categories/time-aware-stages.md new file mode 100644 index 0000000000..82123cefc2 --- /dev/null +++ b/akka-docs/src/main/categories/time-aware-stages.md @@ -0,0 +1 @@ +Those stages operate taking time into consideration. \ No newline at end of file diff --git a/akka-docs/src/main/categories/timer-driven-stages.md b/akka-docs/src/main/categories/timer-driven-stages.md new file mode 100644 index 0000000000..ef62935229 --- /dev/null +++ b/akka-docs/src/main/categories/timer-driven-stages.md @@ -0,0 +1 @@ +These stages process elements using timers, delaying, dropping or grouping elements for certain time durations. \ No newline at end of file diff --git a/akka-docs/src/main/categories/watching-status-stages.md b/akka-docs/src/main/categories/watching-status-stages.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/akka-docs/src/main/paradox/.htaccess b/akka-docs/src/main/paradox/.htaccess index 33ea2ea499..f615f28b9f 100644 --- a/akka-docs/src/main/paradox/.htaccess +++ b/akka-docs/src/main/paradox/.htaccess @@ -1,2 +1,3 @@ RedirectMatch 301 ^(.*)/scala/(.*) $1/$2?language=scala RedirectMatch 301 ^(.*)/java/(.*) $1/$2?language=java +RedirectMatch 301 ^(.*)/stream/stages-overview\.html.* $1/stream/operators/index.html diff --git a/akka-docs/src/main/paradox/stream/index.md b/akka-docs/src/main/paradox/stream/index.md index 9aa4aca3ef..62210a8bc2 100644 --- a/akka-docs/src/main/paradox/stream/index.md +++ b/akka-docs/src/main/paradox/stream/index.md @@ -19,9 +19,9 @@ * [stream-refs](stream-refs.md) * [stream-parallelism](stream-parallelism.md) * [stream-testkit](stream-testkit.md) -* [stages-overview](stages-overview.md) * [stream-substream](stream-substream.md) * [stream-cookbook](stream-cookbook.md) * [../general/stream/stream-configuration](../general/stream/stream-configuration.md) +* [operators](operators/index.md) @@@ diff --git a/akka-docs/src/main/paradox/stream/operators/FileIO/fromPath.md b/akka-docs/src/main/paradox/stream/operators/FileIO/fromPath.md new file mode 100644 index 0000000000..cbc44c5b3f --- /dev/null +++ b/akka-docs/src/main/paradox/stream/operators/FileIO/fromPath.md @@ -0,0 +1,18 @@ +# FileIO.fromPath + +Emit the contents of a file. + +@ref[File IO Sinks and Sources](../index.md#file-io-sinks-and-sources) + +@@@div { .group-scala } + +## Signature + +@@signature [FileIO.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/FileIO.scala) { #fromPath } + +@@@ + +## Description + +Emit the contents of a file, as `ByteString`s, materializes into a @scala[`Future`] @java[`CompletionStage`] which will be completed with +a `IOResult` upon reaching the end of the file or if there is a failure. diff --git a/akka-docs/src/main/paradox/stream/operators/FileIO/toPath.md b/akka-docs/src/main/paradox/stream/operators/FileIO/toPath.md new file mode 100644 index 0000000000..7347ec179d --- /dev/null +++ b/akka-docs/src/main/paradox/stream/operators/FileIO/toPath.md @@ -0,0 +1,14 @@ +# FileIO.toPath + +Create a sink which will write incoming `ByteString` s to a given file path. + +@ref[File IO Sinks and Sources](../index.md#file-io-sinks-and-sources) + +@@@div { .group-scala } + +## Signature + +@@signature [FileIO.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/FileIO.scala) { #toPath } + +@@@ + diff --git a/akka-docs/src/main/paradox/stream/operators/Flow/fromSinkAndSource.md b/akka-docs/src/main/paradox/stream/operators/Flow/fromSinkAndSource.md new file mode 100644 index 0000000000..73440a5d7e --- /dev/null +++ b/akka-docs/src/main/paradox/stream/operators/Flow/fromSinkAndSource.md @@ -0,0 +1,22 @@ +# Flow.fromSinkAndSource + +Creates a `Flow` from a `Sink` and a `Source` where the Flow's input will be sent to the `Sink` and the `Flow` 's output will come from the Source. + +@ref[Flow stages composed of Sinks and Sources](../index.md#flow-stages-composed-of-sinks-and-sources) + +@@@div { .group-scala } + +## Signature + +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #fromSinkAndSource } + +@@@ + +## Description + +Creates a `Flow` from a `Sink` and a `Source` where the Flow's input will be sent to the `Sink` +and the `Flow` 's output will come from the Source. + +Note that termination events, like completion and cancelation is not automatically propagated through to the "other-side" +of the such-composed Flow. Use `Flow.fromSinkAndSourceCoupled` if you want to couple termination of both of the ends, +for example most useful in handling websocket connections. diff --git a/akka-docs/src/main/paradox/stream/operators/Flow/fromSinkAndSourceCoupled.md b/akka-docs/src/main/paradox/stream/operators/Flow/fromSinkAndSourceCoupled.md new file mode 100644 index 0000000000..371d54d275 --- /dev/null +++ b/akka-docs/src/main/paradox/stream/operators/Flow/fromSinkAndSourceCoupled.md @@ -0,0 +1,33 @@ +# Flow.fromSinkAndSourceCoupled + +Allows coupling termination (cancellation, completion, erroring) of Sinks and Sources while creating a Flow between them. + +@ref[Flow stages composed of Sinks and Sources](../index.md#flow-stages-composed-of-sinks-and-sources) + +@@@div { .group-scala } + +## Signature + +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #fromSinkAndSourceCoupled } + +@@@ + +## Description + +Allows coupling termination (cancellation, completion, erroring) of Sinks and Sources while creating a Flow between them. +Similar to `Flow.fromSinkAndSource` however couples the termination of these two stages. + +E.g. if the emitted `Flow` gets a cancellation, the `Source` of course is cancelled, +however the Sink will also be completed. The table below illustrates the effects in detail: + +| Returned Flow | Sink (in) | Source (out) | +|-------------------------------------------------|-----------------------------|---------------------------------| +| cause: upstream (sink-side) receives completion | effect: receives completion | effect: receives cancel | +| cause: upstream (sink-side) receives error | effect: receives error | effect: receives cancel | +| cause: downstream (source-side) receives cancel | effect: completes | effect: receives cancel | +| effect: cancels upstream, completes downstream | effect: completes | cause: signals complete | +| effect: cancels upstream, errors downstream | effect: receives error | cause: signals error or throws | +| effect: cancels upstream, completes downstream | cause: cancels | effect: receives cancel | + +The order in which the *in* and *out* sides receive their respective completion signals is not defined, do not rely on its ordering. + diff --git a/akka-docs/src/main/paradox/stream/reference/lazyInitAsync.md b/akka-docs/src/main/paradox/stream/operators/Flow/lazyInitAsync.md similarity index 85% rename from akka-docs/src/main/paradox/stream/reference/lazyInitAsync.md rename to akka-docs/src/main/paradox/stream/operators/Flow/lazyInitAsync.md index 6cbb2e1649..de68b2490f 100644 --- a/akka-docs/src/main/paradox/stream/reference/lazyInitAsync.md +++ b/akka-docs/src/main/paradox/stream/operators/Flow/lazyInitAsync.md @@ -1,9 +1,17 @@ -# lazyInitAsync +# Flow.lazyInitAsync Creates a real `Flow` upon receiving the first element by calling relevant `flowFactory` given as an argument. +@ref[Simple processing stages](../index.md#simple-processing-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #lazyInitAsync } + +@@@ + ## Description Creates a real `Flow` upon receiving the first element by calling relevant `flowFactory` given as an argument. @@ -30,5 +38,3 @@ Adheres to the `ActorAttributes.SupervisionStrategy` attribute. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/actorRef.md b/akka-docs/src/main/paradox/stream/operators/Sink/actorRef.md similarity index 90% rename from akka-docs/src/main/paradox/stream/reference/actorRef.md rename to akka-docs/src/main/paradox/stream/operators/Sink/actorRef.md index dbc7d676d7..03c9b5674a 100644 --- a/akka-docs/src/main/paradox/stream/reference/actorRef.md +++ b/akka-docs/src/main/paradox/stream/operators/Sink/actorRef.md @@ -2,6 +2,8 @@ Send the elements from the stream to an `ActorRef`. +@ref[Sink stages](../index.md#sink-stages) + @@@ div { .group-scala } ## Signature @@ -21,5 +23,4 @@ Send the elements from the stream to an `ActorRef`. No backpressure so care must @@@ -## Example diff --git a/akka-docs/src/main/paradox/stream/reference/actorRefWithAck.md b/akka-docs/src/main/paradox/stream/operators/Sink/actorRefWithAck.md similarity index 74% rename from akka-docs/src/main/paradox/stream/reference/actorRefWithAck.md rename to akka-docs/src/main/paradox/stream/operators/Sink/actorRefWithAck.md index 5d6cf56e05..6aef965b1e 100644 --- a/akka-docs/src/main/paradox/stream/reference/actorRefWithAck.md +++ b/akka-docs/src/main/paradox/stream/operators/Sink/actorRefWithAck.md @@ -1,7 +1,8 @@ # actorRefWithAck -Send the elements from the stream to an `ActorRef` which must then acknowledge reception after completing a message, -to provide back pressure onto the sink. +Send the elements from the stream to an `ActorRef` which must then acknowledge reception after completing a message, to provide back pressure onto the sink. + +@ref[Sink stages](../index.md#sink-stages) ## Description @@ -17,5 +18,3 @@ to provide back pressure onto the sink. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/asPublisher.md b/akka-docs/src/main/paradox/stream/operators/Sink/asPublisher.md similarity index 83% rename from akka-docs/src/main/paradox/stream/reference/asPublisher.md rename to akka-docs/src/main/paradox/stream/operators/Sink/asPublisher.md index 04560b3c45..1af0fae018 100644 --- a/akka-docs/src/main/paradox/stream/reference/asPublisher.md +++ b/akka-docs/src/main/paradox/stream/operators/Sink/asPublisher.md @@ -2,19 +2,13 @@ Integration with Reactive Streams, materializes into a `org.reactivestreams.Publisher`. +@ref[Sink stages](../index.md#sink-stages) + @@@ div { .group-scala } ## Signature @@signature [Sink.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Sink.scala) { #asPublisher } -@@@ - -## Description - - - -@@@div { .callout } @@@ -## Example diff --git a/akka-docs/src/main/paradox/stream/operators/Sink/cancelled.md b/akka-docs/src/main/paradox/stream/operators/Sink/cancelled.md new file mode 100644 index 0000000000..32f81634fb --- /dev/null +++ b/akka-docs/src/main/paradox/stream/operators/Sink/cancelled.md @@ -0,0 +1,26 @@ +# cancelled + +Immediately cancel the stream + +@ref[Sink stages](../index.md#sink-stages) + +@@@div { .group-scala } + +## Signature + +@@signature [Sink.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Sink.scala) { #cancelled } + +@@@ + +## Description + +Immediately cancel the stream + + +@@@div { .callout } + +**cancels** immediately + +@@@ + + diff --git a/akka-docs/src/main/paradox/stream/operators/Sink/combine.md b/akka-docs/src/main/paradox/stream/operators/Sink/combine.md new file mode 100644 index 0000000000..f92c78d6ec --- /dev/null +++ b/akka-docs/src/main/paradox/stream/operators/Sink/combine.md @@ -0,0 +1,27 @@ +# combine + +Combine several sinks into one using a user specified strategy + +@ref[Sink stages](../index.md#sink-stages) + +@@@div { .group-scala } + +## Signature + +@@signature [Sink.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Sink.scala) { #combine } + +@@@ + +## Description + +Combine several sinks into one using a user specified strategy + + +@@@div { .callout } + +**cancels** depends on the strategy + +**backpressures** depends on the strategy + +@@@ + diff --git a/akka-docs/src/main/paradox/stream/operators/Sink/fold.md b/akka-docs/src/main/paradox/stream/operators/Sink/fold.md new file mode 100644 index 0000000000..4c0bef77a4 --- /dev/null +++ b/akka-docs/src/main/paradox/stream/operators/Sink/fold.md @@ -0,0 +1,32 @@ +# fold + +Fold over emitted element with a function, where each invocation will get the new element and the result from the previous fold invocation. + +@ref[Sink stages](../index.md#sink-stages) + +@@@div { .group-scala } + +## Signature + +@@signature [Sink.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Sink.scala) { #fold } + +@@@ + +## Description + +Fold over emitted element with a function, where each invocation will get the new element and the result from the +previous fold invocation. The first invocation will be provided the `zero` value. + +Materializes into a @scala[`Future`] @java[`CompletionStage`] that will complete with the last state when the stream has completed. + +This stage allows combining values into a result without a global mutable state by instead passing the state along +between invocations. + +@@@div { .callout } + +**cancels** never + +**backpressures** when the previous fold function invocation has not yet completed + +@@@div + diff --git a/akka-docs/src/main/paradox/stream/reference/foreach.md b/akka-docs/src/main/paradox/stream/operators/Sink/foreach.md similarity index 76% rename from akka-docs/src/main/paradox/stream/reference/foreach.md rename to akka-docs/src/main/paradox/stream/operators/Sink/foreach.md index b3940afc56..b26de8caf0 100644 --- a/akka-docs/src/main/paradox/stream/reference/foreach.md +++ b/akka-docs/src/main/paradox/stream/operators/Sink/foreach.md @@ -2,8 +2,16 @@ Invoke a given procedure for each element received. +@ref[Sink stages](../index.md#sink-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Sink.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Sink.scala) { #forEach } + +@@@ + ## Description Invoke a given procedure for each element received. Note that it is not safe to mutate shared state from the procedure. @@ -22,5 +30,4 @@ Note that it is not safe to mutate state from the procedure. @@@ -## Example diff --git a/akka-docs/src/main/paradox/stream/reference/foreachParallel.md b/akka-docs/src/main/paradox/stream/operators/Sink/foreachParallel.md similarity index 65% rename from akka-docs/src/main/paradox/stream/reference/foreachParallel.md rename to akka-docs/src/main/paradox/stream/operators/Sink/foreachParallel.md index 761ab385ce..8a46a51395 100644 --- a/akka-docs/src/main/paradox/stream/reference/foreachParallel.md +++ b/akka-docs/src/main/paradox/stream/operators/Sink/foreachParallel.md @@ -2,8 +2,16 @@ Like `foreach` but allows up to `parallellism` procedure calls to happen in parallel. +@ref[Sink stages](../index.md#sink-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Sink.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Sink.scala) { #foreachParallel } + +@@@ + ## Description Like `foreach` but allows up to `parallellism` procedure calls to happen in parallel. @@ -17,5 +25,3 @@ Like `foreach` but allows up to `parallellism` procedure calls to happen in para @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/operators/Sink/fromSubscriber.md b/akka-docs/src/main/paradox/stream/operators/Sink/fromSubscriber.md new file mode 100644 index 0000000000..df649a00d8 --- /dev/null +++ b/akka-docs/src/main/paradox/stream/operators/Sink/fromSubscriber.md @@ -0,0 +1,14 @@ +# fromSubscriber + +Integration with Reactive Streams, wraps a `org.reactivestreams.Subscriber` as a sink. + +@ref[Sink stages](../index.md#sink-stages) + +@@@div { .group-scala } + +## Signature + +@@signature [Sink.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Sink.scala) { #fromSubscriber } + +@@@ + diff --git a/akka-docs/src/main/paradox/stream/reference/head.md b/akka-docs/src/main/paradox/stream/operators/Sink/head.md similarity index 62% rename from akka-docs/src/main/paradox/stream/reference/head.md rename to akka-docs/src/main/paradox/stream/operators/Sink/head.md index 54ea990e8e..bd0b98df0e 100644 --- a/akka-docs/src/main/paradox/stream/reference/head.md +++ b/akka-docs/src/main/paradox/stream/operators/Sink/head.md @@ -1,10 +1,17 @@ # head -Materializes into a @scala[`Future`] @java[`CompletionStage`] which completes with the first value arriving, -after this the stream is canceled. +Materializes into a @scala[`Future`] @java[`CompletionStage`] which completes with the first value arriving, after this the stream is canceled. + +@ref[Sink stages](../index.md#sink-stages) + +@@@div { .group-scala } ## Signature +@@signature [Sink.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Sink.scala) { #head } + +@@@ + ## Description Materializes into a @scala[`Future`] @java[`CompletionStage`] which completes with the first value arriving, @@ -19,5 +26,3 @@ after this the stream is canceled. If no element is emitted, the @scala[`Future` @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/headOption.md b/akka-docs/src/main/paradox/stream/operators/Sink/headOption.md similarity index 60% rename from akka-docs/src/main/paradox/stream/reference/headOption.md rename to akka-docs/src/main/paradox/stream/operators/Sink/headOption.md index 6e6a902b06..569819400e 100644 --- a/akka-docs/src/main/paradox/stream/reference/headOption.md +++ b/akka-docs/src/main/paradox/stream/operators/Sink/headOption.md @@ -1,10 +1,17 @@ -# headOption +# Sink.headOption -Materializes into a @scala[`Future[Option[T]]`] @java[`CompletionStage>`] which completes with the first value arriving wrapped in @scala[`Some`] @java[`Optional`], -or @scala[a `None`] @java[an empty Optional] if the stream completes without any elements emitted. +Materializes into a @scala[`Future[Option[T]]`] @java[`CompletionStage>`] which completes with the first value arriving wrapped in @scala[`Some`] @java[`Optional`], or @scala[a `None`] @java[an empty Optional] if the stream completes without any elements emitted. + +@ref[Sink stages](../index.md#sink-stages) + +@@@div { .group-scala } ## Signature +@@signature [Sink.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Sink.scala) { #headOption } + +@@@ + ## Description Materializes into a @scala[`Future[Option[T]]`] @java[`CompletionStage>`] which completes with the first value arriving wrapped in @scala[`Some`] @java[`Optional`], @@ -19,5 +26,4 @@ or @scala[a `None`] @java[an empty Optional] if the stream completes without any @@@ -## Example diff --git a/akka-docs/src/main/paradox/stream/reference/ignore.md b/akka-docs/src/main/paradox/stream/operators/Sink/ignore.md similarity index 59% rename from akka-docs/src/main/paradox/stream/reference/ignore.md rename to akka-docs/src/main/paradox/stream/operators/Sink/ignore.md index d4bf99a89a..487b080341 100644 --- a/akka-docs/src/main/paradox/stream/reference/ignore.md +++ b/akka-docs/src/main/paradox/stream/operators/Sink/ignore.md @@ -1,9 +1,17 @@ -# ignore +# Sink.ignore Consume all elements but discards them. +@ref[Sink stages](../index.md#sink-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Sink.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Sink.scala) { #ignore } + +@@@ + ## Description Consume all elements but discards them. Useful when a stream has to be consumed but there is no use to actually @@ -18,5 +26,4 @@ do anything with the elements. @@@ -## Example diff --git a/akka-docs/src/main/paradox/stream/reference/last.md b/akka-docs/src/main/paradox/stream/operators/Sink/last.md similarity index 60% rename from akka-docs/src/main/paradox/stream/reference/last.md rename to akka-docs/src/main/paradox/stream/operators/Sink/last.md index fe7f83026b..adda59e561 100644 --- a/akka-docs/src/main/paradox/stream/reference/last.md +++ b/akka-docs/src/main/paradox/stream/operators/Sink/last.md @@ -1,10 +1,17 @@ -# last +# Sink.last -Materializes into a @scala[`Future`] @java[`CompletionStage`] which will complete with the last value emitted when the stream -completes. +Materializes into a @scala[`Future`] @java[`CompletionStage`] which will complete with the last value emitted when the stream completes. + +@ref[Sink stages](../index.md#sink-stages) + +@@@div { .group-scala } ## Signature +@@signature [Sink.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Sink.scala) { #last } + +@@@ + ## Description Materializes into a @scala[`Future`] @java[`CompletionStage`] which will complete with the last value emitted when the stream @@ -19,5 +26,4 @@ completes. If the stream completes with no elements the @scala[`Future`] @java[` @@@ -## Example diff --git a/akka-docs/src/main/paradox/stream/reference/lastOption.md b/akka-docs/src/main/paradox/stream/operators/Sink/lastOption.md similarity index 59% rename from akka-docs/src/main/paradox/stream/reference/lastOption.md rename to akka-docs/src/main/paradox/stream/operators/Sink/lastOption.md index b872abc6c4..abd12bdb20 100644 --- a/akka-docs/src/main/paradox/stream/reference/lastOption.md +++ b/akka-docs/src/main/paradox/stream/operators/Sink/lastOption.md @@ -1,10 +1,17 @@ -# lastOption +# Sink.lastOption -Materialize a @scala[`Future[Option[T]]`] @java[`CompletionStage>`] which completes with the last value -emitted wrapped in an @scala[`Some`] @java[`Optional`] when the stream completes. +Materialize a @scala[`Future[Option[T]]`] @java[`CompletionStage>`] which completes with the last value emitted wrapped in an @scala[`Some`] @java[`Optional`] when the stream completes. + +@ref[Sink stages](../index.md#sink-stages) + +@@@div { .group-scala } ## Signature +@@signature [Sink.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Sink.scala) { #lastOption } + +@@@ + ## Description Materialize a @scala[`Future[Option[T]]`] @java[`CompletionStage>`] which completes with the last value @@ -20,5 +27,3 @@ completed with @scala[`None`] @java[an empty `Optional`]. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/operators/Sink/lazyInitAsync.md b/akka-docs/src/main/paradox/stream/operators/Sink/lazyInitAsync.md new file mode 100644 index 0000000000..96f509b88c --- /dev/null +++ b/akka-docs/src/main/paradox/stream/operators/Sink/lazyInitAsync.md @@ -0,0 +1,33 @@ +# Sink.lazyInitAsync + +Creates a real `Sink` upon receiving the first element. + +@ref[Sink stages](../index.md#sink-stages) + +@@@div { .group-scala } + +## Signature + +@@signature [Sink.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Sink.scala) { #lazyInitAsync } + +@@@ + +## Description + +Creates a real `Sink` upon receiving the first element. Internal `Sink` will not be created if there are no elements, +because of completion or error. + +- If upstream completes before an element was received then the @scala[`Future`]@java[`CompletionStage`] is completed with @scala[`None`]@java[an empty `Optional`]. +- If upstream fails before an element was received, `sinkFactory` throws an exception, or materialization of the internal + sink fails then the @scala[`Future`]@java[`CompletionStage`] is completed with the exception. +- Otherwise the @scala[`Future`]@java[`CompletionStage`] is completed with the materialized value of the internal sink. + +@@@div { .callout } + +**cancels** never + +**backpressures** when initialized and when created sink backpressures + +@@@ + + diff --git a/akka-docs/src/main/paradox/stream/reference/onComplete.md b/akka-docs/src/main/paradox/stream/operators/Sink/onComplete.md similarity index 52% rename from akka-docs/src/main/paradox/stream/reference/onComplete.md rename to akka-docs/src/main/paradox/stream/operators/Sink/onComplete.md index 3742d13624..5581ef7042 100644 --- a/akka-docs/src/main/paradox/stream/reference/onComplete.md +++ b/akka-docs/src/main/paradox/stream/operators/Sink/onComplete.md @@ -1,9 +1,17 @@ -# onComplete +# Sink.onComplete Invoke a callback when the stream has completed or failed. +@ref[Sink stages](../index.md#sink-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Sink.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Sink.scala) { #onComplete } + +@@@ + ## Description Invoke a callback when the stream has completed or failed. @@ -17,5 +25,4 @@ Invoke a callback when the stream has completed or failed. @@@ -## Example diff --git a/akka-docs/src/main/paradox/stream/operators/Sink/preMaterialize.md b/akka-docs/src/main/paradox/stream/operators/Sink/preMaterialize.md new file mode 100644 index 0000000000..f43830d3a2 --- /dev/null +++ b/akka-docs/src/main/paradox/stream/operators/Sink/preMaterialize.md @@ -0,0 +1,18 @@ +# Sink.preMaterialize + +Materializes this Sink, immediately returning (1) its materialized value, and (2) a new Sink that can be consume elements 'into' the pre-materialized one. + +@ref[Sink stages](../index.md#sink-stages) + +@@@div { .group-scala } + +## Signature + +@@signature [Sink.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Sink.scala) { #preMaterialize } + +@@@ + +## Description + +Materializes this Sink, immediately returning (1) its materialized value, and (2) a new Sink that can be consume elements 'into' the pre-materialized one. Useful for when you need a materialized value of a Sink when handing it out to someone to materialize it for you. + diff --git a/akka-docs/src/main/paradox/stream/reference/queue.md b/akka-docs/src/main/paradox/stream/operators/Sink/queue.md similarity index 68% rename from akka-docs/src/main/paradox/stream/reference/queue.md rename to akka-docs/src/main/paradox/stream/operators/Sink/queue.md index d105de4355..f474e275b1 100644 --- a/akka-docs/src/main/paradox/stream/reference/queue.md +++ b/akka-docs/src/main/paradox/stream/operators/Sink/queue.md @@ -1,9 +1,17 @@ -# queue +# Sink.queue Materialize a `SinkQueue` that can be pulled to trigger demand through the sink. +@ref[Sink stages](../index.md#sink-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Sink.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Sink.scala) { #queue } + +@@@ + ## Description Materialize a `SinkQueue` that can be pulled to trigger demand through the sink. The queue contains @@ -18,5 +26,3 @@ a buffer in case stream emitting elements faster than queue pulling them. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/operators/Sink/reduce.md b/akka-docs/src/main/paradox/stream/operators/Sink/reduce.md new file mode 100644 index 0000000000..cd0029ce49 --- /dev/null +++ b/akka-docs/src/main/paradox/stream/operators/Sink/reduce.md @@ -0,0 +1,29 @@ +# Sink.reduce + +Apply a reduction function on the incoming elements and pass the result to the next invocation. + +@ref[Sink stages](../index.md#sink-stages) + +@@@div { .group-scala } + +## Signature + +@@signature [Sink.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Sink.scala) { #reduce } + +@@@ + +## Description + +Apply a reduction function on the incoming elements and pass the result to the next invocation. The first invocation +receives the two first elements of the flow. + +Materializes into a @scala[`Future`] @java[`CompletionStage`] that will be completed by the last result of the reduction function. + +@@@div { .callout } + +**cancels** never + +**backpressures** when the previous reduction function invocation has not yet completed + +@@@ + diff --git a/akka-docs/src/main/paradox/stream/reference/seq.md b/akka-docs/src/main/paradox/stream/operators/Sink/seq.md similarity index 64% rename from akka-docs/src/main/paradox/stream/reference/seq.md rename to akka-docs/src/main/paradox/stream/operators/Sink/seq.md index a53dc586a6..4dc51b953a 100644 --- a/akka-docs/src/main/paradox/stream/reference/seq.md +++ b/akka-docs/src/main/paradox/stream/operators/Sink/seq.md @@ -1,10 +1,17 @@ -# seq +# Sink.seq -Collect values emitted from the stream into a collection, the collection is available through a @scala[`Future`] @java[`CompletionStage`] or -which completes when the stream completes. +Collect values emitted from the stream into a collection. + +@ref[Sink stages](../index.md#sink-stages) + +@@@div { .group-scala } ## Signature +@@signature [Sink.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Sink.scala) { #seq } + +@@@ + ## Description Collect values emitted from the stream into a collection, the collection is available through a @scala[`Future`] @java[`CompletionStage`] or @@ -18,5 +25,4 @@ if more element are emitted the sink will cancel the stream @@@ -## Example diff --git a/akka-docs/src/main/paradox/stream/reference/alsoTo.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/alsoTo.md similarity index 90% rename from akka-docs/src/main/paradox/stream/reference/alsoTo.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/alsoTo.md index 5a22f90bcc..3948dc5878 100644 --- a/akka-docs/src/main/paradox/stream/reference/alsoTo.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/alsoTo.md @@ -2,6 +2,8 @@ Attaches the given `Sink` to this `Flow`, meaning that elements that pass through this `Flow` will also be sent to the `Sink`. +@ref[Simple processing stages](../index.md#simple-processing-stages) + @@@ div { .group-scala } ## Signature @@ -25,5 +27,4 @@ Attaches the given `Sink` to this `Flow`, meaning that elements that pass throug @@@ -## Example diff --git a/akka-docs/src/main/paradox/stream/reference/apply.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/apply.md similarity index 60% rename from akka-docs/src/main/paradox/stream/reference/apply.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/apply.md index 8a95a382b4..68373ebf51 100644 --- a/akka-docs/src/main/paradox/stream/reference/apply.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/apply.md @@ -1,6 +1,8 @@ # apply -Stream the values of an `immutable. +Stream the values of an `immutable.Seq`. + +@ref[Source stages](../index.md#source-stages) @@@ div { .group-scala } ## Signature @@ -12,7 +14,6 @@ Stream the values of an `immutable. Stream the values of an `immutable.Seq`. - @@@div { .callout } **emits** the next value of the seq @@ -21,16 +22,3 @@ Stream the values of an `immutable.Seq`. @@@ -@@@ div { .group-java } - -### from - -Stream the values of an `Iterable`. Make sure the `Iterable` is immutable or at least not modified after being used -as a source. - -@@@ - -@@@ - -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/ask.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/ask.md similarity index 94% rename from akka-docs/src/main/paradox/stream/reference/ask.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/ask.md index 50dd328394..d3f2e1d245 100644 --- a/akka-docs/src/main/paradox/stream/reference/ask.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/ask.md @@ -2,6 +2,8 @@ Use the `ask` pattern to send a request-reply message to the target `ref` actor. +@ref[Asynchronous processing stages](../index.md#asynchronous-processing-stages) + @@@ div { .group-scala } ## Signature @@ -33,5 +35,3 @@ Adheres to the [[ActorAttributes.SupervisionStrategy]] attribute. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/backpressureTimeout.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/backpressureTimeout.md similarity index 84% rename from akka-docs/src/main/paradox/stream/reference/backpressureTimeout.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/backpressureTimeout.md index 8588f55bb5..e6693cf3c6 100644 --- a/akka-docs/src/main/paradox/stream/reference/backpressureTimeout.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/backpressureTimeout.md @@ -1,7 +1,8 @@ # backpressureTimeout -If the time between the emission of an element and the following downstream demand exceeds the provided timeout, -the stream is failed with a `TimeoutException`. +If the time between the emission of an element and the following downstream demand exceeds the provided timeout, the stream is failed with a `TimeoutException`. + +@ref[Time aware stages](../index.md#time-aware-stages) @@@ div { .group-scala } ## Signature @@ -29,5 +30,3 @@ check is one period (equals to timeout value). @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/balance.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/balance.md similarity index 91% rename from akka-docs/src/main/paradox/stream/reference/balance.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/balance.md index 04af7b8855..670716a3a8 100644 --- a/akka-docs/src/main/paradox/stream/reference/balance.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/balance.md @@ -2,6 +2,8 @@ Fan-out the stream to several streams. +@ref[Fan-out stages](../index.md#fan-out-stages) + ## Description Fan-out the stream to several streams. Each upstream element is emitted to the first available downstream consumer. @@ -19,5 +21,3 @@ Fan-out the stream to several streams. Each upstream element is emitted to the f @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/batch.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/batch.md similarity index 84% rename from akka-docs/src/main/paradox/stream/reference/batch.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/batch.md index 9bab795b5e..3c829b27ba 100644 --- a/akka-docs/src/main/paradox/stream/reference/batch.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/batch.md @@ -1,7 +1,8 @@ # batch -Allow for a slower downstream by passing incoming elements and a summary into an aggregate function as long as there -is backpressure and a maximum number of batched elements is not yet reached. +Allow for a slower downstream by passing incoming elements and a summary into an aggregate function as long as there is backpressure and a maximum number of batched elements is not yet reached. + +@ref[Backpressure aware stages](../index.md#backpressure-aware-stages) @@@ div { .group-scala } ## Signature @@ -33,5 +34,3 @@ aggregated to the batched value. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/batchWeighted.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/batchWeighted.md similarity index 84% rename from akka-docs/src/main/paradox/stream/reference/batchWeighted.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/batchWeighted.md index 06e735253b..02219123cb 100644 --- a/akka-docs/src/main/paradox/stream/reference/batchWeighted.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/batchWeighted.md @@ -1,7 +1,8 @@ # batchWeighted -Allow for a slower downstream by passing incoming elements and a summary into an aggregate function as long as there -is backpressure and a maximum weight batched elements is not yet reached. +Allow for a slower downstream by passing incoming elements and a summary into an aggregate function as long as there is backpressure and a maximum weight batched elements is not yet reached. + +@ref[Backpressure aware stages](../index.md#backpressure-aware-stages) @@@ div { .group-scala } ## Signature @@ -31,5 +32,3 @@ aggregated to the batched value. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/broadcast.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/broadcast.md similarity index 90% rename from akka-docs/src/main/paradox/stream/reference/broadcast.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/broadcast.md index 8c2dd56727..c7f30846a5 100644 --- a/akka-docs/src/main/paradox/stream/reference/broadcast.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/broadcast.md @@ -2,6 +2,8 @@ Emit each incoming element each of `n` outputs. +@ref[Fan-out stages](../index.md#fan-out-stages) + ## Description Emit each incoming element each of `n` outputs. @@ -19,5 +21,4 @@ Emit each incoming element each of `n` outputs. @@@ -## Example diff --git a/akka-docs/src/main/paradox/stream/reference/buffer.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/buffer.md similarity index 83% rename from akka-docs/src/main/paradox/stream/reference/buffer.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/buffer.md index 5c04939fa8..f12fc7d730 100644 --- a/akka-docs/src/main/paradox/stream/reference/buffer.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/buffer.md @@ -2,6 +2,8 @@ Allow for a temporarily faster upstream events by buffering `size` elements. +@ref[Backpressure aware stages](../index.md#backpressure-aware-stages) + @@@ div { .group-scala } ## Signature @@ -14,7 +16,7 @@ Allow for a temporarily faster upstream events by buffering `size` elements. Allow for a temporarily faster upstream events by buffering `size` elements. When the buffer is full, a new element is handled according to the specified `OverflowStrategy`: - * `backpressure` backpressue is applied upstream + * `backpressure` backpressure is applied upstream * `dropHead` drops the oldest element in the buffer to make space for the new element * `dropTail` drops the youngest element in the buffer to make space for the new element * `dropBuffer` drops the entire buffer and buffers the new element @@ -27,11 +29,10 @@ handled according to the specified `OverflowStrategy`: **emits** when downstream stops backpressuring and there is a pending element in the buffer -**backpressures** when `OverflowStrategy` is `backpressue` and buffer is full +**backpressures** when `OverflowStrategy` is `backpressure` and buffer is full **completes** when upstream completes and buffered elements has been drained, or when `OverflowStrategy` is `fail`, the buffer is full and a new element arrives @@@ -## Example diff --git a/akka-docs/src/main/paradox/stream/reference/collect.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/collect.md similarity index 66% rename from akka-docs/src/main/paradox/stream/reference/collect.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/collect.md index 372556182a..dc5035de60 100644 --- a/akka-docs/src/main/paradox/stream/reference/collect.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/collect.md @@ -1,10 +1,17 @@ # collect -Apply a partial function to each incoming element, if the partial function is defined for a value the returned -value is passed downstream. +Apply a partial function to each incoming element, if the partial function is defined for a value the returned value is passed downstream. + +@ref[Simple processing stages](../index.md#simple-processing-stages) + +@@@div { .group-scala } ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #collect } + +@@@ + ## Description Apply a partial function to each incoming element, if the partial function is defined for a value the returned @@ -21,5 +28,3 @@ value is passed downstream. Can often replace `filter` followed by `map` to achi @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/collectType.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/collectType.md new file mode 100644 index 0000000000..f2b70aa5c5 --- /dev/null +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/collectType.md @@ -0,0 +1,16 @@ +# collectType + +Transform this stream by testing the type of each of the elements on which the element is an instance of the provided type as they pass through this processing step. + +@ref[Simple processing stages](../index.md#simple-processing-stages) + +@@@div { .group-scala } + +## Signature + +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #collectType } + +@@@ + + + diff --git a/akka-docs/src/main/paradox/stream/reference/completionTimeout.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/completionTimeout.md similarity index 65% rename from akka-docs/src/main/paradox/stream/reference/completionTimeout.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/completionTimeout.md index eced4103bc..0af7531305 100644 --- a/akka-docs/src/main/paradox/stream/reference/completionTimeout.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/completionTimeout.md @@ -1,10 +1,17 @@ # completionTimeout -If the completion of the stream does not happen until the provided timeout, the stream is failed -with a `TimeoutException`. +If the completion of the stream does not happen until the provided timeout, the stream is failed with a `TimeoutException`. + +@ref[Time aware stages](../index.md#time-aware-stages) + +@@@div { .group-scala } ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #completionTimeout } + +@@@ + ## Description If the completion of the stream does not happen until the provided timeout, the stream is failed @@ -23,5 +30,3 @@ with a `TimeoutException`. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/concat.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/concat.md similarity index 71% rename from akka-docs/src/main/paradox/stream/reference/concat.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/concat.md index 4028d1f295..6aa1d90c39 100644 --- a/akka-docs/src/main/paradox/stream/reference/concat.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/concat.md @@ -2,8 +2,16 @@ After completion of the original upstream the elements of the given source will be emitted. +@ref[Fan-in stages](../index.md#fan-in-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #concat } + +@@@ + ## Description After completion of the original upstream the elements of the given source will be emitted. @@ -19,5 +27,3 @@ After completion of the original upstream the elements of the given source will @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/conflate.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/conflate.md similarity index 71% rename from akka-docs/src/main/paradox/stream/reference/conflate.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/conflate.md index 8bd56fad2d..d41f3ad619 100644 --- a/akka-docs/src/main/paradox/stream/reference/conflate.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/conflate.md @@ -1,10 +1,17 @@ # conflate -Allow for a slower downstream by passing incoming elements and a summary into an aggregate function as long as -there is backpressure. +Allow for a slower downstream by passing incoming elements and a summary into an aggregate function as long as there is backpressure. + +@ref[Backpressure aware stages](../index.md#backpressure-aware-stages) + +@@@div { .group-scala } ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #conflate } + +@@@ + ## Description Allow for a slower downstream by passing incoming elements and a summary into an aggregate function as long as @@ -22,5 +29,3 @@ average of incoming numbers, if aggregation should lead to a different type `con @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/conflateWithSeed.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/conflateWithSeed.md similarity index 68% rename from akka-docs/src/main/paradox/stream/reference/conflateWithSeed.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/conflateWithSeed.md index 84a852bc04..6aea2f37a7 100644 --- a/akka-docs/src/main/paradox/stream/reference/conflateWithSeed.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/conflateWithSeed.md @@ -1,10 +1,17 @@ # conflateWithSeed -Allow for a slower downstream by passing incoming elements and a summary into an aggregate function as long as there -is backpressure. +Allow for a slower downstream by passing incoming elements and a summary into an aggregate function as long as there is backpressure. + +@ref[Backpressure aware stages](../index.md#backpressure-aware-stages) + +@@@div { .group-scala } ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #conflateWithSeed } + +@@@ + ## Description Allow for a slower downstream by passing incoming elements and a summary into an aggregate function as long as there @@ -22,5 +29,4 @@ transform it to the summary type. @@@ -## Example diff --git a/akka-docs/src/main/paradox/stream/reference/delay.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/delay.md similarity index 68% rename from akka-docs/src/main/paradox/stream/reference/delay.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/delay.md index dd004e905e..bb759cc5da 100644 --- a/akka-docs/src/main/paradox/stream/reference/delay.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/delay.md @@ -2,8 +2,16 @@ Delay every element passed through with a specific duration. +@ref[Timer driven stages](../index.md#timer-driven-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #delay } + +@@@ + ## Description Delay every element passed through with a specific duration. @@ -20,5 +28,3 @@ Delay every element passed through with a specific duration. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/detach.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/detach.md similarity index 65% rename from akka-docs/src/main/paradox/stream/reference/detach.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/detach.md index 80467e2c56..52d5a3c39a 100644 --- a/akka-docs/src/main/paradox/stream/reference/detach.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/detach.md @@ -2,8 +2,16 @@ Detach upstream demand from downstream demand without detaching the stream rates. +@ref[Simple processing stages](../index.md#simple-processing-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #detach } + +@@@ + ## Description Detach upstream demand from downstream demand without detaching the stream rates. @@ -19,5 +27,3 @@ Detach upstream demand from downstream demand without detaching the stream rates @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/divertTo.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/divertTo.md similarity index 75% rename from akka-docs/src/main/paradox/stream/reference/divertTo.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/divertTo.md index 0dca817312..b45dccb5e4 100644 --- a/akka-docs/src/main/paradox/stream/reference/divertTo.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/divertTo.md @@ -2,8 +2,16 @@ Each upstream element will either be diverted to the given sink, or the downstream consumer according to the predicate function applied to the element. +@ref[Simple processing stages](../index.md#simple-processing-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #divertTo } + +@@@ + ## Description Each upstream element will either be diverted to the given sink, or the downstream consumer according to the predicate function applied to the element. @@ -21,5 +29,3 @@ Each upstream element will either be diverted to the given sink, or the downstre @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/drop.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/drop.md similarity index 67% rename from akka-docs/src/main/paradox/stream/reference/drop.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/drop.md index f653ae32d8..1de53e3de7 100644 --- a/akka-docs/src/main/paradox/stream/reference/drop.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/drop.md @@ -2,8 +2,16 @@ Drop `n` elements and then pass any subsequent element downstream. +@ref[Simple processing stages](../index.md#simple-processing-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #drop } + +@@@ + ## Description Drop `n` elements and then pass any subsequent element downstream. @@ -19,5 +27,3 @@ Drop `n` elements and then pass any subsequent element downstream. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/dropWhile.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/dropWhile.md similarity index 54% rename from akka-docs/src/main/paradox/stream/reference/dropWhile.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/dropWhile.md index 559ddbd3b0..4555d66776 100644 --- a/akka-docs/src/main/paradox/stream/reference/dropWhile.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/dropWhile.md @@ -1,9 +1,17 @@ # dropWhile -dropWhile +Drop elements as long as a predicate function return true for the element + +@ref[Simple processing stages](../index.md#simple-processing-stages) + +@@@div { .group-scala } ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #dropWhile } + +@@@ + ## Description Drop elements as long as a predicate function return true for the element @@ -19,5 +27,3 @@ Drop elements as long as a predicate function return true for the element @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/dropWithin.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/dropWithin.md similarity index 52% rename from akka-docs/src/main/paradox/stream/reference/dropWithin.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/dropWithin.md index 1efb305e84..b0b77ce9f0 100644 --- a/akka-docs/src/main/paradox/stream/reference/dropWithin.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/dropWithin.md @@ -1,9 +1,17 @@ # dropWithin -dropWithin +Drop elements until a timeout has fired + +@ref[Timer driven stages](../index.md#timer-driven-stages) + +@@@div { .group-scala } ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #dropWithin } + +@@@ + ## Description Drop elements until a timeout has fired @@ -19,5 +27,3 @@ Drop elements until a timeout has fired @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/expand.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/expand.md similarity index 50% rename from akka-docs/src/main/paradox/stream/reference/expand.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/expand.md index c36fd2131d..6ec62b8c2f 100644 --- a/akka-docs/src/main/paradox/stream/reference/expand.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/expand.md @@ -1,16 +1,23 @@ # expand -Like `extrapolate`, but does not have the `initial` argument, and the `Iterator` is also used in lieu of the original -element, allowing for it to be rewritten and/or filtered. +Like `extrapolate`, but does not have the `initial` argument, and the `Iterator` is also used in lieu of the original element, allowing for it to be rewritten and/or filtered. + +@ref[Backpressure aware stages](../index.md#backpressure-aware-stages) + +@@@div { .group-scala } ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #expand } + +@@@ + ## Description Like `extrapolate`, but does not have the `initial` argument, and the `Iterator` is also used in lieu of the original element, allowing for it to be rewritten and/or filtered. -See @ref:[Understanding extrapolate and expand](../stream-rate.md#understanding-extrapolate-and-expand) for more information +See @ref:[Understanding extrapolate and expand](../../stream-rate.md#understanding-extrapolate-and-expand) for more information and examples. @@ -24,5 +31,3 @@ and examples. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/extrapolate.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/extrapolate.md similarity index 69% rename from akka-docs/src/main/paradox/stream/reference/extrapolate.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/extrapolate.md index 8c9a815ae5..477b517cc5 100644 --- a/akka-docs/src/main/paradox/stream/reference/extrapolate.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/extrapolate.md @@ -2,8 +2,16 @@ Allow for a faster downstream by expanding the last emitted element to an `Iterator`. +@ref[Backpressure aware stages](../index.md#backpressure-aware-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #extrapolate } + +@@@ + ## Description Allow for a faster downstream by expanding the last emitted element to an `Iterator`. For example, an @@ -14,7 +22,7 @@ All original elements are always emitted unchanged - the `Iterator` is only used Includes an optional `initial` argument to prevent blocking the entire stream when there are multiple producers. -See @ref:[Understanding extrapolate and expand](../stream-rate.md#understanding-extrapolate-and-expand) for more information +See @ref:[Understanding extrapolate and expand](../../stream-rate.md#understanding-extrapolate-and-expand) for more information and examples. @@ -28,5 +36,3 @@ and examples. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/filter.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/filter.md similarity index 70% rename from akka-docs/src/main/paradox/stream/reference/filter.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/filter.md index 0f277fd7c7..0840f47290 100644 --- a/akka-docs/src/main/paradox/stream/reference/filter.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/filter.md @@ -2,8 +2,16 @@ Filter the incoming elements using a predicate. +@ref[Simple processing stages](../index.md#simple-processing-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #filter } + +@@@ + ## Description Filter the incoming elements using a predicate. If the predicate returns true the element is passed downstream, if @@ -20,5 +28,3 @@ it returns false the element is discarded. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/filterNot.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/filterNot.md similarity index 70% rename from akka-docs/src/main/paradox/stream/reference/filterNot.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/filterNot.md index 60b43230e7..6cab42e7d5 100644 --- a/akka-docs/src/main/paradox/stream/reference/filterNot.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/filterNot.md @@ -2,8 +2,16 @@ Filter the incoming elements using a predicate. +@ref[Simple processing stages](../index.md#simple-processing-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #filterNot } + +@@@ + ## Description Filter the incoming elements using a predicate. If the predicate returns false the element is passed downstream, if @@ -20,5 +28,3 @@ it returns true the element is discarded. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/flatMapConcat.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/flatMapConcat.md similarity index 66% rename from akka-docs/src/main/paradox/stream/reference/flatMapConcat.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/flatMapConcat.md index 0558f6c761..477a12ea35 100644 --- a/akka-docs/src/main/paradox/stream/reference/flatMapConcat.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/flatMapConcat.md @@ -1,10 +1,17 @@ # flatMapConcat -Transform each input element into a `Source` whose elements are then flattened into the output stream through -concatenation. +Transform each input element into a `Source` whose elements are then flattened into the output stream through concatenation. + +@ref[Nesting and flattening stages](../index.md#nesting-and-flattening-stages) + +@@@div { .group-scala } ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #flatMapConcat } + +@@@ + ## Description Transform each input element into a `Source` whose elements are then flattened into the output stream through @@ -21,5 +28,3 @@ concatenation. This means each source is fully consumed before consumption of th @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/flatMapMerge.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/flatMapMerge.md similarity index 65% rename from akka-docs/src/main/paradox/stream/reference/flatMapMerge.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/flatMapMerge.md index e9a7a9f073..9fecb35c46 100644 --- a/akka-docs/src/main/paradox/stream/reference/flatMapMerge.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/flatMapMerge.md @@ -1,10 +1,17 @@ # flatMapMerge -Transform each input element into a `Source` whose elements are then flattened into the output stream through -merging. +Transform each input element into a `Source` whose elements are then flattened into the output stream through merging. + +@ref[Nesting and flattening stages](../index.md#nesting-and-flattening-stages) + +@@@div { .group-scala } ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #flatMapMerge } + +@@@ + ## Description Transform each input element into a `Source` whose elements are then flattened into the output stream through @@ -21,5 +28,4 @@ merging. The maximum number of merged sources has to be specified. @@@ -## Example diff --git a/akka-docs/src/main/paradox/stream/reference/fold.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/fold.md similarity index 58% rename from akka-docs/src/main/paradox/stream/reference/fold.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/fold.md index 83919e145f..6a71c5f7ad 100644 --- a/akka-docs/src/main/paradox/stream/reference/fold.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/fold.md @@ -1,10 +1,17 @@ # fold -Start with current value `zero` and then apply the current and next value to the given function, when upstream -complete the current value is emitted downstream. +Start with current value `zero` and then apply the current and next value to the given function, when upstream complete the current value is emitted downstream. + +@ref[Simple processing stages](../index.md#simple-processing-stages) + +@@@div { .group-scala } ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #fold } + +@@@ + ## Description Start with current value `zero` and then apply the current and next value to the given function, when upstream @@ -21,5 +28,3 @@ complete the current value is emitted downstream. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/foldAsync.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/foldAsync.md similarity index 73% rename from akka-docs/src/main/paradox/stream/reference/foldAsync.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/foldAsync.md index 01a71677c4..864e85c423 100644 --- a/akka-docs/src/main/paradox/stream/reference/foldAsync.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/foldAsync.md @@ -2,8 +2,16 @@ Just like `fold` but receiving a function that results in a @scala[`Future`] @java[`CompletionStage`] to the next value. +@ref[Simple processing stages](../index.md#simple-processing-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #foldAsync } + +@@@ + ## Description Just like `fold` but receiving a function that results in a @scala[`Future`] @java[`CompletionStage`] to the next value. @@ -19,5 +27,3 @@ Just like `fold` but receiving a function that results in a @scala[`Future`] @ja @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/groupBy.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/groupBy.md similarity index 70% rename from akka-docs/src/main/paradox/stream/reference/groupBy.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/groupBy.md index 138adad59a..73c6197ee9 100644 --- a/akka-docs/src/main/paradox/stream/reference/groupBy.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/groupBy.md @@ -2,8 +2,16 @@ Demultiplex the incoming stream into separate output streams. +@ref[Nesting and flattening stages](../index.md#nesting-and-flattening-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #groupBy } + +@@@ + ## Description Demultiplex the incoming stream into separate output streams. @@ -18,5 +26,3 @@ there is an element pending for a group whose substream backpressures @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/grouped.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/grouped.md similarity index 63% rename from akka-docs/src/main/paradox/stream/reference/grouped.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/grouped.md index ca87173faf..af7fb13ca7 100644 --- a/akka-docs/src/main/paradox/stream/reference/grouped.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/grouped.md @@ -1,10 +1,17 @@ # grouped -Accumulate incoming events until the specified number of elements have been accumulated and then pass the collection of -elements downstream. +Accumulate incoming events until the specified number of elements have been accumulated and then pass the collection of elements downstream. + +@ref[Simple processing stages](../index.md#simple-processing-stages) + +@@@div { .group-scala } ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #grouped } + +@@@ + ## Description Accumulate incoming events until the specified number of elements have been accumulated and then pass the collection of @@ -21,5 +28,3 @@ elements downstream. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/groupedWeightedWithin.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/groupedWeightedWithin.md similarity index 73% rename from akka-docs/src/main/paradox/stream/reference/groupedWeightedWithin.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/groupedWeightedWithin.md index a86cc46455..9db29d601e 100644 --- a/akka-docs/src/main/paradox/stream/reference/groupedWeightedWithin.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/groupedWeightedWithin.md @@ -1,10 +1,17 @@ # groupedWeightedWithin -Chunk up this stream into groups of elements received within a time window, or limited by the weight of the elements, -whatever happens first. +Chunk up this stream into groups of elements received within a time window, or limited by the weight of the elements, whatever happens first. + +@ref[Timer driven stages](../index.md#timer-driven-stages) + +@@@div { .group-scala } ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #groupedWeightedWithin } + +@@@ + ## Description Chunk up this stream into groups of elements received within a time window, or limited by the weight of the elements, @@ -23,5 +30,3 @@ but not if no elements has been grouped (i.e: no empty groups), or when weight l @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/groupedWithin.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/groupedWithin.md similarity index 73% rename from akka-docs/src/main/paradox/stream/reference/groupedWithin.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/groupedWithin.md index 917cab2ca0..bc0e79a172 100644 --- a/akka-docs/src/main/paradox/stream/reference/groupedWithin.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/groupedWithin.md @@ -1,10 +1,17 @@ # groupedWithin -Chunk up this stream into groups of elements received within a time window, or limited by the number of the elements, -whatever happens first. +Chunk up this stream into groups of elements received within a time window, or limited by the number of the elements, whatever happens first. + +@ref[Timer driven stages](../index.md#timer-driven-stages) + +@@@div { .group-scala } ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #groupedWithin } + +@@@ + ## Description Chunk up this stream into groups of elements received within a time window, or limited by the number of the elements, @@ -23,5 +30,3 @@ but not if no elements has been grouped (i.e: no empty groups), or when limit ha @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/idleTimeout.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/idleTimeout.md similarity index 70% rename from akka-docs/src/main/paradox/stream/reference/idleTimeout.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/idleTimeout.md index 3eda0c5f8a..dd1c07634c 100644 --- a/akka-docs/src/main/paradox/stream/reference/idleTimeout.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/idleTimeout.md @@ -1,10 +1,17 @@ # idleTimeout -If the time between two processed elements exceeds the provided timeout, the stream is failed -with a `TimeoutException`. +If the time between two processed elements exceeds the provided timeout, the stream is failed with a `TimeoutException`. + +@ref[Time aware stages](../index.md#time-aware-stages) + +@@@div { .group-scala } ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #idleTimeout } + +@@@ + ## Description If the time between two processed elements exceeds the provided timeout, the stream is failed @@ -24,5 +31,3 @@ check is one period (equals to timeout value). @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/initialDelay.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/initialDelay.md similarity index 68% rename from akka-docs/src/main/paradox/stream/reference/initialDelay.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/initialDelay.md index fe616a93fe..3a61dd33f1 100644 --- a/akka-docs/src/main/paradox/stream/reference/initialDelay.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/initialDelay.md @@ -2,8 +2,16 @@ Delays the initial element by the specified duration. +@ref[Timer driven stages](../index.md#timer-driven-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #initialDelay } + +@@@ + ## Description Delays the initial element by the specified duration. @@ -21,5 +29,3 @@ Delays the initial element by the specified duration. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/initialTimeout.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/initialTimeout.md similarity index 65% rename from akka-docs/src/main/paradox/stream/reference/initialTimeout.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/initialTimeout.md index 2d0fe4f34c..b3cfffd0c9 100644 --- a/akka-docs/src/main/paradox/stream/reference/initialTimeout.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/initialTimeout.md @@ -1,10 +1,17 @@ # initialTimeout -If the first element has not passed through this stage before the provided timeout, the stream is failed -with a `TimeoutException`. +If the first element has not passed through this stage before the provided timeout, the stream is failed with a `TimeoutException`. + +@ref[Time aware stages](../index.md#time-aware-stages) + +@@@div { .group-scala } ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #initialTimeout } + +@@@ + ## Description If the first element has not passed through this stage before the provided timeout, the stream is failed @@ -23,5 +30,3 @@ with a `TimeoutException`. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/interleave.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/interleave.md similarity index 74% rename from akka-docs/src/main/paradox/stream/reference/interleave.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/interleave.md index 05c6df0c29..d536407ead 100644 --- a/akka-docs/src/main/paradox/stream/reference/interleave.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/interleave.md @@ -2,8 +2,16 @@ Emits a specifiable number of elements from the original source, then from the provided source and repeats. +@ref[Fan-in stages](../index.md#fan-in-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #interleave } + +@@@ + ## Description Emits a specifiable number of elements from the original source, then from the provided source and repeats. If one @@ -20,5 +28,3 @@ source completes the rest of the other stream will be emitted. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/intersperse.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/intersperse.md similarity index 57% rename from akka-docs/src/main/paradox/stream/reference/intersperse.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/intersperse.md index a69ad181e6..3bc3cf1de3 100644 --- a/akka-docs/src/main/paradox/stream/reference/intersperse.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/intersperse.md @@ -1,9 +1,17 @@ # intersperse -Intersperse stream with provided element similar to `List. +Intersperse stream with provided element similar to `List.mkString`. + +@ref[Simple processing stages](../index.md#simple-processing-stages) + +@@@div { .group-scala } ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #intersperse } + +@@@ + ## Description Intersperse stream with provided element similar to `List.mkString`. It can inject start and end marker elements to stream. @@ -19,5 +27,3 @@ Intersperse stream with provided element similar to `List.mkString`. It can inje @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/keepAlive.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/keepAlive.md similarity index 71% rename from akka-docs/src/main/paradox/stream/reference/keepAlive.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/keepAlive.md index f67151b6f7..d3172224cb 100644 --- a/akka-docs/src/main/paradox/stream/reference/keepAlive.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/keepAlive.md @@ -2,8 +2,16 @@ Injects additional (configured) elements if upstream does not emit for a configured amount of time. +@ref[Time aware stages](../index.md#time-aware-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #keepAlive } + +@@@ + ## Description Injects additional (configured) elements if upstream does not emit for a configured amount of time. @@ -21,5 +29,3 @@ Injects additional (configured) elements if upstream does not emit for a configu @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/limit.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/limit.md similarity index 67% rename from akka-docs/src/main/paradox/stream/reference/limit.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/limit.md index 2d48e770e4..e8fb11bf5b 100644 --- a/akka-docs/src/main/paradox/stream/reference/limit.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/limit.md @@ -2,8 +2,16 @@ Limit number of element from upstream to given `max` number. +@ref[Simple processing stages](../index.md#simple-processing-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #limit } + +@@@ + ## Description Limit number of element from upstream to given `max` number. @@ -19,5 +27,3 @@ Limit number of element from upstream to given `max` number. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/limitWeighted.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/limitWeighted.md similarity index 73% rename from akka-docs/src/main/paradox/stream/reference/limitWeighted.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/limitWeighted.md index d74327cb47..b8cb2bd6fe 100644 --- a/akka-docs/src/main/paradox/stream/reference/limitWeighted.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/limitWeighted.md @@ -2,8 +2,16 @@ Ensure stream boundedness by evaluating the cost of incoming elements using a cost function. +@ref[Simple processing stages](../index.md#simple-processing-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #limitWeighted } + +@@@ + ## Description Ensure stream boundedness by evaluating the cost of incoming elements using a cost function. @@ -20,5 +28,3 @@ Evaluated cost of each element defines how many elements will be allowed to trav @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/log.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/log.md similarity index 73% rename from akka-docs/src/main/paradox/stream/reference/log.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/log.md index 7c95341258..f92cd12021 100644 --- a/akka-docs/src/main/paradox/stream/reference/log.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/log.md @@ -2,8 +2,16 @@ Log elements flowing through the stream as well as completion and erroring. +@ref[Simple processing stages](../index.md#simple-processing-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #log } + +@@@ + ## Description Log elements flowing through the stream as well as completion and erroring. By default element and @@ -21,5 +29,3 @@ This can be changed by calling @scala[`Attributes.logLevels(...)`] @java[`Attrib @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/map.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/map.md similarity index 68% rename from akka-docs/src/main/paradox/stream/reference/map.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/map.md index 2bd0dbf33d..920cc0b530 100644 --- a/akka-docs/src/main/paradox/stream/reference/map.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/map.md @@ -2,8 +2,16 @@ Transform each element in the stream by calling a mapping function with it and passing the returned value downstream. +@ref[Simple processing stages](../index.md#simple-processing-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #map } + +@@@ + ## Description Transform each element in the stream by calling a mapping function with it and passing the returned value downstream. @@ -19,5 +27,4 @@ Transform each element in the stream by calling a mapping function with it and p @@@ -## Example diff --git a/akka-docs/src/main/paradox/stream/reference/mapAsync.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mapAsync.md similarity index 84% rename from akka-docs/src/main/paradox/stream/reference/mapAsync.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mapAsync.md index a542a3dd12..b652a87ed7 100644 --- a/akka-docs/src/main/paradox/stream/reference/mapAsync.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mapAsync.md @@ -2,8 +2,16 @@ Pass incoming elements to a function that return a @scala[`Future`] @java[`CompletionStage`] result. +@ref[Asynchronous processing stages](../index.md#asynchronous-processing-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #mapAsync } + +@@@ + ## Description Pass incoming elements to a function that return a @scala[`Future`] @java[`CompletionStage`] result. When the @scala[`Future`] @java[`CompletionStage`] arrives the result is passed @@ -23,5 +31,3 @@ If a @scala[`Future`] @java[`CompletionStage`] fails, the stream also fails (unl @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/mapAsyncUnordered.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mapAsyncUnordered.md similarity index 77% rename from akka-docs/src/main/paradox/stream/reference/mapAsyncUnordered.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mapAsyncUnordered.md index 7db9bdad7c..14ba6fe743 100644 --- a/akka-docs/src/main/paradox/stream/reference/mapAsyncUnordered.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mapAsyncUnordered.md @@ -1,10 +1,17 @@ # mapAsyncUnordered -Like `mapAsync` but @scala[`Future`] @java[`CompletionStage`] results are passed downstream as they arrive regardless of the order of the elements -that triggered them. +Like `mapAsync` but @scala[`Future`] @java[`CompletionStage`] results are passed downstream as they arrive regardless of the order of the elements that triggered them. + +@ref[Asynchronous processing stages](../index.md#asynchronous-processing-stages) + +@@@div { .group-scala } ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #mapAsyncUnordered } + +@@@ + ## Description Like `mapAsync` but @scala[`Future`] @java[`CompletionStage`] results are passed downstream as they arrive regardless of the order of the elements @@ -23,5 +30,3 @@ If a @scala[`Future`] @java[`CompletionStage`] fails, the stream also fails (unl @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/mapConcat.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mapConcat.md similarity index 74% rename from akka-docs/src/main/paradox/stream/reference/mapConcat.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mapConcat.md index bf172daf3b..8cd7e11b1f 100644 --- a/akka-docs/src/main/paradox/stream/reference/mapConcat.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mapConcat.md @@ -2,8 +2,16 @@ Transform each element into zero or more elements that are individually passed downstream. +@ref[Simple processing stages](../index.md#simple-processing-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #mapConcat } + +@@@ + ## Description Transform each element into zero or more elements that are individually passed downstream. @@ -19,5 +27,3 @@ Transform each element into zero or more elements that are individually passed d @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/mapError.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mapError.md similarity index 76% rename from akka-docs/src/main/paradox/stream/reference/mapError.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mapError.md index 2db954b6da..d2d2c0cdfd 100644 --- a/akka-docs/src/main/paradox/stream/reference/mapError.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mapError.md @@ -1,10 +1,17 @@ # mapError -While similar to `recover` this stage can be used to transform an error signal to a different one *without* logging -it as an error in the process. +While similar to `recover` this stage can be used to transform an error signal to a different one *without* logging it as an error in the process. + +@ref[Simple processing stages](../index.md#simple-processing-stages) + +@@@div { .group-scala } ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #mapError } + +@@@ + ## Description While similar to `recover` this stage can be used to transform an error signal to a different one *without* logging @@ -25,5 +32,3 @@ Similarily to `recover` throwing an exception inside `mapError` _will_ be logged @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/merge.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/merge.md similarity index 70% rename from akka-docs/src/main/paradox/stream/reference/merge.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/merge.md index 1bf5c5802d..9a50ba9a45 100644 --- a/akka-docs/src/main/paradox/stream/reference/merge.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/merge.md @@ -2,8 +2,16 @@ Merge multiple sources. +@ref[Fan-in stages](../index.md#fan-in-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #merge } + +@@@ + ## Description Merge multiple sources. Picks elements randomly if all sources has elements ready. @@ -19,5 +27,3 @@ Merge multiple sources. Picks elements randomly if all sources has elements read @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/mergePreferred.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mergePreferred.md similarity index 91% rename from akka-docs/src/main/paradox/stream/reference/mergePreferred.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mergePreferred.md index 938a9aa672..441620d813 100644 --- a/akka-docs/src/main/paradox/stream/reference/mergePreferred.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mergePreferred.md @@ -2,6 +2,8 @@ Merge multiple sources. +@ref[Fan-in stages](../index.md#fan-in-stages) + ## Signature ## Description @@ -19,5 +21,3 @@ Merge multiple sources. Prefer one source if all sources has elements ready. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/mergePrioritized.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mergePrioritized.md similarity index 93% rename from akka-docs/src/main/paradox/stream/reference/mergePrioritized.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mergePrioritized.md index 5374f9f67f..ab67e81df6 100644 --- a/akka-docs/src/main/paradox/stream/reference/mergePrioritized.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mergePrioritized.md @@ -2,6 +2,8 @@ Merge multiple sources. +@ref[Fan-in stages](../index.md#fan-in-stages) + ## Signature ## Description @@ -20,5 +22,3 @@ sources has elements ready the relative priorities for those sources are used to @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/mergeSorted.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mergeSorted.md similarity index 66% rename from akka-docs/src/main/paradox/stream/reference/mergeSorted.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mergeSorted.md index d1448bc239..6012e7affd 100644 --- a/akka-docs/src/main/paradox/stream/reference/mergeSorted.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mergeSorted.md @@ -2,8 +2,16 @@ Merge multiple sources. +@ref[Fan-in stages](../index.md#fan-in-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #mergeSorted } + +@@@ + ## Description Merge multiple sources. Waits for one element to be ready from each input stream and emits the @@ -20,5 +28,3 @@ smallest element. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/monitor.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/monitor.md similarity index 74% rename from akka-docs/src/main/paradox/stream/reference/monitor.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/monitor.md index 3ab9efe14e..e8bd3d0e2f 100644 --- a/akka-docs/src/main/paradox/stream/reference/monitor.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/monitor.md @@ -2,8 +2,16 @@ Materializes to a `FlowMonitor` that monitors messages flowing through or completion of the stage. +@ref[Watching status stages](../index.md#watching-status-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #monitor } + +@@@ + ## Description Materializes to a `FlowMonitor` that monitors messages flowing through or completion of the stage. The stage otherwise @@ -21,5 +29,3 @@ event, and may therefore affect performance. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/orElse.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/orElse.md similarity index 80% rename from akka-docs/src/main/paradox/stream/reference/orElse.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/orElse.md index f986adeae7..c899da3825 100644 --- a/akka-docs/src/main/paradox/stream/reference/orElse.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/orElse.md @@ -1,10 +1,17 @@ # orElse -If the primary source completes without emitting any elements, the elements from the secondary source -are emitted. +If the primary source completes without emitting any elements, the elements from the secondary source are emitted. + +@ref[Fan-in stages](../index.md#fan-in-stages) + +@@@div { .group-scala } ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #orElse } + +@@@ + ## Description If the primary source completes without emitting any elements, the elements from the secondary source @@ -28,5 +35,3 @@ without emitting and the secondary stream already has completed or when the seco @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/partition.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/partition.md similarity index 92% rename from akka-docs/src/main/paradox/stream/reference/partition.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/partition.md index 82a8ffcdda..b6933875ba 100644 --- a/akka-docs/src/main/paradox/stream/reference/partition.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/partition.md @@ -2,6 +2,8 @@ Fan-out the stream to several streams. +@ref[Fan-out stages](../index.md#fan-out-stages) + ## Signature ## Description @@ -22,5 +24,3 @@ partitioner function applied to the element. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/prefixAndTail.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/prefixAndTail.md similarity index 62% rename from akka-docs/src/main/paradox/stream/reference/prefixAndTail.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/prefixAndTail.md index 544a641dec..bb8801636a 100644 --- a/akka-docs/src/main/paradox/stream/reference/prefixAndTail.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/prefixAndTail.md @@ -1,10 +1,17 @@ # prefixAndTail -Take up to *n* elements from the stream (less than *n* only if the upstream completes before emitting *n* elements) -and returns a pair containing a strict sequence of the taken element and a stream representing the remaining elements. +Take up to *n* elements from the stream (less than *n* only if the upstream completes before emitting *n* elements) and returns a pair containing a strict sequence of the taken element and a stream representing the remaining elements. + +@ref[Nesting and flattening stages](../index.md#nesting-and-flattening-stages) + +@@@div { .group-scala } ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #prefixAndTail } + +@@@ + ## Description Take up to *n* elements from the stream (less than *n* only if the upstream completes before emitting *n* elements) @@ -21,5 +28,4 @@ and returns a pair containing a strict sequence of the taken element and a strea @@@ -## Example diff --git a/akka-docs/src/main/paradox/stream/reference/prepend.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/prepend.md similarity index 75% rename from akka-docs/src/main/paradox/stream/reference/prepend.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/prepend.md index 2fde0f208b..7422d3ce03 100644 --- a/akka-docs/src/main/paradox/stream/reference/prepend.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/prepend.md @@ -2,8 +2,16 @@ Prepends the given source to the flow, consuming it until completion before the original source is consumed. +@ref[Fan-in stages](../index.md#fan-in-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #prepend } + +@@@ + ## Description Prepends the given source to the flow, consuming it until completion before the original source is consumed. @@ -21,5 +29,3 @@ If materialized values needs to be collected `prependMat` is available. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/recover.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/recover.md similarity index 74% rename from akka-docs/src/main/paradox/stream/reference/recover.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/recover.md index 17218ad26f..5259d5c0c2 100644 --- a/akka-docs/src/main/paradox/stream/reference/recover.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/recover.md @@ -2,8 +2,16 @@ Allow sending of one last element downstream when a failure has happened upstream. +@ref[Simple processing stages](../index.md#simple-processing-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #recover } + +@@@ + ## Description Allow sending of one last element downstream when a failure has happened upstream. @@ -21,5 +29,3 @@ Throwing an exception inside `recover` _will_ be logged on ERROR level automatic @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/recoverWith.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/recoverWith.md similarity index 74% rename from akka-docs/src/main/paradox/stream/reference/recoverWith.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/recoverWith.md index 80ab9a67c4..8ccb92cab2 100644 --- a/akka-docs/src/main/paradox/stream/reference/recoverWith.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/recoverWith.md @@ -2,8 +2,16 @@ Allow switching to alternative Source when a failure has happened upstream. +@ref[Simple processing stages](../index.md#simple-processing-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #recoverWith } + +@@@ + ## Description Allow switching to alternative Source when a failure has happened upstream. @@ -21,5 +29,3 @@ Throwing an exception inside `recoverWith` _will_ be logged on ERROR level autom @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/recoverWithRetries.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/recoverWithRetries.md similarity index 83% rename from akka-docs/src/main/paradox/stream/reference/recoverWithRetries.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/recoverWithRetries.md index 3149bed382..69469b372b 100644 --- a/akka-docs/src/main/paradox/stream/reference/recoverWithRetries.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/recoverWithRetries.md @@ -2,8 +2,16 @@ RecoverWithRetries allows to switch to alternative Source on flow failure. +@ref[Simple processing stages](../index.md#simple-processing-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #recoverWithRetries } + +@@@ + ## Description RecoverWithRetries allows to switch to alternative Source on flow failure. It will stay in effect after @@ -25,5 +33,3 @@ This stage can recover the failure signal, but not the skipped elements, which w @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/reduce.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/reduce.md similarity index 59% rename from akka-docs/src/main/paradox/stream/reference/reduce.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/reduce.md index 1ba9f88975..d29cae44d6 100644 --- a/akka-docs/src/main/paradox/stream/reference/reduce.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/reduce.md @@ -1,10 +1,17 @@ # reduce -Start with first element and then apply the current and next value to the given function, when upstream -complete the current value is emitted downstream. +Start with first element and then apply the current and next value to the given function, when upstream complete the current value is emitted downstream. + +@ref[Simple processing stages](../index.md#simple-processing-stages) + +@@@div { .group-scala } ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #reduce } + +@@@ + ## Description Start with first element and then apply the current and next value to the given function, when upstream @@ -21,5 +28,3 @@ complete the current value is emitted downstream. Similar to `fold`. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/scan.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/scan.md similarity index 68% rename from akka-docs/src/main/paradox/stream/reference/scan.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/scan.md index ed12432038..676b375a15 100644 --- a/akka-docs/src/main/paradox/stream/reference/scan.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/scan.md @@ -1,10 +1,17 @@ # scan -Emit its current value which starts at `zero` and then applies the current and next value to the given function -emitting the next current value. +Emit its current value which starts at `zero` and then applies the current and next value to the given function emitting the next current value. + +@ref[Simple processing stages](../index.md#simple-processing-stages) + +@@@div { .group-scala } ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #scan } + +@@@ + ## Description Emit its current value which starts at `zero` and then applies the current and next value to the given function @@ -24,5 +31,3 @@ the second element is required from downstream. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/scanAsync.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/scanAsync.md similarity index 74% rename from akka-docs/src/main/paradox/stream/reference/scanAsync.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/scanAsync.md index bfe31cbc0d..96959e8e90 100644 --- a/akka-docs/src/main/paradox/stream/reference/scanAsync.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/scanAsync.md @@ -2,8 +2,16 @@ Just like `scan` but receiving a function that results in a @scala[`Future`] @java[`CompletionStage`] to the next value. +@ref[Simple processing stages](../index.md#simple-processing-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #scanAsync } + +@@@ + ## Description Just like `scan` but receiving a function that results in a @scala[`Future`] @java[`CompletionStage`] to the next value. @@ -19,5 +27,3 @@ Just like `scan` but receiving a function that results in a @scala[`Future`] @ja @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/sliding.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/sliding.md similarity index 73% rename from akka-docs/src/main/paradox/stream/reference/sliding.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/sliding.md index 2458bed5e8..3605160d2b 100644 --- a/akka-docs/src/main/paradox/stream/reference/sliding.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/sliding.md @@ -2,8 +2,16 @@ Provide a sliding window over the incoming stream and pass the windows as groups of elements downstream. +@ref[Simple processing stages](../index.md#simple-processing-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #sliding } + +@@@ + ## Description Provide a sliding window over the incoming stream and pass the windows as groups of elements downstream. @@ -21,5 +29,3 @@ Note: the last window might be smaller than the requested size due to end of str @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/splitAfter.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/splitAfter.md similarity index 77% rename from akka-docs/src/main/paradox/stream/reference/splitAfter.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/splitAfter.md index f80ce69e86..848a4716d9 100644 --- a/akka-docs/src/main/paradox/stream/reference/splitAfter.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/splitAfter.md @@ -2,8 +2,16 @@ End the current substream whenever a predicate returns `true`, starting a new substream for the next element. +@ref[Nesting and flattening stages](../index.md#nesting-and-flattening-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #splitAfter } + +@@@ + ## Description End the current substream whenever a predicate returns `true`, starting a new substream for the next element. @@ -19,5 +27,3 @@ End the current substream whenever a predicate returns `true`, starting a new su @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/splitWhen.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/splitWhen.md similarity index 75% rename from akka-docs/src/main/paradox/stream/reference/splitWhen.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/splitWhen.md index ab9d3f8150..aada04b346 100644 --- a/akka-docs/src/main/paradox/stream/reference/splitWhen.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/splitWhen.md @@ -2,8 +2,16 @@ Split off elements into a new substream whenever a predicate function return `true`. +@ref[Nesting and flattening stages](../index.md#nesting-and-flattening-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #splitWhen } + +@@@ + ## Description Split off elements into a new substream whenever a predicate function return `true`. @@ -19,5 +27,3 @@ Split off elements into a new substream whenever a predicate function return `tr @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/statefulMapConcat.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/statefulMapConcat.md similarity index 77% rename from akka-docs/src/main/paradox/stream/reference/statefulMapConcat.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/statefulMapConcat.md index 40a0a34758..4a5e4ae3fd 100644 --- a/akka-docs/src/main/paradox/stream/reference/statefulMapConcat.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/statefulMapConcat.md @@ -2,8 +2,16 @@ Transform each element into zero or more elements that are individually passed downstream. +@ref[Simple processing stages](../index.md#simple-processing-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #statefulMapConcat } + +@@@ + ## Description Transform each element into zero or more elements that are individually passed downstream. The difference to `mapConcat` is that @@ -20,5 +28,3 @@ the transformation function is created from a factory for every materialization @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/take.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/take.md similarity index 57% rename from akka-docs/src/main/paradox/stream/reference/take.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/take.md index 9a3420c0b0..c1846a351b 100644 --- a/akka-docs/src/main/paradox/stream/reference/take.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/take.md @@ -1,9 +1,17 @@ # take -take +Pass `n` incoming elements downstream and then complete + +@ref[Simple processing stages](../index.md#simple-processing-stages) + +@@@div { .group-scala } ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #take } + +@@@ + ## Description Pass `n` incoming elements downstream and then complete @@ -19,5 +27,3 @@ Pass `n` incoming elements downstream and then complete @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/takeWhile.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/takeWhile.md similarity index 61% rename from akka-docs/src/main/paradox/stream/reference/takeWhile.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/takeWhile.md index 216093ad78..bc3ceeb90e 100644 --- a/akka-docs/src/main/paradox/stream/reference/takeWhile.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/takeWhile.md @@ -1,10 +1,17 @@ # takeWhile -Pass elements downstream as long as a predicate function return true for the element include the element -when the predicate first return false and then complete. +Pass elements downstream as long as a predicate function return true for the element include the element when the predicate first return false and then complete. + +@ref[Simple processing stages](../index.md#simple-processing-stages) + +@@@div { .group-scala } ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #takeWhile } + +@@@ + ## Description Pass elements downstream as long as a predicate function return true for the element include the element @@ -21,5 +28,3 @@ when the predicate first return false and then complete. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/takeWithin.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/takeWithin.md similarity index 62% rename from akka-docs/src/main/paradox/stream/reference/takeWithin.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/takeWithin.md index da22f4d2e1..fca965e045 100644 --- a/akka-docs/src/main/paradox/stream/reference/takeWithin.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/takeWithin.md @@ -2,8 +2,16 @@ Pass elements downstream within a timeout and then complete. +@ref[Timer driven stages](../index.md#timer-driven-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #takeWithin } + +@@@ + ## Description Pass elements downstream within a timeout and then complete. @@ -19,5 +27,3 @@ Pass elements downstream within a timeout and then complete. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/throttle.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/throttle.md similarity index 60% rename from akka-docs/src/main/paradox/stream/reference/throttle.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/throttle.md index 093fdbbd87..6c0306f22d 100644 --- a/akka-docs/src/main/paradox/stream/reference/throttle.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/throttle.md @@ -1,10 +1,17 @@ # throttle -Limit the throughput to a specific number of elements per time unit, or a specific total cost per time unit, where -a function has to be provided to calculate the individual cost of each element. +Limit the throughput to a specific number of elements per time unit, or a specific total cost per time unit, where a function has to be provided to calculate the individual cost of each element. + +@ref[Simple processing stages](../index.md#simple-processing-stages) + +@@@div { .group-scala } ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #throttle } + +@@@ + ## Description Limit the throughput to a specific number of elements per time unit, or a specific total cost per time unit, where @@ -21,5 +28,3 @@ a function has to be provided to calculate the individual cost of each element. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/unzip.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/unzip.md similarity index 90% rename from akka-docs/src/main/paradox/stream/reference/unzip.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/unzip.md index bd081dabe1..3f0a3fd34b 100644 --- a/akka-docs/src/main/paradox/stream/reference/unzip.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/unzip.md @@ -2,6 +2,8 @@ Takes a stream of two element tuples and unzips the two elements ino two different downstreams. +@ref[Fan-out stages](../index.md#fan-out-stages) + ## Signature ## Description @@ -19,5 +21,3 @@ Takes a stream of two element tuples and unzips the two elements ino two differe @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/unzipWith.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/unzipWith.md similarity index 73% rename from akka-docs/src/main/paradox/stream/reference/unzipWith.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/unzipWith.md index b25c7ee43c..4f575d1637 100644 --- a/akka-docs/src/main/paradox/stream/reference/unzipWith.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/unzipWith.md @@ -1,6 +1,8 @@ # unzipWith -unzipWith +Splits each element of input into multiple downstreams using a function + +@ref[Fan-out stages](../index.md#fan-out-stages) ## Signature @@ -19,5 +21,4 @@ Splits each element of input into multiple downstreams using a function @@@ -## Example diff --git a/akka-docs/src/main/paradox/stream/reference/watch.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/watch.md similarity index 74% rename from akka-docs/src/main/paradox/stream/reference/watch.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/watch.md index f33ed90340..382c91d30e 100644 --- a/akka-docs/src/main/paradox/stream/reference/watch.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/watch.md @@ -2,8 +2,16 @@ Watch a specific `ActorRef` and signal a failure downstream once the actor terminates. +@ref[Simple processing stages](../index.md#simple-processing-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #watch } + +@@@ + ## Description Watch a specific `ActorRef` and signal a failure downstream once the actor terminates. @@ -21,5 +29,3 @@ The signaled failure will be an @java[@javadoc:[WatchedActorTerminatedException] @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/watchTermination.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/watchTermination.md similarity index 74% rename from akka-docs/src/main/paradox/stream/reference/watchTermination.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/watchTermination.md index 774a679a61..c7cc6ee68e 100644 --- a/akka-docs/src/main/paradox/stream/reference/watchTermination.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/watchTermination.md @@ -2,8 +2,16 @@ Materializes to a @scala[`Future`] @java[`CompletionStage`] that will be completed with Done or failed depending whether the upstream of the stage has been completed or failed. +@ref[Watching status stages](../index.md#watching-status-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #watchTermination } + +@@@ + ## Description Materializes to a @scala[`Future`] @java[`CompletionStage`] that will be completed with Done or failed depending whether the upstream of the stage has been completed or failed. @@ -20,5 +28,3 @@ The stage otherwise passes through elements unchanged. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/wireTap.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/wireTap.md similarity index 67% rename from akka-docs/src/main/paradox/stream/reference/wireTap.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/wireTap.md index 6c7bd13dec..6106e6094b 100644 --- a/akka-docs/src/main/paradox/stream/reference/wireTap.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/wireTap.md @@ -1,10 +1,17 @@ # wireTap -Attaches the given `Sink` to this `Flow` as a wire tap, meaning that elements that pass -through will also be sent to the wire-tap `Sink`, without the latter affecting the mainline flow. +Attaches the given `Sink` to this `Flow` as a wire tap, meaning that elements that pass through will also be sent to the wire-tap `Sink`, without the latter affecting the mainline flow. + +@ref[Simple processing stages](../index.md#simple-processing-stages) + +@@@div { .group-scala } ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #wireTap } + +@@@ + ## Description Attaches the given `Sink` to this `Flow` as a wire tap, meaning that elements that pass @@ -25,5 +32,3 @@ also be sent to the wire-tap `Sink` if there is demand. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/zip.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/zip.md similarity index 73% rename from akka-docs/src/main/paradox/stream/reference/zip.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/zip.md index 0e7bc4ef62..635c0a7ccd 100644 --- a/akka-docs/src/main/paradox/stream/reference/zip.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/zip.md @@ -2,8 +2,16 @@ Combines elements from each of multiple sources into @scala[tuples] @java[*Pair*] and passes the @scala[tuples] @java[pairs] downstream. +@ref[Fan-in stages](../index.md#fan-in-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #zip } + +@@@ + ## Description Combines elements from each of multiple sources into @scala[tuples] @java[*Pair*] and passes the @scala[tuples] @java[pairs] downstream. @@ -19,5 +27,3 @@ Combines elements from each of multiple sources into @scala[tuples] @java[*Pair* @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/zipWith.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/zipWith.md similarity index 63% rename from akka-docs/src/main/paradox/stream/reference/zipWith.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/zipWith.md index fc1fe01595..dbff19d025 100644 --- a/akka-docs/src/main/paradox/stream/reference/zipWith.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/zipWith.md @@ -1,10 +1,17 @@ # zipWith -Combines elements from multiple sources through a `combine` function and passes the -returned value downstream. +Combines elements from multiple sources through a `combine` function and passes the returned value downstream. + +@ref[Fan-in stages](../index.md#fan-in-stages) + +@@@div { .group-scala } ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #zipWith } + +@@@ + ## Description Combines elements from multiple sources through a `combine` function and passes the @@ -21,5 +28,3 @@ returned value downstream. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/zipWithIndex.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/zipWithIndex.md similarity index 63% rename from akka-docs/src/main/paradox/stream/reference/zipWithIndex.md rename to akka-docs/src/main/paradox/stream/operators/Source-or-Flow/zipWithIndex.md index e94cd99a6d..3d082221bf 100644 --- a/akka-docs/src/main/paradox/stream/reference/zipWithIndex.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/zipWithIndex.md @@ -2,8 +2,16 @@ Zips elements of current flow with its indices. +@ref[Fan-in stages](../index.md#fan-in-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Flow.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala) { #zipWithIndex } + +@@@ + ## Description Zips elements of current flow with its indices. @@ -19,5 +27,3 @@ Zips elements of current flow with its indices. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/operators/Source/actorRef.md b/akka-docs/src/main/paradox/stream/operators/Source/actorRef.md new file mode 100644 index 0000000000..6a71a3272b --- /dev/null +++ b/akka-docs/src/main/paradox/stream/operators/Source/actorRef.md @@ -0,0 +1,26 @@ +# actorRef + +Materialize an `ActorRef`, sending messages to it will emit them on the stream. + +@ref[Source stages](../index.md#source-stages) + +@@@ div { .group-scala } +## Signature + +@@signature [Source.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Source.scala) { #actorRef } +@@@ + +## Description + +Materialize an `ActorRef`, sending messages to it will emit them on the stream. The actor contain +a buffer but since communication is one way, there is no back pressure. Handling overflow is done by either dropping +elements or failing the stream, the strategy is chosen by the user. + +@@@div { .callout } + +**emits** when there is demand and there are messages in the buffer or a message is sent to the actorref + +**completes** when the `ActorRef` is sent `akka.actor.Status.Success` or `PoisonPill` + +@@@ + diff --git a/akka-docs/src/main/paradox/stream/reference/asSubscriber.md b/akka-docs/src/main/paradox/stream/operators/Source/asSubscriber.md similarity index 86% rename from akka-docs/src/main/paradox/stream/reference/asSubscriber.md rename to akka-docs/src/main/paradox/stream/operators/Source/asSubscriber.md index bb79d1c83c..624e948dcf 100644 --- a/akka-docs/src/main/paradox/stream/reference/asSubscriber.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/asSubscriber.md @@ -2,6 +2,8 @@ Integration with Reactive Streams, materializes into a `org.reactivestreams.Subscriber`. +@ref[Source stages](../index.md#source-stages) + @@@ div { .group-scala } ## Signature @@ -16,5 +18,3 @@ Integration with Reactive Streams, materializes into a `org.reactivestreams.Subs @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/operators/Source/combine.md b/akka-docs/src/main/paradox/stream/operators/Source/combine.md new file mode 100644 index 0000000000..c664b81631 --- /dev/null +++ b/akka-docs/src/main/paradox/stream/operators/Source/combine.md @@ -0,0 +1,25 @@ +# combine + +Combine several sources, using a given strategy such as merge or concat, into one source. + +@ref[Source stages](../index.md#source-stages) + +@@@div { .group-scala } + +## Signature + +@@signature [Source.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Source.scala) { #combine } + +@@@ + +## Description + +@@@div { .callout } + +**emits** when there is demand, but depending on the strategy + +**completes** when all sources has completed + +@@@ + + diff --git a/akka-docs/src/main/paradox/stream/reference/cycle.md b/akka-docs/src/main/paradox/stream/operators/Source/cycle.md similarity index 74% rename from akka-docs/src/main/paradox/stream/reference/cycle.md rename to akka-docs/src/main/paradox/stream/operators/Source/cycle.md index 8103a2eaa5..a3b4d51650 100644 --- a/akka-docs/src/main/paradox/stream/reference/cycle.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/cycle.md @@ -2,8 +2,16 @@ Stream iterator in cycled manner. +@ref[Source stages](../index.md#source-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Source.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Source.scala) { #cycle } + +@@@ + ## Description Stream iterator in cycled manner. Internally new iterator is being created to cycle the one provided via argument meaning @@ -20,5 +28,3 @@ exception. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/empty.md b/akka-docs/src/main/paradox/stream/operators/Source/empty.md similarity index 62% rename from akka-docs/src/main/paradox/stream/reference/empty.md rename to akka-docs/src/main/paradox/stream/operators/Source/empty.md index 4d3ab25a2f..00f7b3f776 100644 --- a/akka-docs/src/main/paradox/stream/reference/empty.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/empty.md @@ -2,8 +2,16 @@ Complete right away without ever emitting any elements. +@ref[Source stages](../index.md#source-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Source.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Source.scala) { #empty } + +@@@ + ## Description Complete right away without ever emitting any elements. Useful when you have to provide a source to @@ -18,5 +26,3 @@ an API but there are no elements to emit. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/failed.md b/akka-docs/src/main/paradox/stream/operators/Source/failed.md similarity index 57% rename from akka-docs/src/main/paradox/stream/reference/failed.md rename to akka-docs/src/main/paradox/stream/operators/Source/failed.md index fe8cffa887..499530edb7 100644 --- a/akka-docs/src/main/paradox/stream/reference/failed.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/failed.md @@ -2,8 +2,16 @@ Fail directly with a user specified exception. +@ref[Source stages](../index.md#source-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Source.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Source.scala) { #failed } + +@@@ + ## Description Fail directly with a user specified exception. @@ -17,5 +25,3 @@ Fail directly with a user specified exception. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/operators/Source/from.md b/akka-docs/src/main/paradox/stream/operators/Source/from.md new file mode 100644 index 0000000000..a799ebb59e --- /dev/null +++ b/akka-docs/src/main/paradox/stream/operators/Source/from.md @@ -0,0 +1,19 @@ +# from + +Stream the values of an `Iterable`. + +@ref[Source stages](../index.md#source-stages) + +## Description + +Stream the values of an `Iterable`. Make sure the `Iterable` is immutable or at least not modified after being used +as a source. + +@@@div { .callout } + +**emits** the next value of the seq + +**completes** when the last element of the seq has been emitted + +@@@ + diff --git a/akka-docs/src/main/paradox/stream/reference/fromCompletionStage.md b/akka-docs/src/main/paradox/stream/operators/Source/fromCompletionStage.md similarity index 66% rename from akka-docs/src/main/paradox/stream/reference/fromCompletionStage.md rename to akka-docs/src/main/paradox/stream/operators/Source/fromCompletionStage.md index 9ebacb8774..48d7678510 100644 --- a/akka-docs/src/main/paradox/stream/reference/fromCompletionStage.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/fromCompletionStage.md @@ -2,8 +2,16 @@ Send the single value of the `CompletionStage` when it completes and there is demand. +@ref[Source stages](../index.md#source-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Source.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Source.scala) { #fromCompletionStage } + +@@@ + ## Description Send the single value of the `CompletionStage` when it completes and there is demand. @@ -18,5 +26,3 @@ If the future fails the stream is failed with that exception. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/fromFuture.md b/akka-docs/src/main/paradox/stream/operators/Source/fromFuture.md similarity index 65% rename from akka-docs/src/main/paradox/stream/reference/fromFuture.md rename to akka-docs/src/main/paradox/stream/operators/Source/fromFuture.md index b0300c364a..eda090565f 100644 --- a/akka-docs/src/main/paradox/stream/reference/fromFuture.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/fromFuture.md @@ -2,8 +2,16 @@ Send the single value of the `Future` when it completes and there is demand. +@ref[Source stages](../index.md#source-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Source.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Source.scala) { #fromFuture } + +@@@ + ## Description Send the single value of the `Future` when it completes and there is demand. @@ -18,5 +26,3 @@ If the future fails the stream is failed with that exception. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/fromFutureSource.md b/akka-docs/src/main/paradox/stream/operators/Source/fromFutureSource.md similarity index 67% rename from akka-docs/src/main/paradox/stream/reference/fromFutureSource.md rename to akka-docs/src/main/paradox/stream/operators/Source/fromFutureSource.md index ef16e7fb30..5ba3e51e32 100644 --- a/akka-docs/src/main/paradox/stream/reference/fromFutureSource.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/fromFutureSource.md @@ -2,8 +2,16 @@ Streams the elements of the given future source once it successfully completes. +@ref[Source stages](../index.md#source-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Source.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Source.scala) { #fromFutureSource } + +@@@ + ## Description Streams the elements of the given future source once it successfully completes. @@ -18,5 +26,3 @@ If the future fails the stream is failed. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/fromIterator.md b/akka-docs/src/main/paradox/stream/operators/Source/fromIterator.md similarity index 77% rename from akka-docs/src/main/paradox/stream/reference/fromIterator.md rename to akka-docs/src/main/paradox/stream/operators/Source/fromIterator.md index 8ab8cf938b..6652fa7a14 100644 --- a/akka-docs/src/main/paradox/stream/reference/fromIterator.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/fromIterator.md @@ -2,9 +2,15 @@ Stream the values from an `Iterator`, requesting the next value when there is demand. +@ref[Source stages](../index.md#source-stages) + +@@@div { .group-scala } + ## Signature -@@signature [BasicDirectives.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Source.scala) { #fromIterator } +@@signature [Source.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Source.scala) { #fromIterator } + +@@@ ## Description @@ -13,7 +19,6 @@ for each materialization, which is the reason the @scala[`method`] @java[`factor If the iterator perform blocking operations, make sure to run it on a separate dispatcher. - @@@div { .callout } **emits** the next value returned from the iterator @@ -22,5 +27,3 @@ If the iterator perform blocking operations, make sure to run it on a separate d @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/operators/Source/fromPublisher.md b/akka-docs/src/main/paradox/stream/operators/Source/fromPublisher.md new file mode 100644 index 0000000000..dcc0514acf --- /dev/null +++ b/akka-docs/src/main/paradox/stream/operators/Source/fromPublisher.md @@ -0,0 +1,14 @@ +# fromPublisher + +Integration with Reactive Streams, subscribes to a `org.reactivestreams.Publisher`. + +@ref[Source stages](../index.md#source-stages) + +@@@div { .group-scala } + +## Signature + +@@signature [Source.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Source.scala) { #fromPublisher } + +@@@ + diff --git a/akka-docs/src/main/paradox/stream/reference/fromSourceCompletionStage.md b/akka-docs/src/main/paradox/stream/operators/Source/fromSourceCompletionStage.md similarity index 91% rename from akka-docs/src/main/paradox/stream/reference/fromSourceCompletionStage.md rename to akka-docs/src/main/paradox/stream/operators/Source/fromSourceCompletionStage.md index 03e0a08ceb..40445e77c3 100644 --- a/akka-docs/src/main/paradox/stream/reference/fromSourceCompletionStage.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/fromSourceCompletionStage.md @@ -2,6 +2,8 @@ Streams the elements of an asynchronous source once its given *completion* stage completes. +@ref[Source stages](../index.md#source-stages) + ## Signature ## Description @@ -18,5 +20,3 @@ If the *completion* fails the stream is failed with that exception. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/lazily.md b/akka-docs/src/main/paradox/stream/operators/Source/lazily.md similarity index 62% rename from akka-docs/src/main/paradox/stream/reference/lazily.md rename to akka-docs/src/main/paradox/stream/operators/Source/lazily.md index 29cd0eed86..e7c7d228e7 100644 --- a/akka-docs/src/main/paradox/stream/reference/lazily.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/lazily.md @@ -2,8 +2,16 @@ Defers creation and materialization of a `Source` until there is demand. +@ref[Source stages](../index.md#source-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Source.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Source.scala) { #lazily } + +@@@ + ## Description Defers creation and materialization of a `Source` until there is demand. @@ -17,5 +25,3 @@ Defers creation and materialization of a `Source` until there is demand. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/lazilyAsync.md b/akka-docs/src/main/paradox/stream/operators/Source/lazilyAsync.md similarity index 87% rename from akka-docs/src/main/paradox/stream/reference/lazilyAsync.md rename to akka-docs/src/main/paradox/stream/operators/Source/lazilyAsync.md index 2a6317bffe..dafefb601b 100644 --- a/akka-docs/src/main/paradox/stream/reference/lazilyAsync.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/lazilyAsync.md @@ -2,6 +2,8 @@ Defers creation and materialization of a `CompletionStage` until there is demand. +@ref[Source stages](../index.md#source-stages) + ## Signature ## Description @@ -17,5 +19,3 @@ Defers creation and materialization of a `CompletionStage` until there is demand @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/maybe.md b/akka-docs/src/main/paradox/stream/operators/Source/maybe.md similarity index 65% rename from akka-docs/src/main/paradox/stream/reference/maybe.md rename to akka-docs/src/main/paradox/stream/operators/Source/maybe.md index fb33c1b41a..fc2c521598 100644 --- a/akka-docs/src/main/paradox/stream/reference/maybe.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/maybe.md @@ -1,10 +1,17 @@ # maybe -Materialize a @scala[`Promise[Option[T]]`] @java[`CompletionStage`] that if completed with a @scala[`Some[T]`] @java[`Optional`] -will emit that *T* and then complete the stream, or if completed with @scala[`None`] @java[`empty Optional`] complete the stream right away. +Materialize a @scala[`Promise[Option[T]]`] @java[`CompletionStage`] that if completed with a @scala[`Some[T]`] @java[`Optional`] will emit that *T* and then complete the stream, or if completed with @scala[`None`] @java[`empty Optional`] complete the stream right away. + +@ref[Source stages](../index.md#source-stages) + +@@@div { .group-scala } ## Signature +@@signature [Source.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Source.scala) { #maybe } + +@@@ + ## Description Materialize a @scala[`Promise[Option[T]]`] @java[`CompletionStage`] that if completed with a @scala[`Some[T]`] @java[`Optional`] @@ -19,5 +26,3 @@ will emit that *T* and then complete the stream, or if completed with @scala[`No @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/operators/Source/queue.md b/akka-docs/src/main/paradox/stream/operators/Source/queue.md new file mode 100644 index 0000000000..fd2bea6e9d --- /dev/null +++ b/akka-docs/src/main/paradox/stream/operators/Source/queue.md @@ -0,0 +1,30 @@ +# queue + +Materialize a `SourceQueue` onto which elements can be pushed for emitting from the source. + +@ref[Source stages](../index.md#source-stages) + +@@@div { .group-scala } + +## Signature + +@@signature [Source.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Source.scala) { #queue } + +@@@ + +## Description + +Materialize a `SourceQueue` onto which elements can be pushed for emitting from the source. The queue contains +a buffer, if elements are pushed onto the queue faster than the source is consumed the overflow will be handled with +a strategy specified by the user. Functionality for tracking when an element has been emitted is available through +`SourceQueue.offer`. + + +@@@div { .callout } + +**emits** when there is demand and the queue contains elements + +**completes** when downstream completes + +@@@ + diff --git a/akka-docs/src/main/paradox/stream/reference/range.md b/akka-docs/src/main/paradox/stream/operators/Source/range.md similarity index 82% rename from akka-docs/src/main/paradox/stream/reference/range.md rename to akka-docs/src/main/paradox/stream/operators/Source/range.md index 13a8555521..77b9f48772 100644 --- a/akka-docs/src/main/paradox/stream/reference/range.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/range.md @@ -1,8 +1,8 @@ -# range +# Source.range Emit each integer in a range, with an option to take bigger steps than 1. -## Signature +@ref[Source stages](../index.md#source-stages) ## Description @@ -17,5 +17,3 @@ Emit each integer in a range, with an option to take bigger steps than 1. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/operators/Source/repeat.md b/akka-docs/src/main/paradox/stream/operators/Source/repeat.md new file mode 100644 index 0000000000..09ca536d19 --- /dev/null +++ b/akka-docs/src/main/paradox/stream/operators/Source/repeat.md @@ -0,0 +1,27 @@ +# Source.repeat + +Stream a single object repeatedly + +@ref[Source stages](../index.md#source-stages) + +@@@div { .group-scala } + +## Signature + +@@signature [Source.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Source.scala) { #repeat } + +@@@ + +## Description + +Stream a single object repeatedly + + +@@@div { .callout } + +**emits** the same value repeatedly when there is demand + +**completes** never + +@@@ + diff --git a/akka-docs/src/main/paradox/stream/operators/Source/single.md b/akka-docs/src/main/paradox/stream/operators/Source/single.md new file mode 100644 index 0000000000..a30906d958 --- /dev/null +++ b/akka-docs/src/main/paradox/stream/operators/Source/single.md @@ -0,0 +1,27 @@ +# Source.single + +Stream a single object + +@ref[Source stages](../index.md#source-stages) + +@@@div { .group-scala } + +## Signature + +@@signature [Source.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Source.scala) { #single } + +@@@ + +## Description + +Stream a single object + + +@@@div { .callout } + +**emits** the value once + +**completes** when the single value has been emitted + +@@@ + diff --git a/akka-docs/src/main/paradox/stream/reference/tick.md b/akka-docs/src/main/paradox/stream/operators/Source/tick.md similarity index 63% rename from akka-docs/src/main/paradox/stream/reference/tick.md rename to akka-docs/src/main/paradox/stream/operators/Source/tick.md index c9f35b5355..9b8e01fc23 100644 --- a/akka-docs/src/main/paradox/stream/reference/tick.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/tick.md @@ -1,9 +1,17 @@ -# tick +# Source.tick A periodical repetition of an arbitrary object. +@ref[Source stages](../index.md#source-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Source.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Source.scala) { #tick } + +@@@ + ## Description A periodical repetition of an arbitrary object. Delay of first tick is specified @@ -18,5 +26,3 @@ separately from interval of the following ticks. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/unfold.md b/akka-docs/src/main/paradox/stream/operators/Source/unfold.md similarity index 71% rename from akka-docs/src/main/paradox/stream/reference/unfold.md rename to akka-docs/src/main/paradox/stream/operators/Source/unfold.md index 4b4a7cef53..882481e073 100644 --- a/akka-docs/src/main/paradox/stream/reference/unfold.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/unfold.md @@ -1,14 +1,20 @@ -# unfold +# Source.unfold -Stream the result of a function as long as it returns a @scala[`Some`] @java[`Optional`], the value inside the option -consists of a @scala[tuple] @java[pair] where the first value is a state passed back into the next call to the function allowing -to pass a state. +Stream the result of a function as long as it returns a @scala[`Some`] @java[`Optional`]. + +@ref[Source stages](../index.md#source-stages) + +@@@div { .group-scala } ## Signature +@@signature [Source.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Source.scala) { #unfold } + +@@@ + ## Description -Stream the result of a function as long as it returns a @scala[`Some`] @java[`Optional`], the value inside the option +Stream the result of a function as long as it returns a @scala[`Some`] @java[`Optional`]. The value inside the option consists of a @scala[tuple] @java[pair] where the first value is a state passed back into the next call to the function allowing to pass a state. The first invocation of the provided fold function will receive the `zero` state. @@ -23,5 +29,3 @@ Can be used to implement many stateful sources without having to touch the more @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/unfoldAsync.md b/akka-docs/src/main/paradox/stream/operators/Source/unfoldAsync.md similarity index 71% rename from akka-docs/src/main/paradox/stream/reference/unfoldAsync.md rename to akka-docs/src/main/paradox/stream/operators/Source/unfoldAsync.md index 1d223b689a..f530351099 100644 --- a/akka-docs/src/main/paradox/stream/reference/unfoldAsync.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/unfoldAsync.md @@ -1,10 +1,17 @@ -# unfoldAsync +# Source.unfoldAsync -Just like `unfold` but the fold function returns a @scala[`Future`] @java[`CompletionStage`] which will cause the source to -complete or emit when it completes. +Just like `unfold` but the fold function returns a @scala[`Future`] @java[`CompletionStage`]. + +@ref[Source stages](../index.md#source-stages) + +@@@div { .group-scala } ## Signature +@@signature [Source.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Source.scala) { #unfoldAsync } + +@@@ + ## Description Just like `unfold` but the fold function returns a @scala[`Future`] @java[`CompletionStage`] which will cause the source to @@ -21,5 +28,3 @@ Can be used to implement many stateful sources without having to touch the more @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/unfoldResource.md b/akka-docs/src/main/paradox/stream/operators/Source/unfoldResource.md similarity index 68% rename from akka-docs/src/main/paradox/stream/reference/unfoldResource.md rename to akka-docs/src/main/paradox/stream/operators/Source/unfoldResource.md index 5ee8561bd7..e2b977d3a0 100644 --- a/akka-docs/src/main/paradox/stream/reference/unfoldResource.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/unfoldResource.md @@ -1,9 +1,17 @@ -# unfoldResource +# Source.unfoldResource Wrap any resource that can be opened, queried for next element (in a blocking way) and closed using three distinct functions into a source. +@ref[Source stages](../index.md#source-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Source.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Source.scala) { #unfoldResource } + +@@@ + ## Description Wrap any resource that can be opened, queried for next element (in a blocking way) and closed using three distinct functions into a source. @@ -17,5 +25,3 @@ Wrap any resource that can be opened, queried for next element (in a blocking wa @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/unfoldResourceAsync.md b/akka-docs/src/main/paradox/stream/operators/Source/unfoldResourceAsync.md similarity index 73% rename from akka-docs/src/main/paradox/stream/reference/unfoldResourceAsync.md rename to akka-docs/src/main/paradox/stream/operators/Source/unfoldResourceAsync.md index f3dc9618d9..3efb9d830a 100644 --- a/akka-docs/src/main/paradox/stream/reference/unfoldResourceAsync.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/unfoldResourceAsync.md @@ -1,9 +1,17 @@ -# unfoldResourceAsync +# Source.unfoldResourceAsync Wrap any resource that can be opened, queried for next element (in a blocking way) and closed using three distinct functions into a source. +@ref[Source stages](../index.md#source-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Source.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Source.scala) { #unfoldResourceAsync } + +@@@ + ## Description Wrap any resource that can be opened, queried for next element (in a blocking way) and closed using three distinct functions into a source. @@ -18,5 +26,3 @@ Functions return @scala[`Future`] @java[`CompletionStage`] to achieve asynchrono @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/zipN.md b/akka-docs/src/main/paradox/stream/operators/Source/zipN.md similarity index 60% rename from akka-docs/src/main/paradox/stream/reference/zipN.md rename to akka-docs/src/main/paradox/stream/operators/Source/zipN.md index 2a25f593c8..16b16305d1 100644 --- a/akka-docs/src/main/paradox/stream/reference/zipN.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/zipN.md @@ -1,9 +1,17 @@ -# zipN +# Source.zipN Combine the elements of multiple streams into a stream of sequences. +@ref[Source stages](../index.md#source-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Source.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Source.scala) { #zipN } + +@@@ + ## Description Combine the elements of multiple streams into a stream of sequences. @@ -17,5 +25,3 @@ Combine the elements of multiple streams into a stream of sequences. @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/zipWithN.md b/akka-docs/src/main/paradox/stream/operators/Source/zipWithN.md similarity index 63% rename from akka-docs/src/main/paradox/stream/reference/zipWithN.md rename to akka-docs/src/main/paradox/stream/operators/Source/zipWithN.md index 7c6ce3c2f2..921e0e27f0 100644 --- a/akka-docs/src/main/paradox/stream/reference/zipWithN.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/zipWithN.md @@ -1,9 +1,17 @@ -# zipWithN +# Source.zipWithN Combine the elements of multiple streams into a stream of sequences using a combiner function. +@ref[Source stages](../index.md#source-stages) + +@@@div { .group-scala } + ## Signature +@@signature [Source.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/Source.scala) { #zipWithN } + +@@@ + ## Description Combine the elements of multiple streams into a stream of sequences using a combiner function. @@ -17,5 +25,4 @@ Combine the elements of multiple streams into a stream of sequences using a comb @@@ -## Example diff --git a/akka-docs/src/main/paradox/stream/reference/asInputStream.md b/akka-docs/src/main/paradox/stream/operators/StreamConverters/asInputStream.md similarity index 86% rename from akka-docs/src/main/paradox/stream/reference/asInputStream.md rename to akka-docs/src/main/paradox/stream/operators/StreamConverters/asInputStream.md index daf7ca9ed5..761900f160 100644 --- a/akka-docs/src/main/paradox/stream/reference/asInputStream.md +++ b/akka-docs/src/main/paradox/stream/operators/StreamConverters/asInputStream.md @@ -1,7 +1,9 @@ -# asInputStream +# StreamConverters.asInputStream Create a sink which materializes into an `InputStream` that can be read to trigger demand through the sink. +@ref[Additional Sink and Source converters](../index.md#additional-sink-and-source-converters) + @@@ div { .group-scala } ## Signature @@ -22,5 +24,3 @@ The `InputStream` will be ended when the stream flowing into this `Sink` complet **backpressures** when no read is pending on the `InputStream` @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/asJavaStream.md b/akka-docs/src/main/paradox/stream/operators/StreamConverters/asJavaStream.md similarity index 88% rename from akka-docs/src/main/paradox/stream/reference/asJavaStream.md rename to akka-docs/src/main/paradox/stream/operators/StreamConverters/asJavaStream.md index 6641965d12..759ba09266 100644 --- a/akka-docs/src/main/paradox/stream/reference/asJavaStream.md +++ b/akka-docs/src/main/paradox/stream/operators/StreamConverters/asJavaStream.md @@ -1,7 +1,9 @@ -# asJavaStream +# StreamConverters.asJavaStream Create a sink which materializes into Java 8 `Stream` that can be run to trigger demand through the sink. +@ref[Additional Sink and Source converters](../index.md#additional-sink-and-source-converters) + @@@ div { .group-scala } ## Signature @@ -24,5 +26,3 @@ Be aware that Java `Stream` blocks current thread while waiting on next element **backpressures** when no read is pending on the Java Stream @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/asOutputStream.md b/akka-docs/src/main/paradox/stream/operators/StreamConverters/asOutputStream.md similarity index 84% rename from akka-docs/src/main/paradox/stream/reference/asOutputStream.md rename to akka-docs/src/main/paradox/stream/operators/StreamConverters/asOutputStream.md index 8cf634f879..7a0afcf6ea 100644 --- a/akka-docs/src/main/paradox/stream/reference/asOutputStream.md +++ b/akka-docs/src/main/paradox/stream/operators/StreamConverters/asOutputStream.md @@ -1,7 +1,9 @@ -# asOutputStream +# StreamConverters.asOutputStream Create a source that materializes into an `OutputStream`. +@ref[Additional Sink and Source converters](../index.md#additional-sink-and-source-converters) + @@@ div { .group-scala } ## Signature @@ -22,5 +24,3 @@ closing the `OutputStream` will complete the `Source`. **completes** when the `OutputStream` is closed @@@ -## Example - diff --git a/akka-docs/src/main/paradox/stream/operators/StreamConverters/fromInputStream.md b/akka-docs/src/main/paradox/stream/operators/StreamConverters/fromInputStream.md new file mode 100644 index 0000000000..00746b4b81 --- /dev/null +++ b/akka-docs/src/main/paradox/stream/operators/StreamConverters/fromInputStream.md @@ -0,0 +1,22 @@ +# StreamConverters.fromInputStream + +Create a source that wraps an `InputStream`. + +@ref[Additional Sink and Source converters](../index.md#additional-sink-and-source-converters) + +@@@div { .group-scala } + +## Signature + +@@signature [Source.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/StreamConverters.scala) { #fromInputStream } + +@@@ + +## Description + + + +@@@div { .callout } + +@@@ + diff --git a/akka-docs/src/main/paradox/stream/operators/StreamConverters/fromJavaStream.md b/akka-docs/src/main/paradox/stream/operators/StreamConverters/fromJavaStream.md new file mode 100644 index 0000000000..23d61c4e2f --- /dev/null +++ b/akka-docs/src/main/paradox/stream/operators/StreamConverters/fromJavaStream.md @@ -0,0 +1,14 @@ +# StreamConverters.fromJavaStream + +Create a source that wraps a Java 8 `Stream`. + +@ref[Additional Sink and Source converters](../index.md#additional-sink-and-source-converters) + +@@@div { .group-scala } + +## Signature + +@@signature [Source.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/StreamConverters.scala) { #fromJavaStream } + +@@@ + diff --git a/akka-docs/src/main/paradox/stream/operators/StreamConverters/fromOutputStream.md b/akka-docs/src/main/paradox/stream/operators/StreamConverters/fromOutputStream.md new file mode 100644 index 0000000000..d8f7d2858c --- /dev/null +++ b/akka-docs/src/main/paradox/stream/operators/StreamConverters/fromOutputStream.md @@ -0,0 +1,14 @@ +# StreamConverters.fromOutputStream + +Create a sink that wraps an `OutputStream`. + +@ref[Additional Sink and Source converters](../index.md#additional-sink-and-source-converters) + +@@@div { .group-scala } + +## Signature + +@@signature [Sink.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/StreamConverters.scala) { #fromOutputStream } + +@@@ + diff --git a/akka-docs/src/main/paradox/stream/operators/StreamConverters/javaCollector.md b/akka-docs/src/main/paradox/stream/operators/StreamConverters/javaCollector.md new file mode 100644 index 0000000000..aa03ccea0f --- /dev/null +++ b/akka-docs/src/main/paradox/stream/operators/StreamConverters/javaCollector.md @@ -0,0 +1,22 @@ +# StreamConverters.javaCollector + +Create a sink which materializes into a @scala[`Future`] @java[`CompletionStage`] which will be completed with a result of the Java 8 `Collector` transformation and reduction operations. + +@ref[Additional Sink and Source converters](../index.md#additional-sink-and-source-converters) + +@@@div { .group-scala } + +## Signature + +@@signature [StreamConverters.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/StreamConverters.scala) { #javaCollector } + +@@@ + +## Description + + + +@@@div { .callout } + +@@@ + diff --git a/akka-docs/src/main/paradox/stream/operators/StreamConverters/javaCollectorParallelUnordered.md b/akka-docs/src/main/paradox/stream/operators/StreamConverters/javaCollectorParallelUnordered.md new file mode 100644 index 0000000000..6715d59b2d --- /dev/null +++ b/akka-docs/src/main/paradox/stream/operators/StreamConverters/javaCollectorParallelUnordered.md @@ -0,0 +1,22 @@ +# StreamConverters.javaCollectorParallelUnordered + +Create a sink which materializes into a @scala[`Future`] @java[`CompletionStage`] which will be completed with a result of the Java 8 `Collector` transformation and reduction operations. + +@ref[Additional Sink and Source converters](../index.md#additional-sink-and-source-converters) + +@@@div { .group-scala } + +## Signature + +@@signature [StreamConverters.scala]($akka$/akka-stream/src/main/scala/akka/stream/scaladsl/StreamConverters.scala) { #javaCollectorParallelUnordered } + +@@@ + +## Description + + + +@@@div { .callout } + +@@@ + diff --git a/akka-docs/src/main/paradox/stream/operators/index.md b/akka-docs/src/main/paradox/stream/operators/index.md new file mode 100644 index 0000000000..118ffffe28 --- /dev/null +++ b/akka-docs/src/main/paradox/stream/operators/index.md @@ -0,0 +1,387 @@ +# Operators + +## Source stages + +These built-in sources are available from @scala[`akka.stream.scaladsl.Source`] @java[`akka.stream.javadsl.Source`]: + +| |Operator|Description| +|--|--|--| +|Source|@ref[actorRef](Source/actorRef.md)|Materialize an `ActorRef`, sending messages to it will emit them on the stream. | +|Source|@ref[asSubscriber](Source/asSubscriber.md)|Integration with Reactive Streams, materializes into a `org.reactivestreams.Subscriber`.| +|Source|@ref[combine](Source/combine.md)|Combine several sources, using a given strategy such as merge or concat, into one source.| +|Source|@ref[cycle](Source/cycle.md)|Stream iterator in cycled manner.| +|Source|@ref[empty](Source/empty.md)|Complete right away without ever emitting any elements.| +|Source|@ref[failed](Source/failed.md)|Fail directly with a user specified exception.| +|Source|@ref[from](Source/from.md)|Stream the values of an `Iterable`.| +|Source|@ref[fromCompletionStage](Source/fromCompletionStage.md)|Send the single value of the `CompletionStage` when it completes and there is demand.| +|Source|@ref[fromFuture](Source/fromFuture.md)|Send the single value of the `Future` when it completes and there is demand.| +|Source|@ref[fromFutureSource](Source/fromFutureSource.md)|Streams the elements of the given future source once it successfully completes.| +|Source|@ref[fromIterator](Source/fromIterator.md)|Stream the values from an `Iterator`, requesting the next value when there is demand.| +|Source|@ref[fromPublisher](Source/fromPublisher.md)|Integration with Reactive Streams, subscribes to a `org.reactivestreams.Publisher`.| +|Source|@ref[fromSourceCompletionStage](Source/fromSourceCompletionStage.md)|Streams the elements of an asynchronous source once its given *completion* stage completes.| +|Source|@ref[lazily](Source/lazily.md)|Defers creation and materialization of a `Source` until there is demand.| +|Source|@ref[lazilyAsync](Source/lazilyAsync.md)|Defers creation and materialization of a `CompletionStage` until there is demand.| +|Source|@ref[maybe](Source/maybe.md)|Materialize a @scala[`Promise[Option[T]]`] @java[`CompletionStage`] that if completed with a @scala[`Some[T]`] @java[`Optional`] will emit that *T* and then complete the stream, or if completed with @scala[`None`] @java[`empty Optional`] complete the stream right away.| +|Source|@ref[queue](Source/queue.md)|Materialize a `SourceQueue` onto which elements can be pushed for emitting from the source. | +|Source|@ref[range](Source/range.md)|Emit each integer in a range, with an option to take bigger steps than 1.| +|Source|@ref[repeat](Source/repeat.md)|Stream a single object repeatedly| +|Source|@ref[single](Source/single.md)|Stream a single object| +|Source|@ref[tick](Source/tick.md)|A periodical repetition of an arbitrary object.| +|Source|@ref[unfold](Source/unfold.md)|Stream the result of a function as long as it returns a @scala[`Some`] @java[`Optional`].| +|Source|@ref[unfoldAsync](Source/unfoldAsync.md)|Just like `unfold` but the fold function returns a @scala[`Future`] @java[`CompletionStage`].| +|Source|@ref[unfoldResource](Source/unfoldResource.md)|Wrap any resource that can be opened, queried for next element (in a blocking way) and closed using three distinct functions into a source.| +|Source|@ref[unfoldResourceAsync](Source/unfoldResourceAsync.md)|Wrap any resource that can be opened, queried for next element (in a blocking way) and closed using three distinct functions into a source.| +|Source|@ref[zipN](Source/zipN.md)|Combine the elements of multiple streams into a stream of sequences.| +|Source|@ref[zipWithN](Source/zipWithN.md)|Combine the elements of multiple streams into a stream of sequences using a combiner function.| + +## Sink stages + +These built-in sinks are available from @scala[`akka.stream.scaladsl.Sink`] @java[`akka.stream.javadsl.Sink`]: + + +| |Operator|Description| +|--|--|--| +|Sink|@ref[actorRef](Sink/actorRef.md)|Send the elements from the stream to an `ActorRef`.| +|Sink|@ref[actorRefWithAck](Sink/actorRefWithAck.md)|Send the elements from the stream to an `ActorRef` which must then acknowledge reception after completing a message, to provide back pressure onto the sink.| +|Sink|@ref[asPublisher](Sink/asPublisher.md)|Integration with Reactive Streams, materializes into a `org.reactivestreams.Publisher`.| +|Sink|@ref[cancelled](Sink/cancelled.md)|Immediately cancel the stream| +|Sink|@ref[combine](Sink/combine.md)|Combine several sinks into one using a user specified strategy| +|Sink|@ref[fold](Sink/fold.md)|Fold over emitted element with a function, where each invocation will get the new element and the result from the previous fold invocation.| +|Sink|@ref[foreach](Sink/foreach.md)|Invoke a given procedure for each element received.| +|Sink|@ref[foreachParallel](Sink/foreachParallel.md)|Like `foreach` but allows up to `parallellism` procedure calls to happen in parallel.| +|Sink|@ref[fromSubscriber](Sink/fromSubscriber.md)|Integration with Reactive Streams, wraps a `org.reactivestreams.Subscriber` as a sink.| +|Sink|@ref[head](Sink/head.md)|Materializes into a @scala[`Future`] @java[`CompletionStage`] which completes with the first value arriving, after this the stream is canceled.| +|Sink|@ref[headOption](Sink/headOption.md)|Materializes into a @scala[`Future[Option[T]]`] @java[`CompletionStage>`] which completes with the first value arriving wrapped in @scala[`Some`] @java[`Optional`], or @scala[a `None`] @java[an empty Optional] if the stream completes without any elements emitted.| +|Sink|@ref[ignore](Sink/ignore.md)|Consume all elements but discards them.| +|Sink|@ref[last](Sink/last.md)|Materializes into a @scala[`Future`] @java[`CompletionStage`] which will complete with the last value emitted when the stream completes.| +|Sink|@ref[lastOption](Sink/lastOption.md)|Materialize a @scala[`Future[Option[T]]`] @java[`CompletionStage>`] which completes with the last value emitted wrapped in an @scala[`Some`] @java[`Optional`] when the stream completes.| +|Sink|@ref[lazyInitAsync](Sink/lazyInitAsync.md)|Creates a real `Sink` upon receiving the first element. | +|Sink|@ref[onComplete](Sink/onComplete.md)|Invoke a callback when the stream has completed or failed.| +|Sink|@ref[preMaterialize](Sink/preMaterialize.md)|Materializes this Sink, immediately returning (1) its materialized value, and (2) a new Sink that can be consume elements 'into' the pre-materialized one.| +|Sink|@ref[queue](Sink/queue.md)|Materialize a `SinkQueue` that can be pulled to trigger demand through the sink.| +|Sink|@ref[reduce](Sink/reduce.md)|Apply a reduction function on the incoming elements and pass the result to the next invocation.| +|Sink|@ref[seq](Sink/seq.md)|Collect values emitted from the stream into a collection.| + +## Additional Sink and Source converters + +Sources and sinks for integrating with `java.io.InputStream` and `java.io.OutputStream` can be found on +`StreamConverters`. As they are blocking APIs the implementations of these stages are run on a separate +dispatcher configured through the `akka.stream.blocking-io-dispatcher`. + +@@@ warning + +Be aware that `asInputStream` and `asOutputStream` materialize `InputStream` and `OutputStream` respectively as +blocking API implementation. They will block tread until data will be available from upstream. +Because of blocking nature these objects cannot be used in `mapMaterializeValue` section as it causes deadlock +of the stream materialization process. +For example, following snippet will fall with timeout exception: + +```scala +... +.toMat(StreamConverters.asInputStream().mapMaterializedValue { inputStream ⇒ + inputStream.read() // this could block forever + ... +}).run() +``` + +@@@ + +| |Operator|Description| +|--|--|--| +|StreamConverters|@ref[asInputStream](StreamConverters/asInputStream.md)|Create a sink which materializes into an `InputStream` that can be read to trigger demand through the sink.| +|StreamConverters|@ref[asJavaStream](StreamConverters/asJavaStream.md)|Create a sink which materializes into Java 8 `Stream` that can be run to trigger demand through the sink.| +|StreamConverters|@ref[asOutputStream](StreamConverters/asOutputStream.md)|Create a source that materializes into an `OutputStream`.| +|StreamConverters|@ref[fromInputStream](StreamConverters/fromInputStream.md)|Create a source that wraps an `InputStream`.| +|StreamConverters|@ref[fromJavaStream](StreamConverters/fromJavaStream.md)|Create a source that wraps a Java 8 `Stream`.| +|StreamConverters|@ref[fromOutputStream](StreamConverters/fromOutputStream.md)|Create a sink that wraps an `OutputStream`.| +|StreamConverters|@ref[javaCollector](StreamConverters/javaCollector.md)|Create a sink which materializes into a @scala[`Future`] @java[`CompletionStage`] which will be completed with a result of the Java 8 `Collector` transformation and reduction operations.| +|StreamConverters|@ref[javaCollectorParallelUnordered](StreamConverters/javaCollectorParallelUnordered.md)|Create a sink which materializes into a @scala[`Future`] @java[`CompletionStage`] which will be completed with a result of the Java 8 `Collector` transformation and reduction operations.| + +## File IO Sinks and Sources + +Sources and sinks for reading and writing files can be found on `FileIO`. + +| |Operator|Description| +|--|--|--| +|FileIO|@ref[fromPath](FileIO/fromPath.md)|Emit the contents of a file.| +|FileIO|@ref[toPath](FileIO/toPath.md)|Create a sink which will write incoming `ByteString` s to a given file path.| + +## Simple processing stages + +These stages can transform the rate of incoming elements since there are stages that emit multiple elements for a +single input (e.g. `mapConcat`) or consume multiple elements before emitting one output (e.g. `filter`). +However, these rate transformations are data-driven, i.e. it is the incoming elements that define how the +rate is affected. This is in contrast with [detached stages](#backpressure-aware-stages) which can change their processing behavior +depending on being backpressured by downstream or not. + +| |Operator|Description| +|--|--|--| +|Source/Flow|@ref[alsoTo](Source-or-Flow/alsoTo.md)|Attaches the given `Sink` to this `Flow`, meaning that elements that pass through this `Flow` will also be sent to the `Sink`.| +|Source/Flow|@ref[collect](Source-or-Flow/collect.md)|Apply a partial function to each incoming element, if the partial function is defined for a value the returned value is passed downstream.| +|Source/Flow|@ref[collectType](Source-or-Flow/collectType.md)|Transform this stream by testing the type of each of the elements on which the element is an instance of the provided type as they pass through this processing step.| +|Source/Flow|@ref[detach](Source-or-Flow/detach.md)|Detach upstream demand from downstream demand without detaching the stream rates.| +|Source/Flow|@ref[divertTo](Source-or-Flow/divertTo.md)|Each upstream element will either be diverted to the given sink, or the downstream consumer according to the predicate function applied to the element.| +|Source/Flow|@ref[drop](Source-or-Flow/drop.md)|Drop `n` elements and then pass any subsequent element downstream.| +|Source/Flow|@ref[dropWhile](Source-or-Flow/dropWhile.md)|Drop elements as long as a predicate function return true for the element| +|Source/Flow|@ref[filter](Source-or-Flow/filter.md)|Filter the incoming elements using a predicate.| +|Source/Flow|@ref[filterNot](Source-or-Flow/filterNot.md)|Filter the incoming elements using a predicate.| +|Source/Flow|@ref[fold](Source-or-Flow/fold.md)|Start with current value `zero` and then apply the current and next value to the given function, when upstream complete the current value is emitted downstream.| +|Source/Flow|@ref[foldAsync](Source-or-Flow/foldAsync.md)|Just like `fold` but receiving a function that results in a @scala[`Future`] @java[`CompletionStage`] to the next value.| +|Source/Flow|@ref[grouped](Source-or-Flow/grouped.md)|Accumulate incoming events until the specified number of elements have been accumulated and then pass the collection of elements downstream.| +|Source/Flow|@ref[intersperse](Source-or-Flow/intersperse.md)|Intersperse stream with provided element similar to `List.mkString`.| +|Flow|@ref[lazyInitAsync](Flow/lazyInitAsync.md)|Creates a real `Flow` upon receiving the first element by calling relevant `flowFactory` given as an argument.| +|Source/Flow|@ref[limit](Source-or-Flow/limit.md)|Limit number of element from upstream to given `max` number.| +|Source/Flow|@ref[limitWeighted](Source-or-Flow/limitWeighted.md)|Ensure stream boundedness by evaluating the cost of incoming elements using a cost function.| +|Source/Flow|@ref[log](Source-or-Flow/log.md)|Log elements flowing through the stream as well as completion and erroring.| +|Source/Flow|@ref[map](Source-or-Flow/map.md)|Transform each element in the stream by calling a mapping function with it and passing the returned value downstream.| +|Source/Flow|@ref[mapConcat](Source-or-Flow/mapConcat.md)|Transform each element into zero or more elements that are individually passed downstream.| +|Source/Flow|@ref[mapError](Source-or-Flow/mapError.md)|While similar to `recover` this stage can be used to transform an error signal to a different one *without* logging it as an error in the process.| +|Source/Flow|@ref[recover](Source-or-Flow/recover.md)|Allow sending of one last element downstream when a failure has happened upstream.| +|Source/Flow|@ref[recoverWith](Source-or-Flow/recoverWith.md)|Allow switching to alternative Source when a failure has happened upstream.| +|Source/Flow|@ref[recoverWithRetries](Source-or-Flow/recoverWithRetries.md)|RecoverWithRetries allows to switch to alternative Source on flow failure.| +|Source/Flow|@ref[reduce](Source-or-Flow/reduce.md)|Start with first element and then apply the current and next value to the given function, when upstream complete the current value is emitted downstream.| +|Source/Flow|@ref[scan](Source-or-Flow/scan.md)|Emit its current value which starts at `zero` and then applies the current and next value to the given function emitting the next current value.| +|Source/Flow|@ref[scanAsync](Source-or-Flow/scanAsync.md)|Just like `scan` but receiving a function that results in a @scala[`Future`] @java[`CompletionStage`] to the next value.| +|Source/Flow|@ref[sliding](Source-or-Flow/sliding.md)|Provide a sliding window over the incoming stream and pass the windows as groups of elements downstream.| +|Source/Flow|@ref[statefulMapConcat](Source-or-Flow/statefulMapConcat.md)|Transform each element into zero or more elements that are individually passed downstream.| +|Source/Flow|@ref[take](Source-or-Flow/take.md)|Pass `n` incoming elements downstream and then complete| +|Source/Flow|@ref[takeWhile](Source-or-Flow/takeWhile.md)|Pass elements downstream as long as a predicate function return true for the element include the element when the predicate first return false and then complete.| +|Source/Flow|@ref[throttle](Source-or-Flow/throttle.md)|Limit the throughput to a specific number of elements per time unit, or a specific total cost per time unit, where a function has to be provided to calculate the individual cost of each element.| +|Source/Flow|@ref[watch](Source-or-Flow/watch.md)|Watch a specific `ActorRef` and signal a failure downstream once the actor terminates.| +|Source/Flow|@ref[wireTap](Source-or-Flow/wireTap.md)|Attaches the given `Sink` to this `Flow` as a wire tap, meaning that elements that pass through will also be sent to the wire-tap `Sink`, without the latter affecting the mainline flow.| + +## Flow stages composed of Sinks and Sources + + + +| |Operator|Description| +|--|--|--| +|Flow|@ref[fromSinkAndSource](Flow/fromSinkAndSource.md)|Creates a `Flow` from a `Sink` and a `Source` where the Flow's input will be sent to the `Sink` and the `Flow` 's output will come from the Source.| +|Flow|@ref[fromSinkAndSourceCoupled](Flow/fromSinkAndSourceCoupled.md)|Allows coupling termination (cancellation, completion, erroring) of Sinks and Sources while creating a Flow between them.| + +## Asynchronous processing stages + +These stages encapsulate an asynchronous computation, properly handling backpressure while taking care of the asynchronous +operation at the same time (usually handling the completion of a @scala[`Future`] @java[`CompletionStage`]). + +| |Operator|Description| +|--|--|--| +|Source/Flow|@ref[ask](Source-or-Flow/ask.md)|Use the `ask` pattern to send a request-reply message to the target `ref` actor.| +|Source/Flow|@ref[mapAsync](Source-or-Flow/mapAsync.md)|Pass incoming elements to a function that return a @scala[`Future`] @java[`CompletionStage`] result.| +|Source/Flow|@ref[mapAsyncUnordered](Source-or-Flow/mapAsyncUnordered.md)|Like `mapAsync` but @scala[`Future`] @java[`CompletionStage`] results are passed downstream as they arrive regardless of the order of the elements that triggered them.| + +## Timer driven stages + +These stages process elements using timers, delaying, dropping or grouping elements for certain time durations. + +| |Operator|Description| +|--|--|--| +|Source/Flow|@ref[delay](Source-or-Flow/delay.md)|Delay every element passed through with a specific duration.| +|Source/Flow|@ref[dropWithin](Source-or-Flow/dropWithin.md)|Drop elements until a timeout has fired| +|Source/Flow|@ref[groupedWeightedWithin](Source-or-Flow/groupedWeightedWithin.md)|Chunk up this stream into groups of elements received within a time window, or limited by the weight of the elements, whatever happens first.| +|Source/Flow|@ref[groupedWithin](Source-or-Flow/groupedWithin.md)|Chunk up this stream into groups of elements received within a time window, or limited by the number of the elements, whatever happens first.| +|Source/Flow|@ref[initialDelay](Source-or-Flow/initialDelay.md)|Delays the initial element by the specified duration.| +|Source/Flow|@ref[takeWithin](Source-or-Flow/takeWithin.md)|Pass elements downstream within a timeout and then complete.| + +## Backpressure aware stages + +These stages are aware of the backpressure provided by their downstreams and able to adapt their behavior to that signal. + +| |Operator|Description| +|--|--|--| +|Source/Flow|@ref[batch](Source-or-Flow/batch.md)|Allow for a slower downstream by passing incoming elements and a summary into an aggregate function as long as there is backpressure and a maximum number of batched elements is not yet reached.| +|Source/Flow|@ref[batchWeighted](Source-or-Flow/batchWeighted.md)|Allow for a slower downstream by passing incoming elements and a summary into an aggregate function as long as there is backpressure and a maximum weight batched elements is not yet reached.| +|Source/Flow|@ref[buffer](Source-or-Flow/buffer.md)|Allow for a temporarily faster upstream events by buffering `size` elements.| +|Source/Flow|@ref[conflate](Source-or-Flow/conflate.md)|Allow for a slower downstream by passing incoming elements and a summary into an aggregate function as long as there is backpressure.| +|Source/Flow|@ref[conflateWithSeed](Source-or-Flow/conflateWithSeed.md)|Allow for a slower downstream by passing incoming elements and a summary into an aggregate function as long as there is backpressure.| +|Source/Flow|@ref[expand](Source-or-Flow/expand.md)|Like `extrapolate`, but does not have the `initial` argument, and the `Iterator` is also used in lieu of the original element, allowing for it to be rewritten and/or filtered.| +|Source/Flow|@ref[extrapolate](Source-or-Flow/extrapolate.md)|Allow for a faster downstream by expanding the last emitted element to an `Iterator`.| + +## Nesting and flattening stages + +These stages either take a stream and turn it into a stream of streams (nesting) or they take a stream that contains +nested streams and turn them into a stream of elements instead (flattening). + +See the [Substreams](stream-substream.md) page for more detail and code samples. + +| |Operator|Description| +|--|--|--| +|Source/Flow|@ref[flatMapConcat](Source-or-Flow/flatMapConcat.md)|Transform each input element into a `Source` whose elements are then flattened into the output stream through concatenation.| +|Source/Flow|@ref[flatMapMerge](Source-or-Flow/flatMapMerge.md)|Transform each input element into a `Source` whose elements are then flattened into the output stream through merging.| +|Source/Flow|@ref[groupBy](Source-or-Flow/groupBy.md)|Demultiplex the incoming stream into separate output streams.| +|Source/Flow|@ref[prefixAndTail](Source-or-Flow/prefixAndTail.md)|Take up to *n* elements from the stream (less than *n* only if the upstream completes before emitting *n* elements) and returns a pair containing a strict sequence of the taken element and a stream representing the remaining elements.| +|Source/Flow|@ref[splitAfter](Source-or-Flow/splitAfter.md)|End the current substream whenever a predicate returns `true`, starting a new substream for the next element.| +|Source/Flow|@ref[splitWhen](Source-or-Flow/splitWhen.md)|Split off elements into a new substream whenever a predicate function return `true`.| + +## Time aware stages + +Those stages operate taking time into consideration. + +| |Operator|Description| +|--|--|--| +|Source/Flow|@ref[backpressureTimeout](Source-or-Flow/backpressureTimeout.md)|If the time between the emission of an element and the following downstream demand exceeds the provided timeout, the stream is failed with a `TimeoutException`.| +|Source/Flow|@ref[completionTimeout](Source-or-Flow/completionTimeout.md)|If the completion of the stream does not happen until the provided timeout, the stream is failed with a `TimeoutException`.| +|Source/Flow|@ref[idleTimeout](Source-or-Flow/idleTimeout.md)|If the time between two processed elements exceeds the provided timeout, the stream is failed with a `TimeoutException`.| +|Source/Flow|@ref[initialTimeout](Source-or-Flow/initialTimeout.md)|If the first element has not passed through this stage before the provided timeout, the stream is failed with a `TimeoutException`.| +|Source/Flow|@ref[keepAlive](Source-or-Flow/keepAlive.md)|Injects additional (configured) elements if upstream does not emit for a configured amount of time.| + +## Fan-in stages + +These stages take multiple streams as their input and provide a single output combining the elements from all of +the inputs in different ways. + +| |Operator|Description| +|--|--|--| +|Source/Flow|@ref[concat](Source-or-Flow/concat.md)|After completion of the original upstream the elements of the given source will be emitted.| +|Source/Flow|@ref[interleave](Source-or-Flow/interleave.md)|Emits a specifiable number of elements from the original source, then from the provided source and repeats.| +|Source/Flow|@ref[merge](Source-or-Flow/merge.md)|Merge multiple sources.| +|Source/Flow|@ref[mergeSorted](Source-or-Flow/mergeSorted.md)|Merge multiple sources.| +|Source/Flow|@ref[orElse](Source-or-Flow/orElse.md)|If the primary source completes without emitting any elements, the elements from the secondary source are emitted.| +|Source/Flow|@ref[prepend](Source-or-Flow/prepend.md)|Prepends the given source to the flow, consuming it until completion before the original source is consumed.| +|Source/Flow|@ref[zip](Source-or-Flow/zip.md)|Combines elements from each of multiple sources into @scala[tuples] @java[*Pair*] and passes the @scala[tuples] @java[pairs] downstream.| +|Source/Flow|@ref[zipWith](Source-or-Flow/zipWith.md)|Combines elements from multiple sources through a `combine` function and passes the returned value downstream.| +|Source/Flow|@ref[zipWithIndex](Source-or-Flow/zipWithIndex.md)|Zips elements of current flow with its indices.| + +## Watching status stages + + + +| |Operator|Description| +|--|--|--| +|Source/Flow|@ref[monitor](Source-or-Flow/monitor.md)|Materializes to a `FlowMonitor` that monitors messages flowing through or completion of the stage.| +|Source/Flow|@ref[watchTermination](Source-or-Flow/watchTermination.md)|Materializes to a @scala[`Future`] @java[`CompletionStage`] that will be completed with Done or failed depending whether the upstream of the stage has been completed or failed.| + +@@@ index + +* [combine](Source/combine.md) +* [fromPublisher](Source/fromPublisher.md) +* [fromIterator](Source/fromIterator.md) +* [cycle](Source/cycle.md) +* [fromFuture](Source/fromFuture.md) +* [fromCompletionStage](Source/fromCompletionStage.md) +* [fromFutureSource](Source/fromFutureSource.md) +* [fromSourceCompletionStage](Source/fromSourceCompletionStage.md) +* [tick](Source/tick.md) +* [single](Source/single.md) +* [repeat](Source/repeat.md) +* [unfold](Source/unfold.md) +* [unfoldAsync](Source/unfoldAsync.md) +* [empty](Source/empty.md) +* [maybe](Source/maybe.md) +* [failed](Source/failed.md) +* [lazily](Source/lazily.md) +* [lazilyAsync](Source/lazilyAsync.md) +* [asSubscriber](Source/asSubscriber.md) +* [actorRef](Source/actorRef.md) +* [zipN](Source/zipN.md) +* [zipWithN](Source/zipWithN.md) +* [queue](Source/queue.md) +* [unfoldResource](Source/unfoldResource.md) +* [unfoldResourceAsync](Source/unfoldResourceAsync.md) +* [from](Source/from.md) +* [range](Source/range.md) +* [concat](Source-or-Flow/concat.md) +* [prepend](Source-or-Flow/prepend.md) +* [orElse](Source-or-Flow/orElse.md) +* [alsoTo](Source-or-Flow/alsoTo.md) +* [divertTo](Source-or-Flow/divertTo.md) +* [wireTap](Source-or-Flow/wireTap.md) +* [interleave](Source-or-Flow/interleave.md) +* [merge](Source-or-Flow/merge.md) +* [mergeSorted](Source-or-Flow/mergeSorted.md) +* [zip](Source-or-Flow/zip.md) +* [zipWith](Source-or-Flow/zipWith.md) +* [zipWithIndex](Source-or-Flow/zipWithIndex.md) +* [map](Source-or-Flow/map.md) +* [recover](Source-or-Flow/recover.md) +* [mapError](Source-or-Flow/mapError.md) +* [recoverWith](Source-or-Flow/recoverWith.md) +* [recoverWithRetries](Source-or-Flow/recoverWithRetries.md) +* [mapConcat](Source-or-Flow/mapConcat.md) +* [statefulMapConcat](Source-or-Flow/statefulMapConcat.md) +* [mapAsync](Source-or-Flow/mapAsync.md) +* [mapAsyncUnordered](Source-or-Flow/mapAsyncUnordered.md) +* [ask](Source-or-Flow/ask.md) +* [watch](Source-or-Flow/watch.md) +* [filter](Source-or-Flow/filter.md) +* [filterNot](Source-or-Flow/filterNot.md) +* [collect](Source-or-Flow/collect.md) +* [collectType](Source-or-Flow/collectType.md) +* [grouped](Source-or-Flow/grouped.md) +* [limit](Source-or-Flow/limit.md) +* [limitWeighted](Source-or-Flow/limitWeighted.md) +* [sliding](Source-or-Flow/sliding.md) +* [scan](Source-or-Flow/scan.md) +* [scanAsync](Source-or-Flow/scanAsync.md) +* [fold](Source-or-Flow/fold.md) +* [foldAsync](Source-or-Flow/foldAsync.md) +* [reduce](Source-or-Flow/reduce.md) +* [intersperse](Source-or-Flow/intersperse.md) +* [groupedWithin](Source-or-Flow/groupedWithin.md) +* [groupedWeightedWithin](Source-or-Flow/groupedWeightedWithin.md) +* [delay](Source-or-Flow/delay.md) +* [drop](Source-or-Flow/drop.md) +* [dropWithin](Source-or-Flow/dropWithin.md) +* [takeWhile](Source-or-Flow/takeWhile.md) +* [dropWhile](Source-or-Flow/dropWhile.md) +* [take](Source-or-Flow/take.md) +* [takeWithin](Source-or-Flow/takeWithin.md) +* [conflateWithSeed](Source-or-Flow/conflateWithSeed.md) +* [conflate](Source-or-Flow/conflate.md) +* [batch](Source-or-Flow/batch.md) +* [batchWeighted](Source-or-Flow/batchWeighted.md) +* [expand](Source-or-Flow/expand.md) +* [extrapolate](Source-or-Flow/extrapolate.md) +* [buffer](Source-or-Flow/buffer.md) +* [prefixAndTail](Source-or-Flow/prefixAndTail.md) +* [groupBy](Source-or-Flow/groupBy.md) +* [splitWhen](Source-or-Flow/splitWhen.md) +* [splitAfter](Source-or-Flow/splitAfter.md) +* [flatMapConcat](Source-or-Flow/flatMapConcat.md) +* [flatMapMerge](Source-or-Flow/flatMapMerge.md) +* [initialTimeout](Source-or-Flow/initialTimeout.md) +* [completionTimeout](Source-or-Flow/completionTimeout.md) +* [idleTimeout](Source-or-Flow/idleTimeout.md) +* [backpressureTimeout](Source-or-Flow/backpressureTimeout.md) +* [keepAlive](Source-or-Flow/keepAlive.md) +* [throttle](Source-or-Flow/throttle.md) +* [detach](Source-or-Flow/detach.md) +* [watchTermination](Source-or-Flow/watchTermination.md) +* [monitor](Source-or-Flow/monitor.md) +* [initialDelay](Source-or-Flow/initialDelay.md) +* [log](Source-or-Flow/log.md) +* [fromSinkAndSource](Flow/fromSinkAndSource.md) +* [fromSinkAndSourceCoupled](Flow/fromSinkAndSourceCoupled.md) +* [lazyInitAsync](Flow/lazyInitAsync.md) +* [preMaterialize](Sink/preMaterialize.md) +* [fromSubscriber](Sink/fromSubscriber.md) +* [cancelled](Sink/cancelled.md) +* [head](Sink/head.md) +* [headOption](Sink/headOption.md) +* [last](Sink/last.md) +* [lastOption](Sink/lastOption.md) +* [seq](Sink/seq.md) +* [asPublisher](Sink/asPublisher.md) +* [ignore](Sink/ignore.md) +* [foreach](Sink/foreach.md) +* [combine](Sink/combine.md) +* [foreachParallel](Sink/foreachParallel.md) +* [fold](Sink/fold.md) +* [reduce](Sink/reduce.md) +* [onComplete](Sink/onComplete.md) +* [actorRef](Sink/actorRef.md) +* [actorRefWithAck](Sink/actorRefWithAck.md) +* [queue](Sink/queue.md) +* [lazyInitAsync](Sink/lazyInitAsync.md) +* [fromInputStream](StreamConverters/fromInputStream.md) +* [asOutputStream](StreamConverters/asOutputStream.md) +* [fromOutputStream](StreamConverters/fromOutputStream.md) +* [asInputStream](StreamConverters/asInputStream.md) +* [javaCollector](StreamConverters/javaCollector.md) +* [javaCollectorParallelUnordered](StreamConverters/javaCollectorParallelUnordered.md) +* [asJavaStream](StreamConverters/asJavaStream.md) +* [fromJavaStream](StreamConverters/fromJavaStream.md) +* [fromPath](FileIO/fromPath.md) +* [toPath](FileIO/toPath.md) + +@@@ diff --git a/akka-docs/src/main/paradox/stream/reference/Flow.fromSinkAndSource.md b/akka-docs/src/main/paradox/stream/reference/Flow.fromSinkAndSource.md deleted file mode 100644 index 2ae391bf98..0000000000 --- a/akka-docs/src/main/paradox/stream/reference/Flow.fromSinkAndSource.md +++ /dev/null @@ -1,17 +0,0 @@ -# Flow.fromSinkAndSource - -Creates a `Flow` from a `Sink` and a `Source` where the Flow's input will be sent to the `Sink` -and the `Flow` 's output will come from the Source. - -## Signature - -## Description - - - -@@@div { .callout } - -@@@ - -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/Flow.fromSinkAndSourceCoupled.md b/akka-docs/src/main/paradox/stream/reference/Flow.fromSinkAndSourceCoupled.md deleted file mode 100644 index 5a6bce528d..0000000000 --- a/akka-docs/src/main/paradox/stream/reference/Flow.fromSinkAndSourceCoupled.md +++ /dev/null @@ -1,16 +0,0 @@ -# Flow.fromSinkAndSourceCoupled - -Allows coupling termination (cancellation, completion, erroring) of Sinks and Sources while creating a Flow between them. - -## Signature - -## Description - - - -@@@div { .callout } - -@@@ - -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/cancelled.md b/akka-docs/src/main/paradox/stream/reference/cancelled.md deleted file mode 100644 index 35243bbbea..0000000000 --- a/akka-docs/src/main/paradox/stream/reference/cancelled.md +++ /dev/null @@ -1,19 +0,0 @@ -# cancelled - -cancelled - -## Signature - -## Description - -Immediately cancel the stream - - -@@@div { .callout } - -**cancels** immediately - -@@@ - -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/collectType.md b/akka-docs/src/main/paradox/stream/reference/collectType.md deleted file mode 100644 index eba512458a..0000000000 --- a/akka-docs/src/main/paradox/stream/reference/collectType.md +++ /dev/null @@ -1,17 +0,0 @@ -# collectType - -Transform this stream by testing the type of each of the elements on which the element is an instance of -the provided type as they pass through this processing step. - -## Signature - -## Description - - - -@@@div { .callout } - -@@@ - -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/combine.md b/akka-docs/src/main/paradox/stream/reference/combine.md deleted file mode 100644 index 28a73896f9..0000000000 --- a/akka-docs/src/main/paradox/stream/reference/combine.md +++ /dev/null @@ -1,21 +0,0 @@ -# combine - -combine - -## Signature - -## Description - -Combine several sinks into one using a user specified strategy - - -@@@div { .callout } - -**cancels** depends on the strategy - -**backpressures** depends on the strategy - -@@@ - -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/fromInputStream.md b/akka-docs/src/main/paradox/stream/reference/fromInputStream.md deleted file mode 100644 index 02143cbf2f..0000000000 --- a/akka-docs/src/main/paradox/stream/reference/fromInputStream.md +++ /dev/null @@ -1,16 +0,0 @@ -# fromInputStream - -Create a source that wraps an `InputStream`. - -## Signature - -## Description - - - -@@@div { .callout } - -@@@ - -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/fromJavaStream.md b/akka-docs/src/main/paradox/stream/reference/fromJavaStream.md deleted file mode 100644 index 9abb17f28a..0000000000 --- a/akka-docs/src/main/paradox/stream/reference/fromJavaStream.md +++ /dev/null @@ -1,16 +0,0 @@ -# fromJavaStream - -Create a source that wraps a Java 8 `Stream`. - -## Signature - -## Description - - - -@@@div { .callout } - -@@@ - -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/fromOutputStream.md b/akka-docs/src/main/paradox/stream/reference/fromOutputStream.md deleted file mode 100644 index 256ab3aaa9..0000000000 --- a/akka-docs/src/main/paradox/stream/reference/fromOutputStream.md +++ /dev/null @@ -1,16 +0,0 @@ -# fromOutputStream - -Create a sink that wraps an `OutputStream`. - -## Signature - -## Description - - - -@@@div { .callout } - -@@@ - -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/fromPath.md b/akka-docs/src/main/paradox/stream/reference/fromPath.md deleted file mode 100644 index 4f796a0bf8..0000000000 --- a/akka-docs/src/main/paradox/stream/reference/fromPath.md +++ /dev/null @@ -1,17 +0,0 @@ -# fromPath - -Emit the contents of a file, as `ByteString` s, materializes into a @scala[`Future`] @java[`CompletionStage`]` which will be completed with -a `IOResult` upon reaching the end of the file or if there is a failure. - -## Signature - -## Description - - - -@@@div { .callout } - -@@@ - -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/fromPublisher.md b/akka-docs/src/main/paradox/stream/reference/fromPublisher.md deleted file mode 100644 index 3695dc3f96..0000000000 --- a/akka-docs/src/main/paradox/stream/reference/fromPublisher.md +++ /dev/null @@ -1,16 +0,0 @@ -# fromPublisher - -Integration with Reactive Streams, subscribes to a `org. - -## Signature - -## Description - - - -@@@div { .callout } - -@@@ - -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/fromSubscriber.md b/akka-docs/src/main/paradox/stream/reference/fromSubscriber.md deleted file mode 100644 index 1cd1a98e0f..0000000000 --- a/akka-docs/src/main/paradox/stream/reference/fromSubscriber.md +++ /dev/null @@ -1,16 +0,0 @@ -# fromSubscriber - -Integration with Reactive Streams, wraps a `org. - -## Signature - -## Description - - - -@@@div { .callout } - -@@@ - -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/javaCollector.md b/akka-docs/src/main/paradox/stream/reference/javaCollector.md deleted file mode 100644 index c4e48124b2..0000000000 --- a/akka-docs/src/main/paradox/stream/reference/javaCollector.md +++ /dev/null @@ -1,17 +0,0 @@ -# javaCollector - -Create a sink which materializes into a @scala[`Future`] @java[`CompletionStage`] which will be completed with a result of the Java 8 `Collector` -transformation and reduction operations. - -## Signature - -## Description - - - -@@@div { .callout } - -@@@ - -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/javaCollectorParallelUnordered.md b/akka-docs/src/main/paradox/stream/reference/javaCollectorParallelUnordered.md deleted file mode 100644 index ae4d6abd41..0000000000 --- a/akka-docs/src/main/paradox/stream/reference/javaCollectorParallelUnordered.md +++ /dev/null @@ -1,17 +0,0 @@ -# javaCollectorParallelUnordered - -Create a sink which materializes into a @scala[`Future`] @java[`CompletionStage`] which will be completed with a result of the Java 8 `Collector` -transformation and reduction operations. - -## Signature - -## Description - - - -@@@div { .callout } - -@@@ - -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/preMaterialize.md b/akka-docs/src/main/paradox/stream/reference/preMaterialize.md deleted file mode 100644 index 8a2e3e05b1..0000000000 --- a/akka-docs/src/main/paradox/stream/reference/preMaterialize.md +++ /dev/null @@ -1,16 +0,0 @@ -# preMaterialize - -Materializes this Sink, immediately returning (1) its materialized value, and (2) a new Sink that can be consume elements 'into' the pre-materialized one. - -## Signature - -## Description - - - -@@@div { .callout } - -@@@ - -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/repeat.md b/akka-docs/src/main/paradox/stream/reference/repeat.md deleted file mode 100644 index 0ab5fbb129..0000000000 --- a/akka-docs/src/main/paradox/stream/reference/repeat.md +++ /dev/null @@ -1,21 +0,0 @@ -# repeat - -repeat - -## Signature - -## Description - -Stream a single object repeatedly - - -@@@div { .callout } - -**emits** the same value repeatedly when there is demand - -**completes** never - -@@@ - -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/single.md b/akka-docs/src/main/paradox/stream/reference/single.md deleted file mode 100644 index c04d9a3e13..0000000000 --- a/akka-docs/src/main/paradox/stream/reference/single.md +++ /dev/null @@ -1,21 +0,0 @@ -# single - -single - -## Signature - -## Description - -Stream a single object - - -@@@div { .callout } - -**emits** the value once - -**completes** when the single value has been emitted - -@@@ - -## Example - diff --git a/akka-docs/src/main/paradox/stream/reference/toPath.md b/akka-docs/src/main/paradox/stream/reference/toPath.md deleted file mode 100644 index 9a0936b2b1..0000000000 --- a/akka-docs/src/main/paradox/stream/reference/toPath.md +++ /dev/null @@ -1,16 +0,0 @@ -# toPath - -Create a sink which will write incoming `ByteString` s to a given file path. - -## Signature - -## Description - - - -@@@div { .callout } - -@@@ - -## Example - diff --git a/akka-docs/src/main/paradox/stream/stages-overview.md b/akka-docs/src/main/paradox/stream/stages-overview.md deleted file mode 100644 index 5f86a33cdc..0000000000 --- a/akka-docs/src/main/paradox/stream/stages-overview.md +++ /dev/null @@ -1,2128 +0,0 @@ -# Overview of built-in stages and their semantics - -
- -## Source stages - -These built-in sources are available from @scala[`akka.stream.scaladsl.Source`] @java[`akka.stream.javadsl.Source`]: - ---------------------------------------------------------------- - -### fromIterator - -Stream the values from an `Iterator`, requesting the next value when there is demand. The iterator will be created anew -for each materialization, which is the reason the @scala[`method`] @java[`factory`] takes a @scala[`function`] @java[`Creator`] rather than an `Iterator` directly. - -If the iterator perform blocking operations, make sure to run it on a separate dispatcher. - -**emits** the next value returned from the iterator - -**completes** when the iterator reaches its end - ---------------------------------------------------------------- - -@@@ div { .group-scala } - -### apply - -Stream the values of an `immutable.Seq`. - -**emits** the next value of the seq - -**completes** when the last element of the seq has been emitted - -@@@ - -@@@ div { .group-java } - -### from - -Stream the values of an `Iterable`. Make sure the `Iterable` is immutable or at least not modified after being used -as a source. - -@@@ - ---------------------------------------------------------------- - -### single - -Stream a single object - -**emits** the value once - -**completes** when the single value has been emitted - ---------------------------------------------------------------- - -### repeat - -Stream a single object repeatedly - -**emits** the same value repeatedly when there is demand - -**completes** never - ---------------------------------------------------------------- - -### cycle - -Stream iterator in cycled manner. Internally new iterator is being created to cycle the one provided via argument meaning -when original iterator runs out of elements process will start all over again from the beginning of the iterator -provided by the evaluation of provided parameter. If method argument provides empty iterator stream will be terminated with -exception. - -**emits** the next value returned from cycled iterator - -**completes** never - ---------------------------------------------------------------- - -### tick - -A periodical repetition of an arbitrary object. Delay of first tick is specified -separately from interval of the following ticks. - -**emits** periodically, if there is downstream backpressure ticks are skipped - -**completes** never - ---------------------------------------------------------------- - -### fromFuture - -Send the single value of the `Future` when it completes and there is demand. -If the future fails the stream is failed with that exception. - -**emits** the future completes - -**completes** after the future has completed - ---------------------------------------------------------------- - -### fromCompletionStage - -Send the single value of the `CompletionStage` when it completes and there is demand. -If the future fails the stream is failed with that exception. - -**emits** the future completes - -**completes** after the future has completed - ---------------------------------------------------------------- - -### fromFutureSource - -Streams the elements of the given future source once it successfully completes. -If the future fails the stream is failed. - -**emits** the next value from the *future* source, once it has completed - -**completes** after the *future* source completes - ---------------------------------------------------------------- - -### fromSourceCompletionStage - -Streams the elements of an asynchronous source once its given *completion* stage completes. -If the *completion* fails the stream is failed with that exception. - -**emits** the next value from the asynchronous source, once its *completion stage* has completed - -**completes** after the asynchronous source completes - ---------------------------------------------------------------- - -### unfold - -Stream the result of a function as long as it returns a @scala[`Some`] @java[`Optional`], the value inside the option -consists of a @scala[tuple] @java[pair] where the first value is a state passed back into the next call to the function allowing -to pass a state. The first invocation of the provided fold function will receive the `zero` state. - -Can be used to implement many stateful sources without having to touch the more low level `GraphStage` API. - -**emits** when there is demand and the unfold function over the previous state returns non empty value - -**completes** when the unfold function returns an empty value - ---------------------------------------------------------------- - -### unfoldAsync - -Just like `unfold` but the fold function returns a @scala[`Future`] @java[`CompletionStage`] which will cause the source to -complete or emit when it completes. - -Can be used to implement many stateful sources without having to touch the more low level `GraphStage` API. - -**emits** when there is demand and unfold state returned future completes with some value - -**completes** when the @scala[future] @java[CompletionStage] returned by the unfold function completes with an empty value - ---------------------------------------------------------------- - -### empty - -Complete right away without ever emitting any elements. Useful when you have to provide a source to -an API but there are no elements to emit. - -**emits** never - -**completes** directly - ---------------------------------------------------------------- - -### maybe - -Materialize a @scala[`Promise[Option[T]]`] @java[`CompletionStage`] that if completed with a @scala[`Some[T]`] @java[`Optional`] -will emit that *T* and then complete the stream, or if completed with @scala[`None`] @java[`empty Optional`] complete the stream right away. - -**emits** when the returned promise is completed with some value - -**completes** after emitting some value, or directly if the promise is completed with no value - ---------------------------------------------------------------- - -### failed - -Fail directly with a user specified exception. - -**emits** never - -**completes** fails the stream directly with the given exception - ---------------------------------------------------------------- - -### lazily - -Defers creation and materialization of a `Source` until there is demand. - -**emits** depends on the wrapped `Source` - -**completes** depends on the wrapped `Source` - ---------------------------------------------------------------- - -### lazilyAsync - -Defers creation and materialization of a `CompletionStage` until there is demand. - -**emits** the future completes - -**completes** after the future has completed - ---------------------------------------------------------------- - -### actorRef - -Materialize an `ActorRef`, sending messages to it will emit them on the stream. The actor contain -a buffer but since communication is one way, there is no back pressure. Handling overflow is done by either dropping -elements or failing the stream, the strategy is chosen by the user. - -**emits** when there is demand and there are messages in the buffer or a message is sent to the actorref - -**completes** when the `ActorRef` is sent `akka.actor.Status.Success` or `PoisonPill` - ---------------------------------------------------------------- - -### range - -Emit each integer in a range, with an option to take bigger steps than 1. - -**emits** when there is demand, the next value - -**completes** when the end of the range has been reached - ---------------------------------------------------------------- - -### combine - -Combine several sources, using a given strategy such as merge or concat, into one source. - -**emits** when there is demand, but depending on the strategy - -**completes** when all sources has completed - ---------------------------------------------------------------- - -### unfoldResource - -Wrap any resource that can be opened, queried for next element (in a blocking way) and closed using three distinct functions into a source. - -**emits** when there is demand and read @scala[function] @java[method] returns value - -**completes** when read function returns `None` - ---------------------------------------------------------------- - -### unfoldResourceAsync - -Wrap any resource that can be opened, queried for next element (in a blocking way) and closed using three distinct functions into a source. -Functions return @scala[`Future`] @java[`CompletionStage`] to achieve asynchronous processing - -**emits** when there is demand and @scala[`Future`] @java[`CompletionStage`] from read function returns value - -**completes** when @scala[`Future`] @java[`CompletionStage`] from read function returns `None` - ---------------------------------------------------------------- - -### queue - -Materialize a `SourceQueue` onto which elements can be pushed for emitting from the source. The queue contains -a buffer, if elements are pushed onto the queue faster than the source is consumed the overflow will be handled with -a strategy specified by the user. Functionality for tracking when an element has been emitted is available through -`SourceQueue.offer`. - -**emits** when there is demand and the queue contains elements - -**completes** when downstream completes - ---------------------------------------------------------------- - -### asSubscriber - -Integration with Reactive Streams, materializes into a `org.reactivestreams.Subscriber`. - ---------------------------------------------------------------- - -### fromPublisher - -Integration with Reactive Streams, subscribes to a `org.reactivestreams.Publisher`. - ---------------------------------------------------------------- - -### zipN - -Combine the elements of multiple streams into a stream of sequences. - -**emits** when all of the inputs has an element available - -**completes** when any upstream completes - ---------------------------------------------------------------- - -### zipWithN - -Combine the elements of multiple streams into a stream of sequences using a combiner function. - -**emits** when all of the inputs has an element available - -**completes** when any upstream completes - ---------------------------------------------------------------- - -
- -## Sink stages - -These built-in sinks are available from @scala[`akka.stream.scaladsl.Sink`] @java[`akka.stream.javadsl.Sink`]: - ---------------------------------------------------------------- - -### head - -Materializes into a @scala[`Future`] @java[`CompletionStage`] which completes with the first value arriving, -after this the stream is canceled. If no element is emitted, the @scala[`Future`] @java[`CompletionStage`] is failed. - -**cancels** after receiving one element - -**backpressures** never - ---------------------------------------------------------------- - -### headOption - -Materializes into a @scala[`Future[Option[T]]`] @java[`CompletionStage>`] which completes with the first value arriving wrapped in @scala[`Some`] @java[`Optional`], -or @scala[a `None`] @java[an empty Optional] if the stream completes without any elements emitted. - -**cancels** after receiving one element - -**backpressures** never - ---------------------------------------------------------------- - -### last - -Materializes into a @scala[`Future`] @java[`CompletionStage`] which will complete with the last value emitted when the stream -completes. If the stream completes with no elements the @scala[`Future`] @java[`CompletionStage`] is failed. - -**cancels** never - -**backpressures** never - ---------------------------------------------------------------- - -### lastOption - -Materialize a @scala[`Future[Option[T]]`] @java[`CompletionStage>`] which completes with the last value -emitted wrapped in an @scala[`Some`] @java[`Optional`] when the stream completes. if the stream completes with no elements the `CompletionStage` is -completed with @scala[`None`] @java[an empty `Optional`]. - -**cancels** never - -**backpressures** never - ---------------------------------------------------------------- - -### ignore - -Consume all elements but discards them. Useful when a stream has to be consumed but there is no use to actually -do anything with the elements. - -**cancels** never - -**backpressures** never - ---------------------------------------------------------------- - -### cancelled - -Immediately cancel the stream - -**cancels** immediately - ---------------------------------------------------------------- - -### seq - -Collect values emitted from the stream into a collection, the collection is available through a @scala[`Future`] @java[`CompletionStage`] or -which completes when the stream completes. Note that the collection is bounded to @scala[`Int.MaxValue`] @java[`Integer.MAX_VALUE`], -if more element are emitted the sink will cancel the stream - -**cancels** If too many values are collected - ---------------------------------------------------------------- - -### foreach - -Invoke a given procedure for each element received. Note that it is not safe to mutate shared state from the procedure. - -The sink materializes into a @scala[`Future[Option[Done]]`] @java[`CompletionStage`] which completes when the -stream completes, or fails if the stream fails. - -Note that it is not safe to mutate state from the procedure. - -**cancels** never - -**backpressures** when the previous procedure invocation has not yet completed - ---------------------------------------------------------------- - -### foreachParallel - -Like `foreach` but allows up to `parallellism` procedure calls to happen in parallel. - -**cancels** never - -**backpressures** when the previous parallel procedure invocations has not yet completed - ---------------------------------------------------------------- - -### onComplete - -Invoke a callback when the stream has completed or failed. - -**cancels** never - -**backpressures** never - ---------------------------------------------------------------- - -### lazyInitAsync - -Creates a real `Sink` upon receiving the first element. Internal `Sink` will not be created if there are no elements, -because of completion or error. - -- If upstream completes before an element was received then the @scala[`Future`]@java[`CompletionStage`] is completed with @scala[`None`]@java[an empty `Optional`]. -- If upstream fails before an element was received, `sinkFactory` throws an exception, or materialization of the internal - sink fails then the @scala[`Future`]@java[`CompletionStage`] is completed with the exception. -- Otherwise the @scala[`Future`]@java[`CompletionStage`] is completed with the materialized value of the internal sink. - -**cancels** never - -**backpressures** when initialized and when created sink backpressures - ---------------------------------------------------------------- - -### queue - -Materialize a `SinkQueue` that can be pulled to trigger demand through the sink. The queue contains -a buffer in case stream emitting elements faster than queue pulling them. - -**cancels** when `SinkQueue.cancel` is called - -**backpressures** when buffer has some space - ---------------------------------------------------------------- - -### fold - -Fold over emitted element with a function, where each invocation will get the new element and the result from the -previous fold invocation. The first invocation will be provided the `zero` value. - -Materializes into a @scala[`Future`] @java[`CompletionStage`] that will complete with the last state when the stream has completed. - -This stage allows combining values into a result without a global mutable state by instead passing the state along -between invocations. - -**cancels** never - -**backpressures** when the previous fold function invocation has not yet completed - ---------------------------------------------------------------- - -### reduce - -Apply a reduction function on the incoming elements and pass the result to the next invocation. The first invocation -receives the two first elements of the flow. - -Materializes into a @scala[`Future`] @java[`CompletionStage`] that will be completed by the last result of the reduction function. - -**cancels** never - -**backpressures** when the previous reduction function invocation has not yet completed - ---------------------------------------------------------------- - -### combine - -Combine several sinks into one using a user specified strategy - -**cancels** depends on the strategy - -**backpressures** depends on the strategy - ---------------------------------------------------------------- - -### actorRef - -Send the elements from the stream to an `ActorRef`. No backpressure so care must be taken to not overflow the inbox. - -**cancels** when the actor terminates - -**backpressures** never - ---------------------------------------------------------------- - -### actorRefWithAck - -Send the elements from the stream to an `ActorRef` which must then acknowledge reception after completing a message, -to provide back pressure onto the sink. - -**cancels** when the actor terminates - -**backpressures** when the actor acknowledgement has not arrived - ---------------------------------------------------------------- - -### asPublisher - -Integration with Reactive Streams, materializes into a `org.reactivestreams.Publisher`. - ---------------------------------------------------------------- - -### fromSubscriber - -Integration with Reactive Streams, wraps a `org.reactivestreams.Subscriber` as a sink - ---------------------------------------------------------------- - -### preMaterialize - -Materializes this Sink, immediately returning (1) its materialized value, and (2) a new Sink that can be consume elements 'into' the pre-materialized one. - -Useful for when you need a materialized value of a Sink when handing it out to someone to materialize it for you. - ---------------------------------------------------------------- - -
- -## Additional Sink and Source converters - -Sources and sinks for integrating with `java.io.InputStream` and `java.io.OutputStream` can be found on -`StreamConverters`. As they are blocking APIs the implementations of these stages are run on a separate -dispatcher configured through the `akka.stream.blocking-io-dispatcher`. - -@@@ warning - -Be aware that `asInputStream` and `asOutputStream` materialize `InputStream` and `OutputStream` respectively as -blocking API implementation. They will block tread until data will be available from upstream. -Because of blocking nature these objects cannot be used in `mapMaterializeValue` section as it causes deadlock -of the stream materialization process. -For example, following snippet will fall with timeout exception: - -```scala -... -.toMat(StreamConverters.asInputStream().mapMaterializedValue { inputStream ⇒ - inputStream.read() // this could block forever - ... -}).run() -``` - -@@@ - ---------------------------------------------------------------- - -### fromOutputStream - -Create a sink that wraps an `OutputStream`. Takes a function that produces an `OutputStream`, when the sink is -materialized the function will be called and bytes sent to the sink will be written to the returned `OutputStream`. - -Materializes into a @scala[`Future`] @java[`CompletionStage`] which will complete with a `IOResult` when the stream -completes. - -Note that a flow can be materialized multiple times, so the function producing the `OutputStream` must be able -to handle multiple invocations. - -The `OutputStream` will be closed when the stream that flows into the `Sink` is completed, and the `Sink` -will cancel its inflow when the `OutputStream` is no longer writable. - ---------------------------------------------------------------- - -### asInputStream - -Create a sink which materializes into an `InputStream` that can be read to trigger demand through the sink. -Bytes emitted through the stream will be available for reading through the `InputStream` - -The `InputStream` will be ended when the stream flowing into this `Sink` completes, and the closing the -`InputStream` will cancel the inflow of this `Sink`. - ---------------------------------------------------------------- - -### fromInputStream - -Create a source that wraps an `InputStream`. Takes a function that produces an `InputStream`, when the source is -materialized the function will be called and bytes from the `InputStream` will be emitted into the stream. - -Materializes into a @scala[`Future`] @java[`CompletionStage`] which will complete with a `IOResult` when the stream -completes. - -Note that a flow can be materialized multiple times, so the function producing the `InputStream` must be able -to handle multiple invocations. - -The `InputStream` will be closed when the `Source` is canceled from its downstream, and reaching the end of the -`InputStream` will complete the `Source`. - ---------------------------------------------------------------- - -### asOutputStream - -Create a source that materializes into an `OutputStream`. When bytes are written to the `OutputStream` they -are emitted from the source. - -The `OutputStream` will no longer be writable when the `Source` has been canceled from its downstream, and -closing the `OutputStream` will complete the `Source`. - ---------------------------------------------------------------- - -### asJavaStream - -Create a sink which materializes into Java 8 `Stream` that can be run to trigger demand through the sink. -Elements emitted through the stream will be available for reading through the Java 8 `Stream`. - -The Java 8 `Stream` will be ended when the stream flowing into this `Sink` completes, and closing the Java -`Stream` will cancel the inflow of this `Sink`. Java `Stream` throws exception in case reactive stream failed. - -Be aware that Java `Stream` blocks current thread while waiting on next element from downstream. - ---------------------------------------------------------------- - -### fromJavaStream - -Create a source that wraps a Java 8 `Stream`. `Source` uses a stream iterator to get all its elements and send them -downstream on demand. - ---------------------------------------------------------------- - -### javaCollector - -Create a sink which materializes into a @scala[`Future`] @java[`CompletionStage`] which will be completed with a result of the Java 8 `Collector` -transformation and reduction operations. This allows usage of Java 8 streams transformations for reactive streams. -The `Collector` will trigger demand downstream. Elements emitted through the stream will be accumulated into a mutable -result container, optionally transformed into a final representation after all input elements have been processed. -The `Collector` can also do reduction at the end. Reduction processing is performed sequentially - -Note that a flow can be materialized multiple times, so the function producing the `Collector` must be able -to handle multiple invocations. - ---------------------------------------------------------------- - -### javaCollectorParallelUnordered - -Create a sink which materializes into a @scala[`Future`] @java[`CompletionStage`] which will be completed with a result of the Java 8 `Collector` -transformation and reduction operations. This allows usage of Java 8 streams transformations for reactive streams. -The `Collector` is triggering demand downstream. Elements emitted through the stream will be accumulated into a mutable -result container, optionally transformed into a final representation after all input elements have been processed. -The `Collector` can also do reduction at the end. Reduction processing is performed in parallel based on graph `Balance`. - -Note that a flow can be materialized multiple times, so the function producing the `Collector` must be able -to handle multiple invocations. - ---------------------------------------------------------------- - -
- -## File IO Sinks and Sources - -Sources and sinks for reading and writing files can be found on `FileIO`. - ---------------------------------------------------------------- - -### fromPath - -Emit the contents of a file, as `ByteString` s, materializes into a @scala[`Future`] @java[`CompletionStage`]` which will be completed with -a `IOResult` upon reaching the end of the file or if there is a failure. - ---------------------------------------------------------------- - -### toPath - -Create a sink which will write incoming `ByteString` s to a given file path. - ---------------------------------------------------------------- - -
- -## Flow stages - -All flows by default backpressure if the computation they encapsulate is not fast enough to keep up with the rate of -incoming elements from the preceding stage. There are differences though how the different stages handle when some of -their downstream stages backpressure them. - -Most stages stop and propagate the failure downstream as soon as any of their upstreams emit a failure. -This happens to ensure reliable teardown of streams and cleanup when failures happen. Failures are meant to -be to model unrecoverable conditions, therefore they are always eagerly propagated. -For in-band error handling of normal errors (dropping elements if a map fails for example) you should use the -supervision support, or explicitly wrap your element types in a proper container that can express error or success -states (for example `Try` in Scala). - -
- -## Simple processing stages - -These stages can transform the rate of incoming elements since there are stages that emit multiple elements for a -single input (e.g. `mapConcat`) or consume multiple elements before emitting one output (e.g. `filter`). -However, these rate transformations are data-driven, i.e. it is the incoming elements that define how the -rate is affected. This is in contrast with [detached stages](#backpressure-aware-stages) which can change their processing behavior -depending on being backpressured by downstream or not. - ---------------------------------------------------------------- - -### alsoTo - -Attaches the given `Sink` to this `Flow`, meaning that elements that pass through this `Flow` will also be sent to the `Sink`. - -**emits** when an element is available and demand exists both from the `Sink` and the downstream - -**backpressures** when downstream or `Sink` backpressures - -**completes** when upstream completes - -**cancels** when downstream or `Sink` cancels - ---------------------------------------------------------------- - -### map - -Transform each element in the stream by calling a mapping function with it and passing the returned value downstream. - -**emits** when the mapping function returns an element - -**backpressures** when downstream backpressures - -**completes** when upstream completes - ---------------------------------------------------------------- - -### mapConcat - -Transform each element into zero or more elements that are individually passed downstream. - -**emits** when the mapping function returns an element or there are still remaining elements from the previously calculated collection - -**backpressures** when downstream backpressures or there are still available elements from the previously calculated collection - -**completes** when upstream completes and all remaining elements has been emitted - ---------------------------------------------------------------- - -### statefulMapConcat - -Transform each element into zero or more elements that are individually passed downstream. The difference to `mapConcat` is that -the transformation function is created from a factory for every materialization of the flow. - -**emits** when the mapping function returns an element or there are still remaining elements from the previously calculated collection - -**backpressures** when downstream backpressures or there are still available elements from the previously calculated collection - -**completes** when upstream completes and all remaining elements has been emitted - ---------------------------------------------------------------- - -### filter - -Filter the incoming elements using a predicate. If the predicate returns true the element is passed downstream, if -it returns false the element is discarded. - -**emits** when the given predicate returns true for the element - -**backpressures** when the given predicate returns true for the element and downstream backpressures - -**completes** when upstream completes - ---------------------------------------------------------------- - -### filterNot - -Filter the incoming elements using a predicate. If the predicate returns false the element is passed downstream, if -it returns true the element is discarded. - -**emits** when the given predicate returns false for the element - -**backpressures** when the given predicate returns false for the element and downstream backpressures - -**completes** when upstream completes - ---------------------------------------------------------------- - -### collect - -Apply a partial function to each incoming element, if the partial function is defined for a value the returned -value is passed downstream. Can often replace `filter` followed by `map` to achieve the same in one single stage. - -**emits** when the provided partial function is defined for the element - -**backpressures** the partial function is defined for the element and downstream backpressures - -**completes** when upstream completes - ---------------------------------------------------------------- - -### collectType - -Transform this stream by testing the type of each of the elements on which the element is an instance of -the provided type as they pass through this processing step. Non-matching elements are filtered out. - -Adheres to the [[ActorAttributes.SupervisionStrategy]] attribute. - -'''Emits when''' the element is an instance of the provided type - -'''Backpressures when''' the element is an instance of the provided type and downstream backpressures - -'''Completes when''' upstream completes - -'''Cancels when''' downstream cancels - ---------------------------------------------------------------- - -### grouped - -Accumulate incoming events until the specified number of elements have been accumulated and then pass the collection of -elements downstream. - -**emits** when the specified number of elements has been accumulated or upstream completed - -**backpressures** when a group has been assembled and downstream backpressures - -**completes** when upstream completes - ---------------------------------------------------------------- - -### sliding - -Provide a sliding window over the incoming stream and pass the windows as groups of elements downstream. - -Note: the last window might be smaller than the requested size due to end of stream. - -**emits** the specified number of elements has been accumulated or upstream completed - -**backpressures** when a group has been assembled and downstream backpressures - -**completes** when upstream completes - ---------------------------------------------------------------- - -### scan - -Emit its current value which starts at `zero` and then applies the current and next value to the given function -emitting the next current value. - -Note that this means that scan emits one element downstream before and upstream elements will not be requested until -the second element is required from downstream. - -**emits** when the function scanning the element returns a new element - -**backpressures** when downstream backpressures - -**completes** when upstream completes - ---------------------------------------------------------------- - -### scanAsync - -Just like `scan` but receiving a function that results in a @scala[`Future`] @java[`CompletionStage`] to the next value. - -**emits** when the @scala[`Future`] @java[`CompletionStage`] resulting from the function scanning the element resolves to the next value - -**backpressures** when downstream backpressures - -**completes** when upstream completes and the last @scala[`Future`] @java[`CompletionStage`] is resolved - ---------------------------------------------------------------- - -### fold - -Start with current value `zero` and then apply the current and next value to the given function, when upstream -complete the current value is emitted downstream. - -**emits** when upstream completes - -**backpressures** when downstream backpressures - -**completes** when upstream completes - ---------------------------------------------------------------- - -### foldAsync - -Just like `fold` but receiving a function that results in a @scala[`Future`] @java[`CompletionStage`] to the next value. - -**emits** when upstream completes and the last @scala[`Future`] @java[`CompletionStage`] is resolved - -**backpressures** when downstream backpressures - -**completes** when upstream completes and the last @scala[`Future`] @java[`CompletionStage`] is resolved - ---------------------------------------------------------------- - -### reduce - -Start with first element and then apply the current and next value to the given function, when upstream -complete the current value is emitted downstream. Similar to `fold`. - -**emits** when upstream completes - -**backpressures** when downstream backpressures - -**completes** when upstream completes - ---------------------------------------------------------------- - -### drop - -Drop `n` elements and then pass any subsequent element downstream. - -**emits** when the specified number of elements has been dropped already - -**backpressures** when the specified number of elements has been dropped and downstream backpressures - -**completes** when upstream completes - ---------------------------------------------------------------- - -### take - -Pass `n` incoming elements downstream and then complete - -**emits** while the specified number of elements to take has not yet been reached - -**backpressures** when downstream backpressures - -**completes** when the defined number of elements has been taken or upstream completes - ---------------------------------------------------------------- - -### takeWhile - -Pass elements downstream as long as a predicate function return true for the element include the element -when the predicate first return false and then complete. - -**emits** while the predicate is true and until the first false result - -**backpressures** when downstream backpressures - -**completes** when predicate returned false or upstream completes - ---------------------------------------------------------------- - -### dropWhile - -Drop elements as long as a predicate function return true for the element - -**emits** when the predicate returned false and for all following stream elements - -**backpressures** predicate returned false and downstream backpressures - -**completes** when upstream completes - ---------------------------------------------------------------- - -### recover - -Allow sending of one last element downstream when a failure has happened upstream. - -Throwing an exception inside `recover` _will_ be logged on ERROR level automatically. - -**emits** when the element is available from the upstream or upstream is failed and pf returns an element - -**backpressures** when downstream backpressures, not when failure happened - -**completes** when upstream completes or upstream failed with exception pf can handle - ---------------------------------------------------------------- - -### recoverWith - -Allow switching to alternative Source when a failure has happened upstream. - -Throwing an exception inside `recoverWith` _will_ be logged on ERROR level automatically. - -**emits** the element is available from the upstream or upstream is failed and pf returns alternative Source - -**backpressures** downstream backpressures, after failure happened it backprssures to alternative Source - -**completes** upstream completes or upstream failed with exception pf can handle - ---------------------------------------------------------------- - -### recoverWithRetries - -RecoverWithRetries allows to switch to alternative Source on flow failure. It will stay in effect after -a failure has been recovered up to *attempts* number of times so that each time there is a failure -it is fed into the *pf* and a new Source may be materialized. Note that if you pass in 0, this won't -attempt to recover at all. A negative `attempts` number is interpreted as "infinite", which results in the exact same behavior as `recoverWith`. - -Since the underlying failure signal onError arrives out-of-band, it might jump over existing elements. -This stage can recover the failure signal, but not the skipped elements, which will be dropped. - -**emits** when element is available from the upstream or upstream is failed and element is available from alternative Source - -**backpressures** when downstream backpressures - -**completes** when upstream completes or upstream failed with exception pf can handle - ---------------------------------------------------------------- - -### mapError - -While similar to `recover` this stage can be used to transform an error signal to a different one *without* logging -it as an error in the process. So in that sense it is NOT exactly equivalent to `recover(t => throw t2)` since recover -would log the `t2` error. - -Since the underlying failure signal onError arrives out-of-band, it might jump over existing elements. -This stage can recover the failure signal, but not the skipped elements, which will be dropped. - -Similarily to `recover` throwing an exception inside `mapError` _will_ be logged on ERROR level automatically. - -**emits** when element is available from the upstream or upstream is failed and pf returns an element -**backpressures** when downstream backpressures -**completes** when upstream completes or upstream failed with exception pf can handle - ---------------------------------------------------------------- - -### detach - -Detach upstream demand from downstream demand without detaching the stream rates. - -**emits** when the upstream stage has emitted and there is demand - -**backpressures** when downstream backpressures - -**completes** when upstream completes - ---------------------------------------------------------------- - -### throttle - -Limit the throughput to a specific number of elements per time unit, or a specific total cost per time unit, where -a function has to be provided to calculate the individual cost of each element. - -**emits** when upstream emits an element and configured time per each element elapsed - -**backpressures** when downstream backpressures - -**completes** when upstream completes - ---------------------------------------------------------------- - -### intersperse - -Intersperse stream with provided element similar to `List.mkString`. It can inject start and end marker elements to stream. - -**emits** when upstream emits an element or before with the *start* element if provided - -**backpressures** when downstream backpressures - -**completes** when upstream completes - ---------------------------------------------------------------- - -### limit - -Limit number of element from upstream to given `max` number. - -**emits** when upstream emits and the number of emitted elements has not reached max - -**backpressures** when downstream backpressures - -**completes** when upstream completes and the number of emitted elements has not reached max - ---------------------------------------------------------------- - -### limitWeighted - -Ensure stream boundedness by evaluating the cost of incoming elements using a cost function. -Evaluated cost of each element defines how many elements will be allowed to travel downstream. - -**emits** when upstream emits and the number of emitted elements has not reached max - -**backpressures** when downstream backpressures - -**completes** when upstream completes and the number of emitted elements has not reached max - ---------------------------------------------------------------- - -### log - -Log elements flowing through the stream as well as completion and erroring. By default element and -completion signals are logged on debug level, and errors are logged on Error level. -This can be changed by calling @scala[`Attributes.logLevels(...)`] @java[`Attributes.createLogLevels(...)`] on the given Flow. - -**emits** when upstream emits - -**backpressures** when downstream backpressures - -**completes** when upstream completes - ---------------------------------------------------------------- - -### divertTo - -Each upstream element will either be diverted to the given sink, or the downstream consumer according to the predicate function applied to the element. - -**emits** when the chosen output stops backpressuring and there is an input element available - -**backpressures** when the chosen output backpressures - -**completes** when upstream completes and no output is pending - -**cancels** when any of the downstreams cancel - ---------------------------------------------------------------- - -### wireTap - -Attaches the given `Sink` to this `Flow` as a wire tap, meaning that elements that pass -through will also be sent to the wire-tap `Sink`, without the latter affecting the mainline flow. -If the wire-tap `Sink` backpressures, elements that would've been sent to it will be dropped instead. - -**emits** element is available and demand exists from the downstream; the element will -also be sent to the wire-tap `Sink` if there is demand. - -**backpressures** downstream backpressures - -**completes** upstream completes - -**cancels** downstream cancels - ---------------------------------------------------------------- - -### lazyInitAsync - -Creates a real `Flow` upon receiving the first element by calling relevant `flowFactory` given as an argument. -Internal `Flow` will not be created if there are no elements, because of completion or error. -The materialized value of the `Flow` will be the materialized value of the created internal flow. - -The materialized value of the `Flow` is a @scala[`Future[Option[M]]`]@java[`CompletionStage>`] that is -completed with @scala[`Some(mat)`]@java[`Optional.of(mat)`] when the internal flow gets materialized or with @scala[`None`] -@java[an empty optional] when there where no elements. If the flow materialization (including the call of the `flowFactory`) -fails then the future is completed with a failure. - -Adheres to the `ActorAttributes.SupervisionStrategy` attribute. - -**emits** when the internal flow is successfully created and it emits - -**backpressures** when the internal flow is successfully created and it backpressures - -**completes** when upstream completes and all elements have been emitted from the internal flow - -**completes** when upstream completes and all futures have been completed and all elements have been emitted - ---------------------------------------------------------------- - -### watch - -Watch a specific `ActorRef` and signal a failure downstream once the actor terminates. -The signaled failure will be an @java[@javadoc:[WatchedActorTerminatedException](akka.stream.WatchedActorTerminatedException)] -@scala[@scaladoc[WatchedActorTerminatedException](akka.stream.WatchedActorTerminatedException)]. - -**emits** when upstream emits - -**backpressures** when downstream backpressures - -**completes** when upstream completes - ---------------------------------------------------------------- - -### ask - -Specialized stage implementing the @scala[@extref[ask](github:akka-actor/src/main/scala/akka/pattern/AskSupport.scala)]@java[@extref[ask](github:akka-actor/src/main/scala/akka/pattern/Patterns.scala)] pattern for inter-op with untyped actors. - -The stream will be failed using an an @java[@javadoc:[WatchedActorTerminatedException](akka.stream.WatchedActorTerminatedException)] -@scala[@scaladoc[WatchedActorTerminatedException](akka.stream.WatchedActorTerminatedException)] if the target actor terminates, -or with an @java[@javadoc:[WatchedActorTerminatedException](akka.pattern.AskTimeoutException)] @scala[@scaladoc[WatchedActorTerminatedException](akka.pattern.AskTimeoutException)] if any of the asks times out. - -**emits** when the futures (in submission order) created by the ask pattern internally are completed - -**backpressures** when the number of futures reaches the configured parallelism and the downstream backpressures - -**fails** when the passed in actor terminates, or a timeout is exceeded in any of the asks performed - -**completes** when upstream completes and all futures have been completed and all elements have been emitted - - ---------------------------------------------------------------- - -
- -## Flow stages composed of Sinks and Sources - ---------------------------------------------------------------- - -### Flow.fromSinkAndSource - -Creates a `Flow` from a `Sink` and a `Source` where the Flow's input will be sent to the `Sink` -and the `Flow` 's output will come from the Source. - -Note that termination events, like completion and cancelation is not automatically propagated through to the "other-side" -of the such-composed Flow. Use `Flow.fromSinkAndSourceCoupled` if you want to couple termination of both of the ends, -for example most useful in handling websocket connections. - ---------------------------------------------------------------- - -### Flow.fromSinkAndSourceCoupled - -Allows coupling termination (cancellation, completion, erroring) of Sinks and Sources while creating a Flow between them. -Similar to `Flow.fromSinkAndSource` however couples the termination of these two stages. - -E.g. if the emitted `Flow` gets a cancellation, the `Source` of course is cancelled, -however the Sink will also be completed. The table below illustrates the effects in detail: - -| Returned Flow | Sink (in) | Source (out) | -|-------------------------------------------------|-----------------------------|---------------------------------| -| cause: upstream (sink-side) receives completion | effect: receives completion | effect: receives cancel | -| cause: upstream (sink-side) receives error | effect: receives error | effect: receives cancel | -| cause: downstream (source-side) receives cancel | effect: completes | effect: receives cancel | -| effect: cancels upstream, completes downstream | effect: completes | cause: signals complete | -| effect: cancels upstream, errors downstream | effect: receives error | cause: signals error or throws | -| effect: cancels upstream, completes downstream | cause: cancels | effect: receives cancel | - -The order in which the *in* and *out* sides receive their respective completion signals is not defined, do not rely on its ordering. - ---------------------------------------------------------------- - -
- -## Asynchronous processing stages - -These stages encapsulate an asynchronous computation, properly handling backpressure while taking care of the asynchronous -operation at the same time (usually handling the completion of a @scala[`Future`] @java[`CompletionStage`]). - ---------------------------------------------------------------- - -### mapAsync - -Pass incoming elements to a function that return a @scala[`Future`] @java[`CompletionStage`] result. When the @scala[`Future`] @java[`CompletionStage`] arrives the result is passed -downstream. Up to `n` elements can be processed concurrently, but regardless of their completion time the incoming -order will be kept when results complete. For use cases where order does not matter `mapAsyncUnordered` can be used. - -If a @scala[`Future`] @java[`CompletionStage`] fails, the stream also fails (unless a different supervision strategy is applied) - -**emits** when the @scala[`Future`] @java[`CompletionStage`] returned by the provided function finishes for the next element in sequence - -**backpressures** when the number of @scala[`Future` s] @java[`CompletionStage` s] reaches the configured parallelism and the downstream backpressures - -**completes** when upstream completes and all @scala[`Future` s] @java[`CompletionStage` s] has been completed and all elements has been emitted - ---------------------------------------------------------------- - -### mapAsyncUnordered - -Like `mapAsync` but @scala[`Future`] @java[`CompletionStage`] results are passed downstream as they arrive regardless of the order of the elements -that triggered them. - -If a @scala[`Future`] @java[`CompletionStage`] fails, the stream also fails (unless a different supervision strategy is applied) - -**emits** any of the @scala[`Future` s] @java[`CompletionStage` s] returned by the provided function complete - -**backpressures** when the number of @scala[`Future` s] @java[`CompletionStage` s] reaches the configured parallelism and the downstream backpressures - -**completes** upstream completes and all @scala[`Future` s] @java[`CompletionStage` s] has been completed and all elements has been emitted - ---------------------------------------------------------------- - -### ask - -Use the `ask` pattern to send a request-reply message to the target `ref` actor. -If any of the asks times out it will fail the stream with a [[akka.pattern.AskTimeoutException]]. - -The `mapTo` class parameter is used to cast the incoming responses to the expected response type. - -Similar to the plain ask pattern, the target actor is allowed to reply with `akka.util.Status`. -An `akka.util.Status#Failure` will cause the stage to fail with the cause carried in the `Failure` message. - -Adheres to the [[ActorAttributes.SupervisionStrategy]] attribute. - -**emits** when the ask @scala[`Future`] @java[`CompletionStage`] returned by the provided function finishes for the next element in sequence - - -**backpressures** when the number of ask @scala[`Future` s] @java[`CompletionStage` s] reaches the configured parallelism and the downstream backpressures - -**completes** when upstream completes and all ask @scala[`Future` s] @java[`CompletionStage` s] has been completed and all elements has been emitted - - ---------------------------------------------------------------- - -
- -## Timer driven stages - -These stages process elements using timers, delaying, dropping or grouping elements for certain time durations. - ---------------------------------------------------------------- - -### takeWithin - -Pass elements downstream within a timeout and then complete. - -**emits** when an upstream element arrives - -**backpressures** downstream backpressures - -**completes** upstream completes or timer fires - ---------------------------------------------------------------- - -### dropWithin - -Drop elements until a timeout has fired - -**emits** after the timer fired and a new upstream element arrives - -**backpressures** when downstream backpressures - -**completes** upstream completes - ---------------------------------------------------------------- - -### groupedWithin - -Chunk up this stream into groups of elements received within a time window, or limited by the number of the elements, -whatever happens first. Empty groups will not be emitted if no elements are received from upstream. -The last group before end-of-stream will contain the buffered elements since the previously emitted group. - -**emits** when the configured time elapses since the last group has been emitted, -but not if no elements has been grouped (i.e: no empty groups), or when limit has been reached. - -**backpressures** downstream backpressures, and there are *n+1* buffered elements - -**completes** when upstream completes - ---------------------------------------------------------------- - -### groupedWeightedWithin - -Chunk up this stream into groups of elements received within a time window, or limited by the weight of the elements, -whatever happens first. Empty groups will not be emitted if no elements are received from upstream. -The last group before end-of-stream will contain the buffered elements since the previously emitted group. - -**emits** when the configured time elapses since the last group has been emitted, -but not if no elements has been grouped (i.e: no empty groups), or when weight limit has been reached. - -**backpressures** downstream backpressures, and buffered group (+ pending element) weighs more than *maxWeight* - -**completes** when upstream completes - ---------------------------------------------------------------- - -### initialDelay - -Delay the initial element by a user specified duration from stream materialization. - -**emits** upstream emits an element if the initial delay already elapsed - -**backpressures** downstream backpressures or initial delay not yet elapsed - -**completes** when upstream completes - ---------------------------------------------------------------- - -### delay - -Delay every element passed through with a specific duration. - -**emits** there is a pending element in the buffer and configured time for this element elapsed - -**backpressures** differs, depends on `OverflowStrategy` set - -**completes** when upstream completes and buffered elements has been drained - - ---------------------------------------------------------------- - -
- -## Backpressure aware stages - -These stages are aware of the backpressure provided by their downstreams and able to adapt their behavior to that signal. - ---------------------------------------------------------------- - -### conflate - -Allow for a slower downstream by passing incoming elements and a summary into an aggregate function as long as -there is backpressure. The summary value must be of the same type as the incoming elements, for example the sum or -average of incoming numbers, if aggregation should lead to a different type `conflateWithSeed` can be used: - -**emits** when downstream stops backpressuring and there is a conflated element available - -**backpressures** when the aggregate function cannot keep up with incoming elements - -**completes** when upstream completes - ---------------------------------------------------------------- - -### conflateWithSeed - -Allow for a slower downstream by passing incoming elements and a summary into an aggregate function as long as there -is backpressure. When backpressure starts or there is no backpressure element is passed into a `seed` function to -transform it to the summary type. - -**emits** when downstream stops backpressuring and there is a conflated element available - -**backpressures** when the aggregate or seed functions cannot keep up with incoming elements - -**completes** when upstream completes - ---------------------------------------------------------------- - -### batch - -Allow for a slower downstream by passing incoming elements and a summary into an aggregate function as long as there -is backpressure and a maximum number of batched elements is not yet reached. When the maximum number is reached and -downstream still backpressures batch will also backpressure. - -When backpressure starts or there is no backpressure element is passed into a `seed` function to transform it -to the summary type. - -Will eagerly pull elements, this behavior may result in a single pending (i.e. buffered) element which cannot be -aggregated to the batched value. - -**emits** when downstream stops backpressuring and there is a batched element available - -**backpressures** when batched elements reached the max limit of allowed batched elements & downstream backpressures - -**completes** when upstream completes and a "possibly pending" element was drained - ---------------------------------------------------------------- - -### batchWeighted - -Allow for a slower downstream by passing incoming elements and a summary into an aggregate function as long as there -is backpressure and a maximum weight batched elements is not yet reached. The weight of each element is determined by -applying `costFn`. When the maximum total weight is reached and downstream still backpressures batch will also -backpressure. - -Will eagerly pull elements, this behavior may result in a single pending (i.e. buffered) element which cannot be -aggregated to the batched value. - -**emits** downstream stops backpressuring and there is a batched element available - -**backpressures** batched elements reached the max weight limit of allowed batched elements & downstream backpressures - -**completes** upstream completes and a "possibly pending" element was drained - ---------------------------------------------------------------- - -### extrapolate - -Allow for a faster downstream by expanding the last emitted element to an `Iterator`. For example, an -`Iterator.continually(element)` will cause `extrapolate` to keep repeating the last emitted element. - -All original elements are always emitted unchanged - the `Iterator` is only used whenever there is downstream - demand before upstream emits a new element. - -Includes an optional `initial` argument to prevent blocking the entire stream when there are multiple producers. - -See @ref:[Understanding extrapolate and expand](stream-rate.md#understanding-extrapolate-and-expand) for more information -and examples. - -**emits** when downstream stops backpressuring - -**backpressures** when downstream backpressures - -**completes** when upstream completes - ---------------------------------------------------------------- - -### expand - -Like `extrapolate`, but does not have the `initial` argument, and the `Iterator` is also used in lieu of the original -element, allowing for it to be rewritten and/or filtered. - -See @ref:[Understanding extrapolate and expand](stream-rate.md#understanding-extrapolate-and-expand) for more information -and examples. - -**emits** when downstream stops backpressuring - -**backpressures** when downstream backpressures - -**completes** when upstream completes - ---------------------------------------------------------------- - -### buffer (Backpressure) - -Allow for a temporarily faster upstream events by buffering `size` elements. When the buffer is full backpressure -is applied. - -**emits** when downstream stops backpressuring and there is a pending element in the buffer - -**backpressures** when buffer is full - -**completes** when upstream completes and buffered elements has been drained - ---------------------------------------------------------------- - -### buffer (Drop) - -Allow for a temporarily faster upstream events by buffering `size` elements. When the buffer is full elements are -dropped according to the specified `OverflowStrategy`: - - * `dropHead` drops the oldest element in the buffer to make space for the new element - * `dropTail` drops the youngest element in the buffer to make space for the new element - * `dropBuffer` drops the entire buffer and buffers the new element - * `dropNew` drops the new element - -**emits** when downstream stops backpressuring and there is a pending element in the buffer - -**backpressures** never (when dropping cannot keep up with incoming elements) - -**completes** upstream completes and buffered elements has been drained - ---------------------------------------------------------------- - -### buffer (Fail) - -Allow for a temporarily faster upstream events by buffering `size` elements. When the buffer is full the stage fails -the flow with a `BufferOverflowException`. - -**emits** when downstream stops backpressuring and there is a pending element in the buffer - -**backpressures** never, fails the stream instead of backpressuring when buffer is full - -**completes** when upstream completes and buffered elements has been drained - ---------------------------------------------------------------- - -
- -## Nesting and flattening stages - - -These stages either take a stream and turn it into a stream of streams (nesting) or they take a stream that contains -nested streams and turn them into a stream of elements instead (flattening). - -See the [Substreams](stream-substream.md) page for more detail and code samples. - ---------------------------------------------------------------- - -### prefixAndTail - -Take up to *n* elements from the stream (less than *n* only if the upstream completes before emitting *n* elements) -and returns a pair containing a strict sequence of the taken element and a stream representing the remaining elements. - -**emits** when the configured number of prefix elements are available. Emits this prefix, and the rest as a substream - -**backpressures** when downstream backpressures or substream backpressures - -**completes** when prefix elements has been consumed and substream has been consumed - ---------------------------------------------------------------- - -### groupBy - -Demultiplex the incoming stream into separate output streams. - -**emits** an element for which the grouping function returns a group that has not yet been created. Emits the new group -there is an element pending for a group whose substream backpressures - -**completes** when upstream completes (Until the end of stream it is not possible to know whether new substreams will be needed or not) - ---------------------------------------------------------------- - -### splitWhen - -Split off elements into a new substream whenever a predicate function return `true`. - -**emits** an element for which the provided predicate is true, opening and emitting a new substream for subsequent elements - -**backpressures** when there is an element pending for the next substream, but the previous is not fully consumed yet, or the substream backpressures - -**completes** when upstream completes (Until the end of stream it is not possible to know whether new substreams will be needed or not) - ---------------------------------------------------------------- - -### splitAfter - -End the current substream whenever a predicate returns `true`, starting a new substream for the next element. - -**emits** when an element passes through. When the provided predicate is true it emits the element * and opens a new substream for subsequent element - -**backpressures** when there is an element pending for the next substream, but the previous is not fully consumed yet, or the substream backpressures - -**completes** when upstream completes (Until the end of stream it is not possible to know whether new substreams will be needed or not) - ---------------------------------------------------------------- - -### flatMapConcat - -Transform each input element into a `Source` whose elements are then flattened into the output stream through -concatenation. This means each source is fully consumed before consumption of the next source starts. - -**emits** when the current consumed substream has an element available - -**backpressures** when downstream backpressures - -**completes** when upstream completes and all consumed substreams complete - ---------------------------------------------------------------- - -### flatMapMerge - -Transform each input element into a `Source` whose elements are then flattened into the output stream through -merging. The maximum number of merged sources has to be specified. - -**emits** when one of the currently consumed substreams has an element available - -**backpressures** when downstream backpressures - -**completes** when upstream completes and all consumed substreams complete - ---------------------------------------------------------------- - -
- -## Time aware stages - -Those stages operate taking time into consideration. - ---------------------------------------------------------------- - -### initialTimeout - -If the first element has not passed through this stage before the provided timeout, the stream is failed -with a `TimeoutException`. - -**emits** when upstream emits an element - -**backpressures** when downstream backpressures - -**completes** when upstream completes or fails if timeout elapses before first element arrives - -**cancels** when downstream cancels - ---------------------------------------------------------------- - -### completionTimeout - -If the completion of the stream does not happen until the provided timeout, the stream is failed -with a `TimeoutException`. - -**emits** when upstream emits an element - -**backpressures** when downstream backpressures - -**completes** when upstream completes or fails if timeout elapses before upstream completes - -**cancels** when downstream cancels - ---------------------------------------------------------------- - -### idleTimeout - -If the time between two processed elements exceeds the provided timeout, the stream is failed -with a `TimeoutException`. The timeout is checked periodically, so the resolution of the -check is one period (equals to timeout value). - -**emits** when upstream emits an element - -**backpressures** when downstream backpressures - -**completes** when upstream completes or fails if timeout elapses between two emitted elements - -**cancels** when downstream cancels - ---------------------------------------------------------------- - -### backpressureTimeout - -If the time between the emission of an element and the following downstream demand exceeds the provided timeout, -the stream is failed with a `TimeoutException`. The timeout is checked periodically, so the resolution of the -check is one period (equals to timeout value). - -**emits** when upstream emits an element - -**backpressures** when downstream backpressures - -**completes** when upstream completes or fails if timeout elapses between element emission and downstream demand. - -**cancels** when downstream cancels - ---------------------------------------------------------------- - -### keepAlive - -Injects additional (configured) elements if upstream does not emit for a configured amount of time. - -**emits** when upstream emits an element or if the upstream was idle for the configured period - -**backpressures** when downstream backpressures - -**completes** when upstream completes - -**cancels** when downstream cancels - ---------------------------------------------------------------- - -### initialDelay - -Delays the initial element by the specified duration. - -**emits** when upstream emits an element if the initial delay is already elapsed - -**backpressures** when downstream backpressures or initial delay is not yet elapsed - -**completes** when upstream completes - -**cancels** when downstream cancels - ---------------------------------------------------------------- - -
- -## Fan-in stages - -These stages take multiple streams as their input and provide a single output combining the elements from all of -the inputs in different ways. - ---------------------------------------------------------------- - -### merge - -Merge multiple sources. Picks elements randomly if all sources has elements ready. - -**emits** when one of the inputs has an element available - -**backpressures** when downstream backpressures - -**completes** when all upstreams complete (This behavior is changeable to completing when any upstream completes by setting `eagerComplete=true`.) - ---------------------------------------------------------------- - -### mergeSorted - -Merge multiple sources. Waits for one element to be ready from each input stream and emits the -smallest element. - -**emits** when all of the inputs have an element available - -**backpressures** when downstream backpressures - -**completes** when all upstreams complete - ---------------------------------------------------------------- - -### mergePreferred - -Merge multiple sources. Prefer one source if all sources has elements ready. - -**emits** when one of the inputs has an element available, preferring a defined input if multiple have elements available - -**backpressures** when downstream backpressures - -**completes** when all upstreams complete (This behavior is changeable to completing when any upstream completes by setting `eagerComplete=true`.) - ---------------------------------------------------------------- - -### mergePrioritized - -Merge multiple sources. Prefer sources depending on priorities if all sources has elements ready. If a subset of all -sources has elements ready the relative priorities for those sources are used to prioritise. - -**emits** when one of the inputs has an element available, preferring inputs based on their priorities if multiple have elements available - -**backpressures** when downstream backpressures - -**completes** when all upstreams complete (This behavior is changeable to completing when any upstream completes by setting `eagerComplete=true`.) - ---------------------------------------------------------------- - -### zip - -Combines elements from each of multiple sources into @scala[tuples] @java[*Pair*] and passes the @scala[tuples] @java[pairs] downstream. - -**emits** when all of the inputs have an element available - -**backpressures** when downstream backpressures - -**completes** when any upstream completes - ---------------------------------------------------------------- - -### zipWith - -Combines elements from multiple sources through a `combine` function and passes the -returned value downstream. - -**emits** when all of the inputs have an element available - -**backpressures** when downstream backpressures - -**completes** when any upstream completes - ---------------------------------------------------------------- - -### zipWithIndex - -Zips elements of current flow with its indices. - -**emits** upstream emits an element and is paired with their index - -**backpressures** when downstream backpressures - -**completes** when upstream completes - ---------------------------------------------------------------- - -### concat - -After completion of the original upstream the elements of the given source will be emitted. - -**emits** when the current stream has an element available; if the current input completes, it tries the next one - -**backpressures** when downstream backpressures - -**completes** when all upstreams complete - ---------------------------------------------------------------- - -### ++ - -Just a shorthand for concat - -**emits** when the current stream has an element available; if the current input completes, it tries the next one - -**backpressures** when downstream backpressures - -**completes** when all upstreams complete - ---------------------------------------------------------------- - -### prepend - -Prepends the given source to the flow, consuming it until completion before the original source is consumed. - -If materialized values needs to be collected `prependMat` is available. - -**emits** when the given stream has an element available; if the given input completes, it tries the current one - -**backpressures** when downstream backpressures - -**completes** when all upstreams complete - ---------------------------------------------------------------- - -### orElse - -If the primary source completes without emitting any elements, the elements from the secondary source -are emitted. If the primary source emits any elements the secondary source is cancelled. - -Note that both sources are materialized directly and the secondary source is backpressured until it becomes -the source of elements or is cancelled. - -Signal errors downstream, regardless which of the two sources emitted the error. - -**emits** when an element is available from first stream or first stream closed without emitting any elements and an element -is available from the second stream - -**backpressures** when downstream backpressures - -**completes** the primary stream completes after emitting at least one element, when the primary stream completes -without emitting and the secondary stream already has completed or when the secondary stream completes - ---------------------------------------------------------------- - -### interleave - -Emits a specifiable number of elements from the original source, then from the provided source and repeats. If one -source completes the rest of the other stream will be emitted. - -**emits** when element is available from the currently consumed upstream - -**backpressures** when upstream backpressures - -**completes** when both upstreams have completed - ---------------------------------------------------------------- - -
- -## Fan-out stages - -These have one input and multiple outputs. They might route the elements between different outputs, or emit elements on -multiple outputs at the same time. - ---------------------------------------------------------------- - -### unzip - -Takes a stream of two element tuples and unzips the two elements ino two different downstreams. - -**emits** when all of the outputs stops backpressuring and there is an input element available - -**backpressures** when any of the outputs backpressures - -**completes** when upstream completes - ---------------------------------------------------------------- - -### unzipWith - -Splits each element of input into multiple downstreams using a function - -**emits** when all of the outputs stops backpressuring and there is an input element available - -**backpressures** when any of the outputs backpressures - -**completes** when upstream completes - ---------------------------------------------------------------- - -### broadcast - -Emit each incoming element each of `n` outputs. - -**emits** when all of the outputs stops backpressuring and there is an input element available - -**backpressures** when any of the outputs backpressures - -**completes** when upstream completes - -**cancels** depends on the `eagerCancel` flag. If it is true, when any downstream cancels, if false, when all downstreams cancel. - ---------------------------------------------------------------- - -### balance - -Fan-out the stream to several streams. Each upstream element is emitted to the first available downstream consumer. - -**emits** when any of the outputs stops backpressuring; emits the element to the first available output - -**backpressures** when all of the outputs backpressure - -**completes** when upstream completes - -**cancels** depends on the `eagerCancel` flag. If it is true, when any downstream cancels, if false, when all downstreams cancel. - ---------------------------------------------------------------- - -### partition - -Fan-out the stream to several streams. Each upstream element is emitted to one downstream consumer according to the -partitioner function applied to the element. - -**emits** when the chosen output stops backpressuring and there is an input element available - -**backpressures** when the chosen output backpressures - -**completes** when upstream completes and no output is pending - -**cancels** depends on the `eagerCancel` flag. If it is true, when any downstream cancels, if false, when all downstreams cancel. - ---------------------------------------------------------------- - -
- -## Watching status stages - ---------------------------------------------------------------- - -### watchTermination - -Materializes to a @scala[`Future`] @java[`CompletionStage`] that will be completed with Done or failed depending whether the upstream of the stage has been completed or failed. -The stage otherwise passes through elements unchanged. - -**emits** when input has an element available - -**backpressures** when output backpressures - -**completes** when upstream completes - ---------------------------------------------------------------- - -### monitor - -Materializes to a `FlowMonitor` that monitors messages flowing through or completion of the stage. The stage otherwise -passes through elements unchanged. Note that the `FlowMonitor` inserts a memory barrier every time it processes an -event, and may therefore affect performance. - -**emits** when upstream emits an element - -**backpressures** when downstream **backpressures** - -**completes** when upstream completes - ---------------------------------------------------------------- - -@@@ index - -* [fromIterator](reference/fromIterator.md) -* [apply](reference/apply.md) -* [single](reference/single.md) -* [repeat](reference/repeat.md) -* [cycle](reference/cycle.md) -* [tick](reference/tick.md) -* [fromFuture](reference/fromFuture.md) -* [fromCompletionStage](reference/fromCompletionStage.md) -* [fromFutureSource](reference/fromFutureSource.md) -* [fromSourceCompletionStage](reference/fromSourceCompletionStage.md) -* [unfold](reference/unfold.md) -* [unfoldAsync](reference/unfoldAsync.md) -* [empty](reference/empty.md) -* [maybe](reference/maybe.md) -* [failed](reference/failed.md) -* [lazily](reference/lazily.md) -* [lazilyAsync](reference/lazilyAsync.md) -* [actorRef](reference/actorRef.md) -* [range](reference/range.md) -* [combine](reference/combine.md) -* [unfoldResource](reference/unfoldResource.md) -* [unfoldResourceAsync](reference/unfoldResourceAsync.md) -* [queue](reference/queue.md) -* [asSubscriber](reference/asSubscriber.md) -* [fromPublisher](reference/fromPublisher.md) -* [zipN](reference/zipN.md) -* [zipWithN](reference/zipWithN.md) -* [head](reference/head.md) -* [headOption](reference/headOption.md) -* [last](reference/last.md) -* [lastOption](reference/lastOption.md) -* [ignore](reference/ignore.md) -* [cancelled](reference/cancelled.md) -* [seq](reference/seq.md) -* [foreach](reference/foreach.md) -* [foreachParallel](reference/foreachParallel.md) -* [onComplete](reference/onComplete.md) -* [lazyInitAsync](reference/lazyInitAsync.md) -* [queue](reference/queue.md) -* [fold](reference/fold.md) -* [reduce](reference/reduce.md) -* [combine](reference/combine.md) -* [actorRef](reference/actorRef.md) -* [actorRefWithAck](reference/actorRefWithAck.md) -* [asPublisher](reference/asPublisher.md) -* [fromSubscriber](reference/fromSubscriber.md) -* [preMaterialize](reference/preMaterialize.md) -* [fromOutputStream](reference/fromOutputStream.md) -* [asInputStream](reference/asInputStream.md) -* [fromInputStream](reference/fromInputStream.md) -* [asOutputStream](reference/asOutputStream.md) -* [asJavaStream](reference/asJavaStream.md) -* [fromJavaStream](reference/fromJavaStream.md) -* [javaCollector](reference/javaCollector.md) -* [javaCollectorParallelUnordered](reference/javaCollectorParallelUnordered.md) -* [fromPath](reference/fromPath.md) -* [toPath](reference/toPath.md) -* [alsoTo](reference/alsoTo.md) -* [map](reference/map.md) -* [mapConcat](reference/mapConcat.md) -* [statefulMapConcat](reference/statefulMapConcat.md) -* [filter](reference/filter.md) -* [filterNot](reference/filterNot.md) -* [collect](reference/collect.md) -* [collectType ](reference/collectType.md) -* [grouped](reference/grouped.md) -* [sliding](reference/sliding.md) -* [scan](reference/scan.md) -* [scanAsync](reference/scanAsync.md) -* [fold](reference/fold.md) -* [foldAsync](reference/foldAsync.md) -* [reduce](reference/reduce.md) -* [drop](reference/drop.md) -* [take](reference/take.md) -* [takeWhile](reference/takeWhile.md) -* [dropWhile](reference/dropWhile.md) -* [recover](reference/recover.md) -* [recoverWith](reference/recoverWith.md) -* [recoverWithRetries](reference/recoverWithRetries.md) -* [mapError](reference/mapError.md) -* [detach](reference/detach.md) -* [throttle](reference/throttle.md) -* [intersperse](reference/intersperse.md) -* [limit](reference/limit.md) -* [limitWeighted](reference/limitWeighted.md) -* [log](reference/log.md) -* [divertTo](reference/divertTo.md) -* [wireTap](reference/wireTap.md) -* [lazyInitAsync](reference/lazyInitAsync.md) -* [watch](reference/watch.md) -* [ask](reference/ask.md) -* [Flow.fromSinkAndSource](reference/Flow.fromSinkAndSource.md) -* [Flow.fromSinkAndSourceCoupled](reference/Flow.fromSinkAndSourceCoupled.md) -* [mapAsync](reference/mapAsync.md) -* [mapAsyncUnordered](reference/mapAsyncUnordered.md) -* [ask](reference/ask.md) -* [takeWithin](reference/takeWithin.md) -* [dropWithin](reference/dropWithin.md) -* [groupedWithin](reference/groupedWithin.md) -* [groupedWeightedWithin](reference/groupedWeightedWithin.md) -* [initialDelay](reference/initialDelay.md) -* [delay](reference/delay.md) -* [conflate](reference/conflate.md) -* [conflateWithSeed](reference/conflateWithSeed.md) -* [batch](reference/batch.md) -* [batchWeighted](reference/batchWeighted.md) -* [extrapolate](reference/extrapolate.md) -* [expand](reference/expand.md) -* [buffer](reference/buffer.md) -* [prefixAndTail](reference/prefixAndTail.md) -* [groupBy](reference/groupBy.md) -* [splitWhen](reference/splitWhen.md) -* [splitAfter](reference/splitAfter.md) -* [flatMapConcat](reference/flatMapConcat.md) -* [flatMapMerge](reference/flatMapMerge.md) -* [initialTimeout](reference/initialTimeout.md) -* [completionTimeout](reference/completionTimeout.md) -* [idleTimeout](reference/idleTimeout.md) -* [backpressureTimeout](reference/backpressureTimeout.md) -* [keepAlive](reference/keepAlive.md) -* [initialDelay](reference/initialDelay.md) -* [merge](reference/merge.md) -* [mergeSorted](reference/mergeSorted.md) -* [mergePreferred](reference/mergePreferred.md) -* [mergePrioritized](reference/mergePrioritized.md) -* [zip](reference/zip.md) -* [zipWith](reference/zipWith.md) -* [zipWithIndex](reference/zipWithIndex.md) -* [concat](reference/concat.md) -* [prepend](reference/prepend.md) -* [orElse](reference/orElse.md) -* [interleave](reference/interleave.md) -* [unzip](reference/unzip.md) -* [unzipWith](reference/unzipWith.md) -* [broadcast](reference/broadcast.md) -* [balance](reference/balance.md) -* [partition](reference/partition.md) -* [watchTermination](reference/watchTermination.md) -* [monitor](reference/monitor.md) - -@@@ diff --git a/akka-docs/src/main/paradox/stream/stream-cookbook.md b/akka-docs/src/main/paradox/stream/stream-cookbook.md index 4f551ae6a8..a8b47a98ae 100644 --- a/akka-docs/src/main/paradox/stream/stream-cookbook.md +++ b/akka-docs/src/main/paradox/stream/stream-cookbook.md @@ -11,7 +11,7 @@ This part also serves as supplementary material for the main body of documentati open while reading the manual and look for examples demonstrating various streaming concepts as they appear in the main body of documentation. -If you need a quick reference of the available processing stages used in the recipes see @ref:[stages overview](stages-overview.md). +If you need a quick reference of the available processing stages used in the recipes see @ref:[operator index](operators/index.md). ## Working with Flows diff --git a/akka-docs/src/main/paradox/stream/stream-flows-and-basics.md b/akka-docs/src/main/paradox/stream/stream-flows-and-basics.md index 9109a8e6e9..5db81e831e 100644 --- a/akka-docs/src/main/paradox/stream/stream-flows-and-basics.md +++ b/akka-docs/src/main/paradox/stream/stream-flows-and-basics.md @@ -36,7 +36,7 @@ is running. Processing Stage : The common name for all building blocks that build up a Graph. Examples of a processing stage would be operations like `map()`, `filter()`, custom `GraphStage` s and graph -junctions like `Merge` or `Broadcast`. For the full list of built-in processing stages see @ref:[stages overview](stages-overview.md) +junctions like `Merge` or `Broadcast`. For the full list of built-in processing stages see the @ref:[operator index](operators/index.md) When we talk about *asynchronous, non-blocking backpressure* we mean that the processing stages available in Akka diff --git a/akka-docs/src/main/paradox/stream/stream-graphs.md b/akka-docs/src/main/paradox/stream/stream-graphs.md index cf680f39eb..85e242603b 100644 --- a/akka-docs/src/main/paradox/stream/stream-graphs.md +++ b/akka-docs/src/main/paradox/stream/stream-graphs.md @@ -18,7 +18,7 @@ Graphs are built from simple Flows which serve as the linear connections within which serve as fan-in and fan-out points for Flows. Thanks to the junctions having meaningful types based on their behavior and making them explicit elements these elements should be rather straightforward to use. -Akka Streams currently provide these junctions (for a detailed list see @ref[stages overview](stages-overview.md)): +Akka Streams currently provide these junctions (for a detailed list see the @ref[operator index](operators/index.md)): * **Fan-out** diff --git a/akka-docs/src/main/paradox/stream/stream-introduction.md b/akka-docs/src/main/paradox/stream/stream-introduction.md index e42c00a33b..bd92881fa3 100644 --- a/akka-docs/src/main/paradox/stream/stream-introduction.md +++ b/akka-docs/src/main/paradox/stream/stream-introduction.md @@ -69,7 +69,7 @@ look like and what they can do. point. * The bottom-up learners may feel more at home rummaging through the @ref:[Streams Cookbook](stream-cookbook.md). - * For a complete overview of the built-in processing stages you can look at the -table in @ref:[stages overview](stages-overview.md) + * For a complete overview of the built-in processing operators you can look at the +@ref:[operator index](operators/index.md) * The other sections can be read sequentially or as needed during the previous steps, each digging deeper into specific topics. \ No newline at end of file diff --git a/akka-docs/src/main/paradox/stream/stream-quickstart.md b/akka-docs/src/main/paradox/stream/stream-quickstart.md index 66930d2cd4..f4f079b20f 100644 --- a/akka-docs/src/main/paradox/stream/stream-quickstart.md +++ b/akka-docs/src/main/paradox/stream/stream-quickstart.md @@ -202,7 +202,7 @@ second the throttle combinator will assert *back-pressure* upstream. This is basically all there is to Akka Streams in a nutshell—glossing over the fact that there are dozens of sources and sinks and many more stream -transformation combinators to choose from, see also @ref:[stages overview](stages-overview.md). +transformation combinators to choose from, see also @ref:[operator index](operators/index.md). # Reactive Tweets diff --git a/akka-docs/src/main/paradox/stream/stream-substream.md b/akka-docs/src/main/paradox/stream/stream-substream.md index e24a40eff4..6914c16857 100644 --- a/akka-docs/src/main/paradox/stream/stream-substream.md +++ b/akka-docs/src/main/paradox/stream/stream-substream.md @@ -6,7 +6,7 @@ into a stream of streams. SubFlows cannot contribute to the super-flow’s materialized value since they are materialized later, during the runtime of the flow graph processing. -Stages that create substreams are listed on @ref:[Nesting and flattening stages](stages-overview.md#nesting-and-flattening-stages) +Stages that create substreams are listed on @ref[Nesting and flattening stages](operators/index.md#nesting-and-flattening-stages) ## Nesting stages diff --git a/akka-stream-tests/src/test/scala/akka/stream/DocsStageCoverageSpec.scala b/akka-stream-tests/src/test/scala/akka/stream/DocsStageCoverageSpec.scala deleted file mode 100644 index 9dc48fffb6..0000000000 --- a/akka-stream-tests/src/test/scala/akka/stream/DocsStageCoverageSpec.scala +++ /dev/null @@ -1,97 +0,0 @@ -/** - * Copyright (C) 2015-2018 Lightbend Inc. - */ - -package akka.stream - -import java.io.File -import java.lang.reflect.{Method, Modifier} -import java.nio.file.{Path, Paths} - -import akka.event.Logging -import org.scalatest.{Matchers, WordSpec} - -class DocsStageCoverageSpec extends WordSpec with Matchers { - - val sFlowClass: Class[_] = classOf[akka.stream.scaladsl.Flow[_, _, _]] - val jFlowClass: Class[_] = classOf[akka.stream.javadsl.Flow[_, _, _]] - - val sSubFlowClass: Class[_] = classOf[DslConsistencySpec.ScalaSubFlow[_, _, _]] - val jSubFlowClass: Class[_] = classOf[akka.stream.javadsl.SubFlow[_, _, _]] - - val sSourceClass: Class[_] = classOf[akka.stream.scaladsl.Source[_, _]] - val jSourceClass: Class[_] = classOf[akka.stream.javadsl.Source[_, _]] - - val sSubSourceClass: Class[_] = classOf[DslConsistencySpec.ScalaSubSource[_, _]] - val jSubSourceClass: Class[_] = classOf[akka.stream.javadsl.SubSource[_, _]] - - val sSinkClass: Class[_] = classOf[akka.stream.scaladsl.Sink[_, _]] - val jSinkClass: Class[_] = classOf[akka.stream.javadsl.Sink[_, _]] - - val jRunnableGraphClass: Class[_] = classOf[akka.stream.javadsl.RunnableGraph[_]] - val sRunnableGraphClass: Class[_] = classOf[akka.stream.scaladsl.RunnableGraph[_]] - - val ignore: Set[String] = - Set("equals", "hashCode", "notify", "notifyAll", "wait", "toString", "getClass") ++ - Set("productArity", "canEqual", "productPrefix", "copy", "productIterator", "productElement") ++ - Set("create", "apply", "ops", "appendJava", "andThen", "andThenMat", "isIdentity", "withAttributes", "transformMaterializing") ++ - Set("asScala", "asJava", "deprecatedAndThen", "deprecatedAndThenMat") - - val graphHelpers = Set("zipGraph", "zipWithGraph", "mergeGraph", "mergeSortedGraph", "interleaveGraph", "concatGraph", "prependGraph", "alsoToGraph", "wireTapGraph", "orElseGraph", "divertToGraph") - - val allowMissing: Map[Class[_], Set[String]] = Map( - jFlowClass → graphHelpers, - jSourceClass → (graphHelpers ++ Set("watch", "ask")), - // Java subflows can only be nested using .via and .to (due to type system restrictions) - jSubFlowClass → (graphHelpers ++ Set("groupBy", "splitAfter", "splitWhen", "subFlow", "watch", "ask")), - jSubSourceClass → (graphHelpers ++ Set("groupBy", "splitAfter", "splitWhen", "subFlow", "watch", "ask")), - - sFlowClass → Set("of"), - sSourceClass → Set("adapt", "from", "watch"), - sSinkClass → Set("adapt"), - sSubFlowClass → Set(), - sSubSourceClass → Set(), - - sRunnableGraphClass → Set("builder")) - - def materializing(m: Method): Boolean = m.getParameterTypes.contains(classOf[ActorMaterializer]) - - val DocsRoot = Paths.get("akka-docs/src/main/paradox/stream") - - def assertPageExists(c: Class[_], name: String): Unit = { - val operatorDocFile: Path = operatorDocFilePath(c, name) - assert(operatorDocFile.toFile.exists(), s"Expected [$operatorDocFile] to exist and document [$name] operator on [$c]") - } - - private def operatorDocFilePath(c: Class[_], name: String): Path = - DocsRoot.resolve(Logging.simpleName(c)).resolve(name + ".md") - - "Java and Scala DSLs" must { - - ("Source" → List[Class[_]](sSourceClass, jSourceClass)) :: - // ("SubSource" → List[Class[_]](sSubSourceClass, jSubSourceClass)) :: - ("Flow" → List[Class[_]](sFlowClass, jFlowClass)) :: - // ("SubFlow" → List[Class[_]](sSubFlowClass, jSubFlowClass)) :: - ("Sink" → List[Class[_]](sSinkClass, jSinkClass)) :: - ("RunnableFlow" → List[Class[_]](sRunnableGraphClass, jRunnableGraphClass)) :: - Nil foreach { - case (element, classes) ⇒ - - val allOps = - (for { - c ← classes - m ← c.getMethods - if !Modifier.isStatic(m.getModifiers) - if !ignore(m.getName) - if !m.getName.contains("$") - if !materializing(m) - } yield m.getName).toSet - - allOps foreach { opName ⇒ - s"document [$element] operation [$opName]" in { - assertPageExists(classes.head, opName) - } - } - } - } -} diff --git a/build.sbt b/build.sbt index 7d270f9e77..7b9dc86336 100644 --- a/build.sbt +++ b/build.sbt @@ -235,7 +235,10 @@ lazy val docs = akkaModule("akka-docs") resolvers += Resolver.jcenterRepo, deployRsyncArtifact := List((paradox in Compile).value -> s"www/docs/akka/${version.value}") ) - .enablePlugins(AkkaParadoxPlugin, DeployRsync, NoPublish, ParadoxBrowse, ScaladocNoVerificationOfDiagrams) + .enablePlugins( + AkkaParadoxPlugin, DeployRsync, NoPublish, ParadoxBrowse, + ScaladocNoVerificationOfDiagrams, + StreamOperatorsIndexGenerator) .settings(ParadoxSupport.paradoxWithCustomDirectives) .disablePlugins(MimaPlugin, WhiteSourcePlugin) diff --git a/project/ParadoxSupport.scala b/project/ParadoxSupport.scala index 0f3739ab41..702f563314 100644 --- a/project/ParadoxSupport.scala +++ b/project/ParadoxSupport.scala @@ -113,7 +113,7 @@ object ParadoxSupport { //println(s"Looking for signature regex '$Signature'") val text = Source.fromFile(file)(Codec.UTF8).getLines.collect { - case line@Signature(signature, kind, l, definition) if labels contains l.toLowerCase() => + case line@Signature(signature, kind, l, definition) if labels contains l.replaceAll("Mat$", "").toLowerCase() => //println(s"Found label '$l' with sig '$full' in line $line") if (kind == "type") signature + definition else signature diff --git a/project/StreamOperatorsIndexGenerator.scala b/project/StreamOperatorsIndexGenerator.scala new file mode 100644 index 0000000000..7f56e62fb4 --- /dev/null +++ b/project/StreamOperatorsIndexGenerator.scala @@ -0,0 +1,207 @@ +/** + * Copyright (C) 2016-2018 Lightbend Inc. + */ + +import sbt._ +import sbt.Keys._ + +/** + * Generate the "index" pages of stream operators. + */ +object StreamOperatorsIndexGenerator extends AutoPlugin { + + override val projectSettings: Seq[Setting[_]] = inConfig(Compile)(Seq( + resourceGenerators += + generateAlphabeticalIndex(sourceDirectory, + _ / "paradox" / "stream" / "operators" / "index.md" + ) + )) + + val categories = Seq( + "Source stages", + "Sink stages", + "Additional Sink and Source converters", + "File IO Sinks and Sources", + "Simple processing stages", + "Flow stages composed of Sinks and Sources", + "Asynchronous processing stages", + "Timer driven stages", + "Backpressure aware stages", + "Nesting and flattening stages", + "Time aware stages", + "Fan-in stages", + // TODO these don't show up as def's yet so don't show up in the index.. +// "Fan-out stages", + "Watching status stages" + ) + + def categoryId(name: String): String = name.toLowerCase.replace(' ', '-') + + val pendingSourceOrFlow = Seq( + "to", + "toMat", + "via", + "viaMat", + "async", + "upcast", + "shape", + "run", + "runWith", + "traversalBuilder", + "runFold", + "runFoldAsync", + "runForeach", + "runReduce", + "named", + "throttleEven", + "actorPublisher", + "addAttributes", + "mapMaterializedValue", + // *Graph: + "concatGraph", + "prependGraph", + "mergeSortedGraph", + "fromGraph", + "interleaveGraph", + "zipGraph", + "mergeGraph", + "wireTapGraph", + "alsoToGraph", + "orElseGraph", + "divertToGraph", + "zipWithGraph" + ) + + // FIXME document these methods as well + val pendingTestCases = Map( + "Source" -> (pendingSourceOrFlow ++ Seq( + "preMaterialize" + )), + "Flow" -> (pendingSourceOrFlow ++ Seq( + "lazyInit", + "fromProcessorMat", + "toProcessor", + "fromProcessor", + "of", + "join", + "joinMat", + "fromFunction" + )), + "Sink" -> Seq( + "lazyInit", + "collection", + "contramap", + "named", + "addAttributes", + "async", + "mapMaterializedValue", + "runWith", + "shape", + "traversalBuilder", + "fromGraph", + "actorSubscriber", + "foldAsync", + "newOnCompleteStage" + ), + "FileIO" -> Seq( + "fromFile", + "toFile" + ) + ) + + val ignore = + Set("equals", "hashCode", "notify", "notifyAll", "wait", "toString", "getClass") ++ + Set("productArity", "canEqual", "productPrefix", "copy", "productIterator", "productElement") ++ + Set("create", "apply", "ops", "appendJava", "andThen", "andThenMat", "isIdentity", "withAttributes", "transformMaterializing") ++ + Set("asScala", "asJava", "deprecatedAndThen", "deprecatedAndThenMat") ++ + Set("++") + + def isPending(element: String, opName: String) = + pendingTestCases.get(element).exists(_.contains(opName)) + + def generateAlphabeticalIndex(dir: SettingKey[File], locate: File ⇒ File) = Def.task[Seq[File]] { + val file = locate(dir.value) + + val defs = + List( + "akka-stream/src/main/scala/akka/stream/scaladsl/Source.scala", + "akka-stream/src/main/scala/akka/stream/javadsl/Source.scala", +// "akka-stream/src/main/scala/akka/stream/scaladsl/SubSource.scala", +// "akka-stream/src/main/scala/akka/stream/javadsl/SubSource.scala", + "akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala", + "akka-stream/src/main/scala/akka/stream/javadsl/Flow.scala", +// "akka-stream/src/main/scala/akka/stream/scaladsl/SubFlow.scala", +// "akka-stream/src/main/scala/akka/stream/javadsl/SubFlow.scala", +// "akka-stream/src/main/scala/akka/stream/scaladsl/RunnableFlow.scala", +// "akka-stream/src/main/scala/akka/stream/javadsl/RunnableFlow.scala", + "akka-stream/src/main/scala/akka/stream/scaladsl/Sink.scala", + "akka-stream/src/main/scala/akka/stream/javadsl/Sink.scala", + "akka-stream/src/main/scala/akka/stream/scaladsl/StreamConverters.scala", + "akka-stream/src/main/scala/akka/stream/javadsl/StreamConverters.scala", + "akka-stream/src/main/scala/akka/stream/scaladsl/FileIO.scala", + "akka-stream/src/main/scala/akka/stream/javadsl/FileIO.scala", + ).flatMap{ f ⇒ + val element = f.split("/")(7).split("\\.")(0) + IO.read(new File(f)).split("\n") + .map(_.trim).filter(_.startsWith("def ")) + .map(_.drop(4).takeWhile(c ⇒ c != '[' && c != '(' && c != ':')) + .filter(op => !isPending(element, op)) + .filter(op => !ignore.contains(op)) + .map(_.replaceAll("Mat$", "")) + .map(method ⇒ (element, method)) + } + + val sourceAndFlow = defs.collect { case ("Source", method) => method } intersect defs.collect { case ("Flow", method) => method } + + val groupedDefs = + defs.map { + case (element @ ("Source" | "Flow"), method) if sourceAndFlow.contains(method) => + ("Source/Flow", method, s"Source-or-Flow/$method.md") + case (element, method) => + (element, method, s"$element/$method.md") + }.distinct + + val tablePerCategory = groupedDefs.map { case (element, method, md) => + val (description, category) = getDetails(file.getParentFile / md) + category -> (element, method, md, description) + } + .groupBy(_._1) + .mapValues(lines => + "| |Operator|Description|\n" ++ + "|--|--|--|\n" ++ + lines + .map(_._2) + .sortBy(_._2) + .map { case (element, method, md, description) => s"|$element|@ref[$method]($md)|$description|" } + .mkString("\n") + ) + + val tables = categories.map { category => + s"## $category\n\n" ++ + IO.read(dir.value / "categories" / (categoryId(category) + ".md")) ++ "\n\n" ++ + tablePerCategory(category) + }.mkString("\n\n") + + val content = + "# Operators\n\n" + tables + "\n\n@@@ index\n\n" + + groupedDefs.map { case (_, method, md) => s"* [$method]($md)" }.mkString("\n") + "\n\n@@@\n" + + if (!file.exists || IO.read(file) != content) IO.write(file, content) + Seq(file) + } + + def getDetails(file: File): (String, String) = { + val contents = IO.read(file).dropWhile(_ != '\n').drop(2) + // This forces the short description to be on a single line. We could make this smarter, + // but 'forcing' the short description to be really short seems nice as well. + val description = contents.takeWhile(_ != '\n') + val categoryLink = contents.dropWhile(_ != '\n').drop(2).takeWhile(_ != '\n') + require(categoryLink.startsWith("@ref"), s"category link in $file, saw $categoryLink") + val categoryName = categoryLink.drop(5).takeWhile(_ != ']') + val categoryLinkId = categoryLink.dropWhile(_ != '#').drop(1).takeWhile(_ != ')') + require(categories.contains(categoryName), s"category $categoryName in $file should be known") + require(categoryLinkId == categoryId(categoryName), s"category id $categoryLinkId in $file") + (description, categoryName) + } + +}