diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4bb1294b53..2158cc0c93 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -383,9 +383,9 @@ tested it becomes an officially supported Akka feature. [List of Akka features marked as may change](http://doc.akka.io/docs/akka/current/common/may-change.html) -## Contributing new Akka Streams stages/operators +## Contributing new Akka Streams operators -Documentation of Akka Streams operators and stages is automatically enforced. +Documentation of Akka Streams operators is automatically enforced. If a method exists on Source / Sink / Flow, or any other class listed in `project/StreamOperatorsIndexGenerator.scala`, it must also have a corresponding documentation page under `akka-docs/src/main/paradox/streams/operators/...`. @@ -393,11 +393,11 @@ The pages structure is well-defined, and must be the same on all documentation p docs pages in there to see the pattern in action. In general though the page must consist of: - the title, including where the operator is defined (e.g. `ActorFlow.ask` or `Source.map`) -- a short explanation of what this stage does, 1 sentence is optimal -- an image explaining the stage more visually (whenever possible) -- a link to the stages' "category" (these are listed in `akka-docs/src/main/paradox/categories`) +- a short explanation of what this operator does, 1 sentence is optimal +- an image explaining the operator more visually (whenever possible) +- a link to the operators' "category" (these are listed in `akka-docs/src/main/paradox/categories`) - the method signature snippet (use the built in directives to generate it) -- a longer explanation about the stage and it's exact semantics (when it pulls, cancels, signals elements) +- a longer explanation about the operator and it's exact semantics (when it pulls, cancels, signals elements) - at least one usage example Using this structure, the surrounding infrastructure will **generate the index pages**, so you do not need to maintain diff --git a/akka-docs/src/main/categories/actor-interop-operators.md b/akka-docs/src/main/categories/actor-interop-operators.md new file mode 100644 index 0000000000..86d5d92d31 --- /dev/null +++ b/akka-docs/src/main/categories/actor-interop-operators.md @@ -0,0 +1 @@ +Operators meant for inter-operating between Akka Streams and Actors: diff --git a/akka-docs/src/main/categories/actor-interop-stages.md b/akka-docs/src/main/categories/actor-interop-stages.md deleted file mode 100644 index 27221ca10a..0000000000 --- a/akka-docs/src/main/categories/actor-interop-stages.md +++ /dev/null @@ -1 +0,0 @@ -Stages and operations meant for inter-operating between Akka Streams and Actors: 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 index db9fdc0f6e..751230442a 100644 --- a/akka-docs/src/main/categories/additional-sink-and-source-converters.md +++ b/akka-docs/src/main/categories/additional-sink-and-source-converters.md @@ -1,5 +1,5 @@ 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 +`StreamConverters`. As they are blocking APIs the implementations of these operators are run on a separate dispatcher configured through the `akka.stream.blocking-io-dispatcher`. @@@ warning diff --git a/akka-docs/src/main/categories/asynchronous-operators.md b/akka-docs/src/main/categories/asynchronous-operators.md index 2fd69d6dbf..e1e7ef317b 100644 --- a/akka-docs/src/main/categories/asynchronous-operators.md +++ b/akka-docs/src/main/categories/asynchronous-operators.md @@ -1,2 +1,2 @@ -These stages encapsulate an asynchronous computation, properly handling backpressure while taking care of the asynchronous +These operators 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-operators.md b/akka-docs/src/main/categories/backpressure-aware-operators.md new file mode 100644 index 0000000000..6ef298d647 --- /dev/null +++ b/akka-docs/src/main/categories/backpressure-aware-operators.md @@ -0,0 +1 @@ +These operators 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/backpressure-aware-stages.md b/akka-docs/src/main/categories/backpressure-aware-stages.md deleted file mode 100644 index 32f899d893..0000000000 --- a/akka-docs/src/main/categories/backpressure-aware-stages.md +++ /dev/null @@ -1 +0,0 @@ -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-operators.md b/akka-docs/src/main/categories/fan-in-operators.md new file mode 100644 index 0000000000..9bb39619ff --- /dev/null +++ b/akka-docs/src/main/categories/fan-in-operators.md @@ -0,0 +1,2 @@ +These operators 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-in-stages.md b/akka-docs/src/main/categories/fan-in-stages.md deleted file mode 100644 index 6516c7082e..0000000000 --- a/akka-docs/src/main/categories/fan-in-stages.md +++ /dev/null @@ -1,2 +0,0 @@ -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-operators.md similarity index 100% rename from akka-docs/src/main/categories/fan-out-stages.md rename to akka-docs/src/main/categories/fan-out-operators.md diff --git a/akka-docs/src/main/categories/flow-stages-composed-of-sinks-and-sources.md b/akka-docs/src/main/categories/flow-operators-composed-of-sinks-and-sources.md similarity index 100% rename from akka-docs/src/main/categories/flow-stages-composed-of-sinks-and-sources.md rename to akka-docs/src/main/categories/flow-operators-composed-of-sinks-and-sources.md diff --git a/akka-docs/src/main/categories/nesting-and-flattening-stages.md b/akka-docs/src/main/categories/nesting-and-flattening-operators.md similarity index 56% rename from akka-docs/src/main/categories/nesting-and-flattening-stages.md rename to akka-docs/src/main/categories/nesting-and-flattening-operators.md index 530c879b24..7273b250a7 100644 --- a/akka-docs/src/main/categories/nesting-and-flattening-stages.md +++ b/akka-docs/src/main/categories/nesting-and-flattening-operators.md @@ -1,4 +1,4 @@ -These stages either take a stream and turn it into a stream of streams (nesting) or they take a stream that contains +These operators 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-operators.md b/akka-docs/src/main/categories/simple-operators.md index caaf4b719a..aba2c15dc8 100644 --- a/akka-docs/src/main/categories/simple-operators.md +++ b/akka-docs/src/main/categories/simple-operators.md @@ -1,5 +1,5 @@ -These stages can transform the rate of incoming elements since there are stages that emit multiple elements for a +These operators can transform the rate of incoming elements since there are operators 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 +rate is affected. This is in contrast with [detached operators](#backpressure-aware-operators) 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-operators.md similarity index 100% rename from akka-docs/src/main/categories/sink-stages.md rename to akka-docs/src/main/categories/sink-operators.md diff --git a/akka-docs/src/main/categories/source-stages.md b/akka-docs/src/main/categories/source-operators.md similarity index 100% rename from akka-docs/src/main/categories/source-stages.md rename to akka-docs/src/main/categories/source-operators.md diff --git a/akka-docs/src/main/categories/time-aware-operators.md b/akka-docs/src/main/categories/time-aware-operators.md new file mode 100644 index 0000000000..9673ff31c5 --- /dev/null +++ b/akka-docs/src/main/categories/time-aware-operators.md @@ -0,0 +1 @@ +Those operators operate taking time into consideration. \ 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 deleted file mode 100644 index 82123cefc2..0000000000 --- a/akka-docs/src/main/categories/time-aware-stages.md +++ /dev/null @@ -1 +0,0 @@ -Those stages operate taking time into consideration. \ No newline at end of file diff --git a/akka-docs/src/main/categories/timer-driven-operators.md b/akka-docs/src/main/categories/timer-driven-operators.md new file mode 100644 index 0000000000..644d470eb3 --- /dev/null +++ b/akka-docs/src/main/categories/timer-driven-operators.md @@ -0,0 +1 @@ +These operators 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/timer-driven-stages.md b/akka-docs/src/main/categories/timer-driven-stages.md deleted file mode 100644 index ef62935229..0000000000 --- a/akka-docs/src/main/categories/timer-driven-stages.md +++ /dev/null @@ -1 +0,0 @@ -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-operators.md similarity index 100% rename from akka-docs/src/main/categories/watching-status-stages.md rename to akka-docs/src/main/categories/watching-status-operators.md diff --git a/akka-docs/src/main/paradox/general/stream/stream-design.md b/akka-docs/src/main/paradox/general/stream/stream-design.md index e8bb8c72dd..805a5ce9c8 100644 --- a/akka-docs/src/main/paradox/general/stream/stream-design.md +++ b/akka-docs/src/main/paradox/general/stream/stream-design.md @@ -24,7 +24,7 @@ This means that we provide all the tools necessary to express any stream process One important consequence of offering only features that can be relied upon is the restriction that Akka Streams cannot ensure that all objects sent through a processing topology will be processed. Elements can be dropped for a number of reasons: - * plain user code can consume one element in a *map(...)* stage and produce an entirely different one as its result + * plain user code can consume one element in a *map(...)* operator and produce an entirely different one as its result * common stream operators drop elements intentionally, e.g. take/drop/filter/conflate/buffer/… * stream failure will tear down the stream without waiting for processing to finish, all elements that are in flight will be discarded * stream cancellation will propagate upstream (e.g. from a *take* operator) leading to upstream processing steps being terminated without having processed all of their inputs @@ -90,7 +90,7 @@ Unfortunately the method name for signaling *failure* to a Subscriber is called @@@ -There is only limited support for treating `onError` in Akka Streams compared to the operators that are available for the transformation of data elements, which is intentional in the spirit of the previous paragraph. Since `onError` signals that the stream is collapsing, its ordering semantics are not the same as for stream completion: transformation stages of any kind will collapse with the stream, possibly still holding elements in implicit or explicit buffers. This means that data elements emitted before a failure can still be lost if the `onError` overtakes them. +There is only limited support for treating `onError` in Akka Streams compared to the operators that are available for the transformation of data elements, which is intentional in the spirit of the previous paragraph. Since `onError` signals that the stream is collapsing, its ordering semantics are not the same as for stream completion: transformation operators of any kind will collapse with the stream, possibly still holding elements in implicit or explicit buffers. This means that data elements emitted before a failure can still be lost if the `onError` overtakes them. The ability for failures to propagate faster than data elements is essential for tearing down streams that are back-pressured—especially since back-pressure can be the failure mode (e.g. by tripping upstream buffers which then abort because they cannot do anything else; or if a dead-lock occurred). diff --git a/akka-docs/src/main/paradox/stream/operators/ActorFlow/ask.md b/akka-docs/src/main/paradox/stream/operators/ActorFlow/ask.md index e05c3cf6bc..00fe9047c1 100644 --- a/akka-docs/src/main/paradox/stream/operators/ActorFlow/ask.md +++ b/akka-docs/src/main/paradox/stream/operators/ActorFlow/ask.md @@ -2,7 +2,7 @@ Use the `AskPattern` to send each element as an `ask` to the target actor, and expect a reply back that will be sent further downstream. -@ref[Actor interop stages](../index.md#actor-interop-stages) +@ref[Actor interop operators](../index.md#actor-interop-operators) ## Dependency diff --git a/akka-docs/src/main/paradox/stream/operators/ActorSink/actorRef.md b/akka-docs/src/main/paradox/stream/operators/ActorSink/actorRef.md index 002c2a7d4f..ff889ec9e6 100644 --- a/akka-docs/src/main/paradox/stream/operators/ActorSink/actorRef.md +++ b/akka-docs/src/main/paradox/stream/operators/ActorSink/actorRef.md @@ -2,7 +2,7 @@ Sends the elements of the stream to the given @java[`ActorRef`]@scala[`ActorRef[T]`]. -@ref[Actor interop stages](../index.md#actor-interop-stages) +@ref[Actor interop operators](../index.md#actor-interop-operators) @@@div { .group-scala } @@ -37,7 +37,7 @@ upstream, but there is no back-pressure signal from the destination actor, i.e. if the actor is not consuming the messages fast enough the mailbox of the actor will grow. For potentially slow consumer actors it is recommended to use a bounded mailbox with zero `mailbox-push-timeout-time` or use a rate -limiting stage in front of this `Sink`. +limiting operator in front of this `Sink`. ## Examples diff --git a/akka-docs/src/main/paradox/stream/operators/Flow/fromSinkAndSource.md b/akka-docs/src/main/paradox/stream/operators/Flow/fromSinkAndSource.md index 73440a5d7e..2ee4d47237 100644 --- a/akka-docs/src/main/paradox/stream/operators/Flow/fromSinkAndSource.md +++ b/akka-docs/src/main/paradox/stream/operators/Flow/fromSinkAndSource.md @@ -2,7 +2,7 @@ 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) +@ref[Flow operators composed of Sinks and Sources](../index.md#flow-operators-composed-of-sinks-and-sources) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Flow/fromSinkAndSourceCoupled.md b/akka-docs/src/main/paradox/stream/operators/Flow/fromSinkAndSourceCoupled.md index 6d6c54d302..9c85ff5455 100644 --- a/akka-docs/src/main/paradox/stream/operators/Flow/fromSinkAndSourceCoupled.md +++ b/akka-docs/src/main/paradox/stream/operators/Flow/fromSinkAndSourceCoupled.md @@ -2,7 +2,7 @@ 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) +@ref[Flow operators composed of Sinks and Sources](../index.md#flow-operators-composed-of-sinks-and-sources) @@@div { .group-scala } @@ -15,7 +15,7 @@ Allows coupling termination (cancellation, completion, erroring) of Sinks and So ## 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. +Similar to `Flow.fromSinkAndSource` however couples the termination of these two operators. E.g. if the emitted `Flow` gets a cancellation, the `Source` is cancelled, however the Sink will also be completed. The table below illustrates the effects in detail: diff --git a/akka-docs/src/main/paradox/stream/operators/Sink/actorRef.md b/akka-docs/src/main/paradox/stream/operators/Sink/actorRef.md index 03c9b5674a..88b37550d0 100644 --- a/akka-docs/src/main/paradox/stream/operators/Sink/actorRef.md +++ b/akka-docs/src/main/paradox/stream/operators/Sink/actorRef.md @@ -2,7 +2,7 @@ Send the elements from the stream to an `ActorRef`. -@ref[Sink stages](../index.md#sink-stages) +@ref[Sink operators](../index.md#sink-operators) @@@ div { .group-scala } ## Signature diff --git a/akka-docs/src/main/paradox/stream/operators/Sink/actorRefWithAck.md b/akka-docs/src/main/paradox/stream/operators/Sink/actorRefWithAck.md index b7bd884903..c3d550b667 100644 --- a/akka-docs/src/main/paradox/stream/operators/Sink/actorRefWithAck.md +++ b/akka-docs/src/main/paradox/stream/operators/Sink/actorRefWithAck.md @@ -2,7 +2,7 @@ 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) +@ref[Sink operators](../index.md#sink-operators) ## Description diff --git a/akka-docs/src/main/paradox/stream/operators/Sink/asPublisher.md b/akka-docs/src/main/paradox/stream/operators/Sink/asPublisher.md index 1af0fae018..f022d35353 100644 --- a/akka-docs/src/main/paradox/stream/operators/Sink/asPublisher.md +++ b/akka-docs/src/main/paradox/stream/operators/Sink/asPublisher.md @@ -2,7 +2,7 @@ Integration with Reactive Streams, materializes into a `org.reactivestreams.Publisher`. -@ref[Sink stages](../index.md#sink-stages) +@ref[Sink operators](../index.md#sink-operators) @@@ div { .group-scala } ## Signature diff --git a/akka-docs/src/main/paradox/stream/operators/Sink/cancelled.md b/akka-docs/src/main/paradox/stream/operators/Sink/cancelled.md index 32f81634fb..0ee8a287d3 100644 --- a/akka-docs/src/main/paradox/stream/operators/Sink/cancelled.md +++ b/akka-docs/src/main/paradox/stream/operators/Sink/cancelled.md @@ -2,7 +2,7 @@ Immediately cancel the stream -@ref[Sink stages](../index.md#sink-stages) +@ref[Sink operators](../index.md#sink-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Sink/combine.md b/akka-docs/src/main/paradox/stream/operators/Sink/combine.md index f92c78d6ec..da12dc8c7d 100644 --- a/akka-docs/src/main/paradox/stream/operators/Sink/combine.md +++ b/akka-docs/src/main/paradox/stream/operators/Sink/combine.md @@ -2,7 +2,7 @@ Combine several sinks into one using a user specified strategy -@ref[Sink stages](../index.md#sink-stages) +@ref[Sink operators](../index.md#sink-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Sink/fold.md b/akka-docs/src/main/paradox/stream/operators/Sink/fold.md index 4c0bef77a4..a799678e82 100644 --- a/akka-docs/src/main/paradox/stream/operators/Sink/fold.md +++ b/akka-docs/src/main/paradox/stream/operators/Sink/fold.md @@ -2,7 +2,7 @@ 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) +@ref[Sink operators](../index.md#sink-operators) @@@div { .group-scala } @@ -19,7 +19,7 @@ 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 +This operator allows combining values into a result without a global mutable state by instead passing the state along between invocations. @@@div { .callout } diff --git a/akka-docs/src/main/paradox/stream/operators/Sink/foreach.md b/akka-docs/src/main/paradox/stream/operators/Sink/foreach.md index b26de8caf0..5b8dbb5169 100644 --- a/akka-docs/src/main/paradox/stream/operators/Sink/foreach.md +++ b/akka-docs/src/main/paradox/stream/operators/Sink/foreach.md @@ -2,7 +2,7 @@ Invoke a given procedure for each element received. -@ref[Sink stages](../index.md#sink-stages) +@ref[Sink operators](../index.md#sink-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Sink/foreachParallel.md b/akka-docs/src/main/paradox/stream/operators/Sink/foreachParallel.md index 8a46a51395..63f9e00d08 100644 --- a/akka-docs/src/main/paradox/stream/operators/Sink/foreachParallel.md +++ b/akka-docs/src/main/paradox/stream/operators/Sink/foreachParallel.md @@ -2,7 +2,7 @@ Like `foreach` but allows up to `parallellism` procedure calls to happen in parallel. -@ref[Sink stages](../index.md#sink-stages) +@ref[Sink operators](../index.md#sink-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Sink/fromSubscriber.md b/akka-docs/src/main/paradox/stream/operators/Sink/fromSubscriber.md index df649a00d8..3bfc750296 100644 --- a/akka-docs/src/main/paradox/stream/operators/Sink/fromSubscriber.md +++ b/akka-docs/src/main/paradox/stream/operators/Sink/fromSubscriber.md @@ -2,7 +2,7 @@ Integration with Reactive Streams, wraps a `org.reactivestreams.Subscriber` as a sink. -@ref[Sink stages](../index.md#sink-stages) +@ref[Sink operators](../index.md#sink-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Sink/head.md b/akka-docs/src/main/paradox/stream/operators/Sink/head.md index bd0b98df0e..ef4775a338 100644 --- a/akka-docs/src/main/paradox/stream/operators/Sink/head.md +++ b/akka-docs/src/main/paradox/stream/operators/Sink/head.md @@ -2,7 +2,7 @@ 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) +@ref[Sink operators](../index.md#sink-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Sink/headOption.md b/akka-docs/src/main/paradox/stream/operators/Sink/headOption.md index 569819400e..2625716f73 100644 --- a/akka-docs/src/main/paradox/stream/operators/Sink/headOption.md +++ b/akka-docs/src/main/paradox/stream/operators/Sink/headOption.md @@ -2,7 +2,7 @@ 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) +@ref[Sink operators](../index.md#sink-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Sink/ignore.md b/akka-docs/src/main/paradox/stream/operators/Sink/ignore.md index 487b080341..dce48dcad2 100644 --- a/akka-docs/src/main/paradox/stream/operators/Sink/ignore.md +++ b/akka-docs/src/main/paradox/stream/operators/Sink/ignore.md @@ -2,7 +2,7 @@ Consume all elements but discards them. -@ref[Sink stages](../index.md#sink-stages) +@ref[Sink operators](../index.md#sink-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Sink/last.md b/akka-docs/src/main/paradox/stream/operators/Sink/last.md index adda59e561..ce301059fc 100644 --- a/akka-docs/src/main/paradox/stream/operators/Sink/last.md +++ b/akka-docs/src/main/paradox/stream/operators/Sink/last.md @@ -2,7 +2,7 @@ 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) +@ref[Sink operators](../index.md#sink-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Sink/lastOption.md b/akka-docs/src/main/paradox/stream/operators/Sink/lastOption.md index abd12bdb20..0c71a2e527 100644 --- a/akka-docs/src/main/paradox/stream/operators/Sink/lastOption.md +++ b/akka-docs/src/main/paradox/stream/operators/Sink/lastOption.md @@ -2,7 +2,7 @@ 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) +@ref[Sink operators](../index.md#sink-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Sink/lazyInitAsync.md b/akka-docs/src/main/paradox/stream/operators/Sink/lazyInitAsync.md index 96f509b88c..3b00a845c8 100644 --- a/akka-docs/src/main/paradox/stream/operators/Sink/lazyInitAsync.md +++ b/akka-docs/src/main/paradox/stream/operators/Sink/lazyInitAsync.md @@ -2,7 +2,7 @@ Creates a real `Sink` upon receiving the first element. -@ref[Sink stages](../index.md#sink-stages) +@ref[Sink operators](../index.md#sink-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Sink/onComplete.md b/akka-docs/src/main/paradox/stream/operators/Sink/onComplete.md index 5581ef7042..da63a5a566 100644 --- a/akka-docs/src/main/paradox/stream/operators/Sink/onComplete.md +++ b/akka-docs/src/main/paradox/stream/operators/Sink/onComplete.md @@ -2,7 +2,7 @@ Invoke a callback when the stream has completed or failed. -@ref[Sink stages](../index.md#sink-stages) +@ref[Sink operators](../index.md#sink-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Sink/preMaterialize.md b/akka-docs/src/main/paradox/stream/operators/Sink/preMaterialize.md index f43830d3a2..d71e6cf83a 100644 --- a/akka-docs/src/main/paradox/stream/operators/Sink/preMaterialize.md +++ b/akka-docs/src/main/paradox/stream/operators/Sink/preMaterialize.md @@ -2,7 +2,7 @@ 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) +@ref[Sink operators](../index.md#sink-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Sink/queue.md b/akka-docs/src/main/paradox/stream/operators/Sink/queue.md index b537040ddf..835abed44c 100644 --- a/akka-docs/src/main/paradox/stream/operators/Sink/queue.md +++ b/akka-docs/src/main/paradox/stream/operators/Sink/queue.md @@ -2,7 +2,7 @@ Materialize a `SinkQueue` that can be pulled to trigger demand through the sink. -@ref[Sink stages](../index.md#sink-stages) +@ref[Sink operators](../index.md#sink-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Sink/reduce.md b/akka-docs/src/main/paradox/stream/operators/Sink/reduce.md index cd0029ce49..26ea5a5295 100644 --- a/akka-docs/src/main/paradox/stream/operators/Sink/reduce.md +++ b/akka-docs/src/main/paradox/stream/operators/Sink/reduce.md @@ -2,7 +2,7 @@ Apply a reduction function on the incoming elements and pass the result to the next invocation. -@ref[Sink stages](../index.md#sink-stages) +@ref[Sink operators](../index.md#sink-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Sink/seq.md b/akka-docs/src/main/paradox/stream/operators/Sink/seq.md index 4dc51b953a..27b5c36474 100644 --- a/akka-docs/src/main/paradox/stream/operators/Sink/seq.md +++ b/akka-docs/src/main/paradox/stream/operators/Sink/seq.md @@ -2,7 +2,7 @@ Collect values emitted from the stream into a collection. -@ref[Sink stages](../index.md#sink-stages) +@ref[Sink operators](../index.md#sink-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/apply.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/apply.md index 68373ebf51..4147f8a09a 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/apply.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/apply.md @@ -2,7 +2,7 @@ Stream the values of an `immutable.Seq`. -@ref[Source stages](../index.md#source-stages) +@ref[Source operators](../index.md#source-operators) @@@ div { .group-scala } ## Signature diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/ask.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/ask.md index 05af939360..61efacb380 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/ask.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/ask.md @@ -18,7 +18,7 @@ If any of the asks times out it will fail the stream with a [[akka.pattern.AskTi 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. +An `akka.util.Status#Failure` will cause the operator to fail with the cause carried in the `Failure` message. Adheres to the [[ActorAttributes.SupervisionStrategy]] attribute. diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/backpressureTimeout.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/backpressureTimeout.md index e6693cf3c6..dfa5759f50 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/backpressureTimeout.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/backpressureTimeout.md @@ -2,7 +2,7 @@ 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) +@ref[Time aware operators](../index.md#time-aware-operators) @@@ div { .group-scala } ## Signature diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/balance.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/balance.md index 670716a3a8..0bc0a7aef3 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/balance.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/balance.md @@ -2,7 +2,7 @@ Fan-out the stream to several streams. -@ref[Fan-out stages](../index.md#fan-out-stages) +@ref[Fan-out operators](../index.md#fan-out-operators) ## Description diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/batch.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/batch.md index 3c829b27ba..f28615c860 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/batch.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/batch.md @@ -2,7 +2,7 @@ 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) +@ref[Backpressure aware operators](../index.md#backpressure-aware-operators) @@@ div { .group-scala } ## Signature diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/batchWeighted.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/batchWeighted.md index 02219123cb..7659019e7a 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/batchWeighted.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/batchWeighted.md @@ -2,7 +2,7 @@ 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) +@ref[Backpressure aware operators](../index.md#backpressure-aware-operators) @@@ div { .group-scala } ## Signature diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/broadcast.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/broadcast.md index c7f30846a5..d72c55ddc3 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/broadcast.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/broadcast.md @@ -2,7 +2,7 @@ Emit each incoming element each of `n` outputs. -@ref[Fan-out stages](../index.md#fan-out-stages) +@ref[Fan-out operators](../index.md#fan-out-operators) ## Description diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/buffer.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/buffer.md index f12fc7d730..d5bd802245 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/buffer.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/buffer.md @@ -2,7 +2,7 @@ Allow for a temporarily faster upstream events by buffering `size` elements. -@ref[Backpressure aware stages](../index.md#backpressure-aware-stages) +@ref[Backpressure aware operators](../index.md#backpressure-aware-operators) @@@ div { .group-scala } ## Signature diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/collect.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/collect.md index f7ba620615..4a3c3fcd75 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/collect.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/collect.md @@ -15,7 +15,7 @@ Apply a partial function to each incoming element, if the partial function is de ## Description 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. +value is passed downstream. Can often replace `filter` followed by `map` to achieve the same in one single operators. @@@div { .callout } diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/completionTimeout.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/completionTimeout.md index 0af7531305..fb35eef19c 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/completionTimeout.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/completionTimeout.md @@ -2,7 +2,7 @@ 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) +@ref[Time aware operators](../index.md#time-aware-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/concat.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/concat.md index 6aa1d90c39..51048b5327 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/concat.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/concat.md @@ -2,7 +2,7 @@ After completion of the original upstream the elements of the given source will be emitted. -@ref[Fan-in stages](../index.md#fan-in-stages) +@ref[Fan-in operators](../index.md#fan-in-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/conflate.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/conflate.md index d41f3ad619..eb2ee541a3 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/conflate.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/conflate.md @@ -2,7 +2,7 @@ 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) +@ref[Backpressure aware operators](../index.md#backpressure-aware-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/conflateWithSeed.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/conflateWithSeed.md index 6aea2f37a7..7f769f601a 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/conflateWithSeed.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/conflateWithSeed.md @@ -2,7 +2,7 @@ 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) +@ref[Backpressure aware operators](../index.md#backpressure-aware-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/delay.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/delay.md index bb759cc5da..6db9c46ae5 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/delay.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/delay.md @@ -2,7 +2,7 @@ Delay every element passed through with a specific duration. -@ref[Timer driven stages](../index.md#timer-driven-stages) +@ref[Timer driven operators](../index.md#timer-driven-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/detach.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/detach.md index e3cd693085..a306e48e77 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/detach.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/detach.md @@ -19,7 +19,7 @@ Detach upstream demand from downstream demand without detaching the stream rates @@@div { .callout } -**emits** when the upstream stage has emitted and there is demand +**emits** when the upstream operators has emitted and there is demand **backpressures** when downstream backpressures diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/dropWithin.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/dropWithin.md index b0b77ce9f0..d2f6d8f7d9 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/dropWithin.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/dropWithin.md @@ -2,7 +2,7 @@ Drop elements until a timeout has fired -@ref[Timer driven stages](../index.md#timer-driven-stages) +@ref[Timer driven operators](../index.md#timer-driven-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/expand.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/expand.md index 6ec62b8c2f..91fc9ed003 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/expand.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/expand.md @@ -2,7 +2,7 @@ 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) +@ref[Backpressure aware operators](../index.md#backpressure-aware-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/extrapolate.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/extrapolate.md index 477b517cc5..fc74a0e2c5 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/extrapolate.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/extrapolate.md @@ -2,7 +2,7 @@ Allow for a faster downstream by expanding the last emitted element to an `Iterator`. -@ref[Backpressure aware stages](../index.md#backpressure-aware-stages) +@ref[Backpressure aware operators](../index.md#backpressure-aware-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/flatMapConcat.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/flatMapConcat.md index 477a12ea35..75956fce9e 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/flatMapConcat.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/flatMapConcat.md @@ -2,7 +2,7 @@ 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) +@ref[Nesting and flattening operators](../index.md#nesting-and-flattening-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/flatMapMerge.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/flatMapMerge.md index 9fecb35c46..e6dbd1a7aa 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/flatMapMerge.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/flatMapMerge.md @@ -2,7 +2,7 @@ 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) +@ref[Nesting and flattening operators](../index.md#nesting-and-flattening-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/groupBy.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/groupBy.md index aa822853ab..32f524accb 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/groupBy.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/groupBy.md @@ -2,7 +2,7 @@ Demultiplex the incoming stream into separate output streams. -@ref[Nesting and flattening stages](../index.md#nesting-and-flattening-stages) +@ref[Nesting and flattening operators](../index.md#nesting-and-flattening-operators) @@@div { .group-scala } @@ -24,7 +24,7 @@ of closing these elements might get lost. @@@ warning -If `allowClosedSubstreamRecreation` is set to `false` (default behavior) the stage keeps track of all +If `allowClosedSubstreamRecreation` is set to `false` (default behavior) the operators keeps track of all keys of streams that have already been closed. If you expect an infinite number of keys this can cause memory issues. Elements belonging to those keys are drained directly and not send to the substream. diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/groupedWeightedWithin.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/groupedWeightedWithin.md index 9db29d601e..1b511ef29d 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/groupedWeightedWithin.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/groupedWeightedWithin.md @@ -2,7 +2,7 @@ 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) +@ref[Timer driven operators](../index.md#timer-driven-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/groupedWithin.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/groupedWithin.md index bc0e79a172..dacb25c37b 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/groupedWithin.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/groupedWithin.md @@ -2,7 +2,7 @@ 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) +@ref[Timer driven operators](../index.md#timer-driven-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/idleTimeout.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/idleTimeout.md index dd1c07634c..9d1e299bcf 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/idleTimeout.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/idleTimeout.md @@ -2,7 +2,7 @@ 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) +@ref[Time aware operators](../index.md#time-aware-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/initialDelay.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/initialDelay.md index 3a61dd33f1..6565c62325 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/initialDelay.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/initialDelay.md @@ -2,7 +2,7 @@ Delays the initial element by the specified duration. -@ref[Timer driven stages](../index.md#timer-driven-stages) +@ref[Timer driven operators](../index.md#timer-driven-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/initialTimeout.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/initialTimeout.md index b3cfffd0c9..9caca6b94b 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/initialTimeout.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/initialTimeout.md @@ -1,8 +1,8 @@ # 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 operators before the provided timeout, the stream is failed with a `TimeoutException`. -@ref[Time aware stages](../index.md#time-aware-stages) +@ref[Time aware operators](../index.md#time-aware-operators) @@@div { .group-scala } @@ -14,7 +14,7 @@ If the first element has not passed through this stage before the provided timeo ## Description -If the first element has not passed through this stage before the provided timeout, the stream is failed +If the first element has not passed through this operators before the provided timeout, the stream is failed with a `TimeoutException`. diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/interleave.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/interleave.md index d536407ead..0ec3535d6a 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/interleave.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/interleave.md @@ -2,7 +2,7 @@ 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) +@ref[Fan-in operators](../index.md#fan-in-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/keepAlive.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/keepAlive.md index d3172224cb..1573518613 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/keepAlive.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/keepAlive.md @@ -2,7 +2,7 @@ Injects additional (configured) elements if upstream does not emit for a configured amount of time. -@ref[Time aware stages](../index.md#time-aware-stages) +@ref[Time aware operators](../index.md#time-aware-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mapError.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mapError.md index a6100b8c91..66c0c36890 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mapError.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mapError.md @@ -1,6 +1,6 @@ # 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 operators can be used to transform an error signal to a different one *without* logging it as an error in the process. @ref[Simple operators](../index.md#simple-operators) @@ -14,12 +14,12 @@ While similar to `recover` this stage can be used to transform an error signal t ## Description -While similar to `recover` this stage can be used to transform an error signal to a different one *without* logging +While similar to `recover` this operators 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. +This operators 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. diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/merge.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/merge.md index 9a50ba9a45..39181a746e 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/merge.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/merge.md @@ -2,7 +2,7 @@ Merge multiple sources. -@ref[Fan-in stages](../index.md#fan-in-stages) +@ref[Fan-in operators](../index.md#fan-in-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mergeLatest.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mergeLatest.md index 48634393e7..73f1e537c7 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mergeLatest.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mergeLatest.md @@ -2,7 +2,7 @@ Merge multiple sources. -@ref[Fan-in stages](../index.md#fan-in-stages) +@ref[Fan-in operators](../index.md#fan-in-operators) ## Signature diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mergePreferred.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mergePreferred.md index 441620d813..bf35942353 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mergePreferred.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mergePreferred.md @@ -2,7 +2,7 @@ Merge multiple sources. -@ref[Fan-in stages](../index.md#fan-in-stages) +@ref[Fan-in operators](../index.md#fan-in-operators) ## Signature diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mergePrioritized.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mergePrioritized.md index ab67e81df6..d8f31b7e81 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mergePrioritized.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mergePrioritized.md @@ -2,7 +2,7 @@ Merge multiple sources. -@ref[Fan-in stages](../index.md#fan-in-stages) +@ref[Fan-in operators](../index.md#fan-in-operators) ## Signature diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mergeSorted.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mergeSorted.md index 6012e7affd..2e64d438d0 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mergeSorted.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/mergeSorted.md @@ -2,7 +2,7 @@ Merge multiple sources. -@ref[Fan-in stages](../index.md#fan-in-stages) +@ref[Fan-in operators](../index.md#fan-in-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/monitor.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/monitor.md index e8bd3d0e2f..e60264356f 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/monitor.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/monitor.md @@ -1,8 +1,8 @@ # monitor -Materializes to a `FlowMonitor` that monitors messages flowing through or completion of the stage. +Materializes to a `FlowMonitor` that monitors messages flowing through or completion of the operators. -@ref[Watching status stages](../index.md#watching-status-stages) +@ref[Watching status operators](../index.md#watching-status-operators) @@@div { .group-scala } @@ -14,7 +14,7 @@ Materializes to a `FlowMonitor` that monitors messages flowing through or comple ## Description -Materializes to a `FlowMonitor` that monitors messages flowing through or completion of the stage. The stage otherwise +Materializes to a `FlowMonitor` that monitors messages flowing through or completion of the operators. The operators otherwise passes through elements unchanged. Note that the `FlowMonitor` inserts a memory barrier every time it processes an event, and may therefore affect performance. diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/orElse.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/orElse.md index c899da3825..63b0addc49 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/orElse.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/orElse.md @@ -2,7 +2,7 @@ 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) +@ref[Fan-in operators](../index.md#fan-in-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/partition.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/partition.md index b6933875ba..a9c6d01660 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/partition.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/partition.md @@ -2,7 +2,7 @@ Fan-out the stream to several streams. -@ref[Fan-out stages](../index.md#fan-out-stages) +@ref[Fan-out operators](../index.md#fan-out-operators) ## Signature diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/prefixAndTail.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/prefixAndTail.md index bb8801636a..7bd1a9f011 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/prefixAndTail.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/prefixAndTail.md @@ -2,7 +2,7 @@ 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) +@ref[Nesting and flattening operators](../index.md#nesting-and-flattening-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/prepend.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/prepend.md index 7422d3ce03..da8439c03e 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/prepend.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/prepend.md @@ -2,7 +2,7 @@ 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) +@ref[Fan-in operators](../index.md#fan-in-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/recoverWithRetries.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/recoverWithRetries.md index 3595732703..a51b7c6ef2 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/recoverWithRetries.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/recoverWithRetries.md @@ -20,7 +20,7 @@ it is fed into the *pf* and a new Source may be materialized. Note that if you p 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. +This operators can recover the failure signal, but not the skipped elements, which will be dropped. @@@div { .callout } diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/splitAfter.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/splitAfter.md index 848a4716d9..df056f07d5 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/splitAfter.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/splitAfter.md @@ -2,7 +2,7 @@ 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) +@ref[Nesting and flattening operators](../index.md#nesting-and-flattening-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/splitWhen.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/splitWhen.md index aada04b346..8c5dd2379b 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/splitWhen.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/splitWhen.md @@ -2,7 +2,7 @@ Split off elements into a new substream whenever a predicate function return `true`. -@ref[Nesting and flattening stages](../index.md#nesting-and-flattening-stages) +@ref[Nesting and flattening operators](../index.md#nesting-and-flattening-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/takeWithin.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/takeWithin.md index fca965e045..25a0191abc 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/takeWithin.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/takeWithin.md @@ -2,7 +2,7 @@ Pass elements downstream within a timeout and then complete. -@ref[Timer driven stages](../index.md#timer-driven-stages) +@ref[Timer driven operators](../index.md#timer-driven-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/unzip.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/unzip.md index 3f0a3fd34b..8e1a3d8589 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/unzip.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/unzip.md @@ -2,7 +2,7 @@ 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) +@ref[Fan-out operators](../index.md#fan-out-operators) ## Signature diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/unzipWith.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/unzipWith.md index 4f575d1637..9d2f6c5420 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/unzipWith.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/unzipWith.md @@ -2,7 +2,7 @@ Splits each element of input into multiple downstreams using a function -@ref[Fan-out stages](../index.md#fan-out-stages) +@ref[Fan-out operators](../index.md#fan-out-operators) ## Signature diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/watchTermination.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/watchTermination.md index c7cc6ee68e..727b46b82a 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/watchTermination.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/watchTermination.md @@ -1,8 +1,8 @@ # 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. +Materializes to a @scala[`Future`] @java[`CompletionStage`] that will be completed with Done or failed depending whether the upstream of the operators has been completed or failed. -@ref[Watching status stages](../index.md#watching-status-stages) +@ref[Watching status operators](../index.md#watching-status-operators) @@@div { .group-scala } @@ -14,8 +14,8 @@ Materializes to a @scala[`Future`] @java[`CompletionStage`] that will be complet ## 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. -The stage otherwise passes through elements unchanged. +Materializes to a @scala[`Future`] @java[`CompletionStage`] that will be completed with Done or failed depending whether the upstream of the operators has been completed or failed. +The operators otherwise passes through elements unchanged. @@@div { .callout } diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/zip.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/zip.md index 635c0a7ccd..97d5050516 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/zip.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/zip.md @@ -2,7 +2,7 @@ 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) +@ref[Fan-in operators](../index.md#fan-in-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/zipWith.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/zipWith.md index dbff19d025..be04c3d230 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/zipWith.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/zipWith.md @@ -2,7 +2,7 @@ Combines elements from multiple sources through a `combine` function and passes the returned value downstream. -@ref[Fan-in stages](../index.md#fan-in-stages) +@ref[Fan-in operators](../index.md#fan-in-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/zipWithIndex.md b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/zipWithIndex.md index 3d082221bf..0301eecbb9 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/zipWithIndex.md +++ b/akka-docs/src/main/paradox/stream/operators/Source-or-Flow/zipWithIndex.md @@ -2,7 +2,7 @@ Zips elements of current flow with its indices. -@ref[Fan-in stages](../index.md#fan-in-stages) +@ref[Fan-in operators](../index.md#fan-in-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source/actorRef.md b/akka-docs/src/main/paradox/stream/operators/Source/actorRef.md index 6a71a3272b..a3333a73e6 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source/actorRef.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/actorRef.md @@ -2,7 +2,7 @@ Materialize an `ActorRef`, sending messages to it will emit them on the stream. -@ref[Source stages](../index.md#source-stages) +@ref[Source operators](../index.md#source-operators) @@@ div { .group-scala } ## Signature diff --git a/akka-docs/src/main/paradox/stream/operators/Source/asSubscriber.md b/akka-docs/src/main/paradox/stream/operators/Source/asSubscriber.md index 624e948dcf..3d9ae97be5 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source/asSubscriber.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/asSubscriber.md @@ -2,7 +2,7 @@ Integration with Reactive Streams, materializes into a `org.reactivestreams.Subscriber`. -@ref[Source stages](../index.md#source-stages) +@ref[Source operators](../index.md#source-operators) @@@ div { .group-scala } ## Signature diff --git a/akka-docs/src/main/paradox/stream/operators/Source/combine.md b/akka-docs/src/main/paradox/stream/operators/Source/combine.md index c664b81631..f4045abfe2 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source/combine.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/combine.md @@ -2,7 +2,7 @@ Combine several sources, using a given strategy such as merge or concat, into one source. -@ref[Source stages](../index.md#source-stages) +@ref[Source operators](../index.md#source-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source/cycle.md b/akka-docs/src/main/paradox/stream/operators/Source/cycle.md index a3b4d51650..99189fc2b8 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source/cycle.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/cycle.md @@ -2,7 +2,7 @@ Stream iterator in cycled manner. -@ref[Source stages](../index.md#source-stages) +@ref[Source operators](../index.md#source-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source/empty.md b/akka-docs/src/main/paradox/stream/operators/Source/empty.md index 00f7b3f776..00da4208cc 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source/empty.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/empty.md @@ -2,7 +2,7 @@ Complete right away without ever emitting any elements. -@ref[Source stages](../index.md#source-stages) +@ref[Source operators](../index.md#source-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source/failed.md b/akka-docs/src/main/paradox/stream/operators/Source/failed.md index 499530edb7..f057950178 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source/failed.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/failed.md @@ -2,7 +2,7 @@ Fail directly with a user specified exception. -@ref[Source stages](../index.md#source-stages) +@ref[Source operators](../index.md#source-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source/from.md b/akka-docs/src/main/paradox/stream/operators/Source/from.md index a799ebb59e..cfc6858d2f 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source/from.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/from.md @@ -2,7 +2,7 @@ Stream the values of an `Iterable`. -@ref[Source stages](../index.md#source-stages) +@ref[Source operators](../index.md#source-operators) ## Description diff --git a/akka-docs/src/main/paradox/stream/operators/Source/fromCompletionStage.md b/akka-docs/src/main/paradox/stream/operators/Source/fromCompletionStage.md index 48d7678510..939cd24dfc 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source/fromCompletionStage.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/fromCompletionStage.md @@ -2,7 +2,7 @@ Send the single value of the `CompletionStage` when it completes and there is demand. -@ref[Source stages](../index.md#source-stages) +@ref[Source operators](../index.md#source-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source/fromFuture.md b/akka-docs/src/main/paradox/stream/operators/Source/fromFuture.md index eda090565f..4588c78d53 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source/fromFuture.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/fromFuture.md @@ -2,7 +2,7 @@ Send the single value of the `Future` when it completes and there is demand. -@ref[Source stages](../index.md#source-stages) +@ref[Source operators](../index.md#source-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source/fromFutureSource.md b/akka-docs/src/main/paradox/stream/operators/Source/fromFutureSource.md index 5ba3e51e32..1fa3254170 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source/fromFutureSource.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/fromFutureSource.md @@ -2,7 +2,7 @@ Streams the elements of the given future source once it successfully completes. -@ref[Source stages](../index.md#source-stages) +@ref[Source operators](../index.md#source-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source/fromIterator.md b/akka-docs/src/main/paradox/stream/operators/Source/fromIterator.md index 6652fa7a14..c31325b80c 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source/fromIterator.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/fromIterator.md @@ -2,7 +2,7 @@ Stream the values from an `Iterator`, requesting the next value when there is demand. -@ref[Source stages](../index.md#source-stages) +@ref[Source operators](../index.md#source-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source/fromPublisher.md b/akka-docs/src/main/paradox/stream/operators/Source/fromPublisher.md index dcc0514acf..67aa909022 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source/fromPublisher.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/fromPublisher.md @@ -2,7 +2,7 @@ Integration with Reactive Streams, subscribes to a `org.reactivestreams.Publisher`. -@ref[Source stages](../index.md#source-stages) +@ref[Source operators](../index.md#source-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source/fromSourceCompletionStage.md b/akka-docs/src/main/paradox/stream/operators/Source/fromSourceCompletionStage.md index 40445e77c3..e4e11bc9e0 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source/fromSourceCompletionStage.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/fromSourceCompletionStage.md @@ -1,20 +1,20 @@ # fromSourceCompletionStage -Streams the elements of an asynchronous source once its given *completion* stage completes. +Streams the elements of an asynchronous source once its given *completion* operator completes. -@ref[Source stages](../index.md#source-stages) +@ref[Source operators](../index.md#source-operators) ## Signature ## Description -Streams the elements of an asynchronous source once its given *completion* stage completes. +Streams the elements of an asynchronous source once its given *completion* operator completes. If the *completion* fails the stream is failed with that exception. @@@div { .callout } -**emits** the next value from the asynchronous source, once its *completion stage* has completed +**emits** the next value from the asynchronous source, once its *completion operator* has completed **completes** after the asynchronous source completes diff --git a/akka-docs/src/main/paradox/stream/operators/Source/lazily.md b/akka-docs/src/main/paradox/stream/operators/Source/lazily.md index e7c7d228e7..8eaf664414 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source/lazily.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/lazily.md @@ -2,7 +2,7 @@ Defers creation and materialization of a `Source` until there is demand. -@ref[Source stages](../index.md#source-stages) +@ref[Source operators](../index.md#source-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source/lazilyAsync.md b/akka-docs/src/main/paradox/stream/operators/Source/lazilyAsync.md index dafefb601b..5709c6727a 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source/lazilyAsync.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/lazilyAsync.md @@ -2,7 +2,7 @@ Defers creation and materialization of a `CompletionStage` until there is demand. -@ref[Source stages](../index.md#source-stages) +@ref[Source operators](../index.md#source-operators) ## Signature diff --git a/akka-docs/src/main/paradox/stream/operators/Source/maybe.md b/akka-docs/src/main/paradox/stream/operators/Source/maybe.md index fc2c521598..85ae8bdb99 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source/maybe.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/maybe.md @@ -2,7 +2,7 @@ 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) +@ref[Source operators](../index.md#source-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source/queue.md b/akka-docs/src/main/paradox/stream/operators/Source/queue.md index 5378e22194..3fa4a03e5c 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source/queue.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/queue.md @@ -2,7 +2,7 @@ Materialize a `SourceQueue` onto which elements can be pushed for emitting from the source. -@ref[Source stages](../index.md#source-stages) +@ref[Source operators](../index.md#source-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source/range.md b/akka-docs/src/main/paradox/stream/operators/Source/range.md index 77b9f48772..ef44631c0b 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source/range.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/range.md @@ -2,7 +2,7 @@ Emit each integer in a range, with an option to take bigger steps than 1. -@ref[Source stages](../index.md#source-stages) +@ref[Source operators](../index.md#source-operators) ## Description diff --git a/akka-docs/src/main/paradox/stream/operators/Source/repeat.md b/akka-docs/src/main/paradox/stream/operators/Source/repeat.md index 09ca536d19..82df94d41e 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source/repeat.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/repeat.md @@ -2,7 +2,7 @@ Stream a single object repeatedly -@ref[Source stages](../index.md#source-stages) +@ref[Source operators](../index.md#source-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source/single.md b/akka-docs/src/main/paradox/stream/operators/Source/single.md index a30906d958..92dfdad3bc 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source/single.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/single.md @@ -2,7 +2,7 @@ Stream a single object -@ref[Source stages](../index.md#source-stages) +@ref[Source operators](../index.md#source-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source/tick.md b/akka-docs/src/main/paradox/stream/operators/Source/tick.md index 9b8e01fc23..b1a2f1d8e5 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source/tick.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/tick.md @@ -2,7 +2,7 @@ A periodical repetition of an arbitrary object. -@ref[Source stages](../index.md#source-stages) +@ref[Source operators](../index.md#source-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source/unfold.md b/akka-docs/src/main/paradox/stream/operators/Source/unfold.md index fd9c8a5b38..b634ea3ba8 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source/unfold.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/unfold.md @@ -2,7 +2,7 @@ Stream the result of a function as long as it returns a @scala[`Some`] @java[`Optional`]. -@ref[Source stages](../index.md#source-stages) +@ref[Source operators](../index.md#source-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source/unfoldAsync.md b/akka-docs/src/main/paradox/stream/operators/Source/unfoldAsync.md index d3cd81832c..79a465fe38 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source/unfoldAsync.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/unfoldAsync.md @@ -2,7 +2,7 @@ Just like `unfold` but the fold function returns a @scala[`Future`] @java[`CompletionStage`]. -@ref[Source stages](../index.md#source-stages) +@ref[Source operators](../index.md#source-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source/unfoldResource.md b/akka-docs/src/main/paradox/stream/operators/Source/unfoldResource.md index e2b977d3a0..e5a4c21635 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source/unfoldResource.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/unfoldResource.md @@ -2,7 +2,7 @@ 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) +@ref[Source operators](../index.md#source-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source/unfoldResourceAsync.md b/akka-docs/src/main/paradox/stream/operators/Source/unfoldResourceAsync.md index 3efb9d830a..c79e7e020b 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source/unfoldResourceAsync.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/unfoldResourceAsync.md @@ -2,7 +2,7 @@ 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) +@ref[Source operators](../index.md#source-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source/zipN.md b/akka-docs/src/main/paradox/stream/operators/Source/zipN.md index 16b16305d1..c283b0bc49 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source/zipN.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/zipN.md @@ -2,7 +2,7 @@ Combine the elements of multiple streams into a stream of sequences. -@ref[Source stages](../index.md#source-stages) +@ref[Source operators](../index.md#source-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/Source/zipWithN.md b/akka-docs/src/main/paradox/stream/operators/Source/zipWithN.md index 921e0e27f0..cfed23b9f6 100644 --- a/akka-docs/src/main/paradox/stream/operators/Source/zipWithN.md +++ b/akka-docs/src/main/paradox/stream/operators/Source/zipWithN.md @@ -2,7 +2,7 @@ Combine the elements of multiple streams into a stream of sequences using a combiner function. -@ref[Source stages](../index.md#source-stages) +@ref[Source operators](../index.md#source-operators) @@@div { .group-scala } diff --git a/akka-docs/src/main/paradox/stream/operators/index.md b/akka-docs/src/main/paradox/stream/operators/index.md index 625911a391..0f31d28c37 100644 --- a/akka-docs/src/main/paradox/stream/operators/index.md +++ b/akka-docs/src/main/paradox/stream/operators/index.md @@ -1,7 +1,7 @@ # Operators -## Source stages +## Source operators These built-in sources are available from @scala[`akka.stream.scaladsl.Source`] @java[`akka.stream.javadsl.Source`]: @@ -19,7 +19,7 @@ These built-in sources are available from @scala[`akka.stream.scaladsl.Source`] |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[fromSourceCompletionStage](Source/fromSourceCompletionStage.md)|Streams the elements of an asynchronous source once its given *completion* operator 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.| @@ -35,7 +35,7 @@ These built-in sources are available from @scala[`akka.stream.scaladsl.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 +## Sink operators These built-in sinks are available from @scala[`akka.stream.scaladsl.Sink`] @java[`akka.stream.javadsl.Sink`]: @@ -66,7 +66,7 @@ These built-in sinks are available from @scala[`akka.stream.scaladsl.Sink`] @jav ## 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 +`StreamConverters`. As they are blocking APIs the implementations of these operators are run on a separate dispatcher configured through the `akka.stream.blocking-io-dispatcher`. @@@ warning @@ -109,10 +109,10 @@ Sources and sinks for reading and writing files can be found on `FileIO`. ## Simple operators -These stages can transform the rate of incoming elements since there are stages that emit multiple elements for a +These operators can transform the rate of incoming elements since there are operators 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 +rate is affected. This is in contrast with [detached operators](#backpressure-aware-operators) which can change their processing behavior depending on being backpressured by downstream or not. | |Operator|Description| @@ -136,7 +136,7 @@ depending on being backpressured by downstream or not. |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[mapError](Source-or-Flow/mapError.md)|While similar to `recover` this operators 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.| @@ -151,7 +151,7 @@ depending on being backpressured by downstream or not. |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 +## Flow operators composed of Sinks and Sources @@ -162,7 +162,7 @@ depending on being backpressured by downstream or not. ## Asynchronous operators -These stages encapsulate an asynchronous computation, properly handling backpressure while taking care of the asynchronous +These operators 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| @@ -171,9 +171,9 @@ operation at the same time (usually handling the completion of a @scala[`Future` |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 +## Timer driven operators -These stages process elements using timers, delaying, dropping or grouping elements for certain time durations. +These operators process elements using timers, delaying, dropping or grouping elements for certain time durations. | |Operator|Description| |--|--|--| @@ -184,9 +184,9 @@ These stages process elements using timers, delaying, dropping or grouping eleme |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 +## Backpressure aware operators -These stages are aware of the backpressure provided by their downstreams and able to adapt their behavior to that signal. +These operators are aware of the backpressure provided by their downstreams and able to adapt their behavior to that signal. | |Operator|Description| |--|--|--| @@ -198,9 +198,9 @@ These stages are aware of the backpressure provided by their downstreams and abl |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 +## Nesting and flattening operators -These stages either take a stream and turn it into a stream of streams (nesting) or they take a stream that contains +These operators 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. @@ -214,21 +214,21 @@ See the [Substreams](stream-substream.md) page for more detail and code samples. |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 +## Time aware operators -Those stages operate taking time into consideration. +Those operators 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[initialTimeout](Source-or-Flow/initialTimeout.md)|If the first element has not passed through this operators 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 +## Fan-in operators -These stages take multiple streams as their input and provide a single output combining the elements from all of +These operators take multiple streams as their input and provide a single output combining the elements from all of the inputs in different ways. | |Operator|Description| @@ -243,18 +243,18 @@ the inputs in different ways. |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 +## Watching status operators | |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.| +|Source/Flow|@ref[monitor](Source-or-Flow/monitor.md)|Materializes to a `FlowMonitor` that monitors messages flowing through or completion of the operators.| +|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 operators has been completed or failed.| -## Actor interop stages +## Actor interop operators -Stages and operations meant for inter-operating between Akka Streams and Actors: +Operators meant for inter-operating between Akka Streams and Actors: | |Operator|Description| diff --git a/akka-docs/src/main/paradox/stream/stream-composition.md b/akka-docs/src/main/paradox/stream/stream-composition.md index 2cfc5f2ed5..ae74770dab 100644 --- a/akka-docs/src/main/paradox/stream/stream-composition.md +++ b/akka-docs/src/main/paradox/stream/stream-composition.md @@ -19,16 +19,16 @@ the modularity aspects of the library. ## Basics of composition and modularity Every operator used in Akka Streams can be imagined as a "box" with input and output ports where elements to -be processed arrive and leave the stage. In this view, a `Source` is nothing else than a "box" with a single +be processed arrive and leave the operator. In this view, a `Source` is nothing else than a "box" with a single output port, or, a `BidiFlow` is a "box" with exactly two input and two output ports. In the figure below -we illustrate the most common used stages viewed as "boxes". +we illustrate the most commonly used operators viewed as "boxes". ![compose_shapes.png](../images/compose_shapes.png) -The *linear* stages are `Source`, `Sink` +The *linear* operators are `Source`, `Sink` and `Flow`, as these can be used to compose strict chains of operators. -Fan-in and Fan-out stages have usually multiple input or multiple output ports, therefore they allow to build -more complex graph layouts, not only chains. `BidiFlow` stages are usually useful in IO related tasks, where +Fan-in and Fan-out operators have usually multiple input or multiple output ports, therefore they allow to build +more complex graph layouts, not only chains. `BidiFlow` operators are usually useful in IO related tasks, where there are input and output channels to be handled. Due to the specific shape of `BidiFlow` it is easy to stack them on top of each other to build a layered protocol for example. The `TLS` support in Akka is for example implemented as a `BidiFlow`. @@ -40,7 +40,7 @@ to interact with. One good example is the `Http` server component, which is enco `BidiFlow` which interfaces with the client TCP connection using an input-output port pair accepting and sending `ByteString` s, while its upper ports emit and receive `HttpRequest` and `HttpResponse` instances. -The following figure demonstrates various composite stages, that contain various other type of stages internally, but +The following figure demonstrates various composite operators, that contain various other type of operators internally, but hiding them behind a *shape* that looks like a `Source`, `Flow`, etc. ![compose_composites.png](../images/compose_composites.png) @@ -127,7 +127,7 @@ As a first example, let's look at a more complex layout: ![compose_graph.png](../images/compose_graph.png) The diagram shows a `RunnableGraph` (remember, if there are no unwired ports, the graph is closed, and therefore -can be materialized) that encapsulates a non-trivial stream processing network. It contains fan-in, fan-out stages, +can be materialized) that encapsulates a non-trivial stream processing network. It contains fan-in, fan-out operators, directed and non-directed cycles. The `runnable()` method of the `GraphDSL` object allows the creation of a general, closed, and runnable graph. For example the network on the diagram can be realized like this: @@ -139,7 +139,7 @@ Java In the code above we used the implicit port numbering feature (to make the graph more readable and similar to the diagram) and we imported `Source` s, `Sink` s and `Flow` s explicitly. It is possible to refer to the ports -explicitly, and it is not necessary to import our linear stages via `add()`, so another version might look like this: +explicitly, and it is not necessary to import our linear operators via `add()`, so another version might look like this: Scala : @@snip [CompositionDocSpec.scala]($code$/scala/docs/stream/CompositionDocSpec.scala) { #complex-graph-alt } @@ -244,7 +244,7 @@ needs to return a different object that provides the necessary interaction capab * a materialized value, optionally providing a controlled interaction capability with the network Unlike actors though, each of the operators might provide a materialized value, so when we compose multiple -stages or modules, we need to combine the materialized value as well (there are default rules which make this easier, +operators or modules, we need to combine the materialized value as well (there are default rules which make this easier, for example *to()* and *via()* takes care of the most common case of taking the materialized value to the left. See @ref:[Combining materialized values](stream-flows-and-basics.md#flow-combine-mat) for details). We demonstrate how this works by a code example and a diagram which graphically demonstrates what is happening. @@ -311,8 +311,8 @@ of combining materialized values without nesting and hierarchy involved. We have seen that we can use `named()` to introduce a nesting level in the fluid DSL (and also explicit nesting by using `create()` from `GraphDSL`). Apart from having the effect of adding a nesting level, `named()` is actually a shorthand for calling `withAttributes(Attributes.name("someName"))`. Attributes provide a way to fine-tune certain -aspects of the materialized running entity. For example buffer sizes for asynchronous stages can be controlled via -attributes (see @ref:[Buffers for asynchronous stages](stream-rate.md#async-stream-buffers)). When it comes to hierarchic composition, attributes are inherited +aspects of the materialized running entity. For example buffer sizes for asynchronous operators can be controlled via +attributes (see @ref:[Buffers for asynchronous operators](stream-rate.md#async-stream-buffers)). When it comes to hierarchic composition, attributes are inherited by nested modules, unless they override them with a custom value. The code below, a modification of an earlier example sets the `inputBuffer` attribute on certain modules, but not @@ -327,7 +327,7 @@ Java The effect is, that each module inherits the `inputBuffer` attribute from its enclosing parent, unless it has the same attribute explicitly set. `nestedSource` gets the default attributes from the materializer itself. `nestedSink` on the other hand has this attribute set, so it will be used by all nested modules. `nestedFlow` will inherit from `nestedSink` -except the `map` stage which has again an explicitly provided attribute overriding the inherited one. +except the `map` operator which has again an explicitly provided attribute overriding the inherited one. ![compose_attributes.png](../images/compose_attributes.png) diff --git a/akka-docs/src/main/paradox/stream/stream-cookbook.md b/akka-docs/src/main/paradox/stream/stream-cookbook.md index f83ba20179..bf160b143d 100644 --- a/akka-docs/src/main/paradox/stream/stream-cookbook.md +++ b/akka-docs/src/main/paradox/stream/stream-cookbook.md @@ -113,13 +113,13 @@ of the stream. This recipe uses a @ref[`GraphStage`](stream-customize.md) to define a custom Akka Stream operator, to host a mutable `MessageDigest` class (part of the Java Cryptography API) and update it with the bytes arriving from the stream. When the stream starts, the `onPull` handler of the -stage is called, which bubbles up the `pull` event to its upstream. As a response to this pull, a ByteString +operator is called, which bubbles up the `pull` event to its upstream. As a response to this pull, a ByteString chunk will arrive (`onPush`) which we use to update the digest, then it will pull for the next chunk. Eventually the stream of `ByteString` s depletes and we get a notification about this event via `onUpstreamFinish`. At this point we want to emit the digest value, but we cannot do it with `push` in this handler directly since there may be no downstream demand. Instead we call `emit` which will temporarily replace the handlers, emit the provided value when -demand comes in and then reset the stage state. It will then complete the stage. +demand comes in and then reset the operator state. It will then complete the operator. Scala : @@snip [RecipeDigest.scala]($code$/scala/docs/stream/cookbook/RecipeDigest.scala) { #calculating-digest } @@ -290,7 +290,7 @@ The graph consists of a `Balance` node which is a special fan-out operation that downstream consumers. In a `for` loop we wire all of our desired workers as outputs of this balancer element, then we wire the outputs of these workers to a `Merge` element that will collect the results from the workers. -To make the worker stages run in parallel we mark them as asynchronous with *async*. +To make the worker operators run in parallel we mark them as asynchronous with *async*. Scala : @@snip [RecipeWorkerPool.scala]($code$/scala/docs/stream/cookbook/RecipeWorkerPool.scala) { #worker-pool } @@ -451,7 +451,7 @@ for this actor. the same sequence, but capping the size of `ByteString` s. In other words we want to slice up `ByteString` s into smaller chunks if they exceed a size threshold. -This can be achieved with a single @ref[`GraphStage`](stream-customize.md) to define a custom Akka Stream operator. The main logic of our stage is in `emitChunk()` +This can be achieved with a single @ref[`GraphStage`](stream-customize.md) to define a custom Akka Stream operator. The main logic of our operator is in `emitChunk()` which implements the following logic: * if the buffer is empty, and upstream is not closed we pull for more bytes, if it is closed we complete diff --git a/akka-docs/src/main/paradox/stream/stream-customize.md b/akka-docs/src/main/paradox/stream/stream-customize.md index 59655d8f71..17daa8d666 100644 --- a/akka-docs/src/main/paradox/stream/stream-customize.md +++ b/akka-docs/src/main/paradox/stream/stream-customize.md @@ -13,7 +13,7 @@ To use Akka Streams, add the module to your project: ## Introduction While the processing vocabulary of Akka Streams is quite rich (see the @ref:[Streams Cookbook](stream-cookbook.md) for examples) it -is sometimes necessary to define new transformation stages either because some functionality is missing from the +is sometimes necessary to define new transformation operators either because some functionality is missing from the stock operations, or for performance reasons. In this part we show how to build custom operators and graph junctions of various kinds. @@ -30,11 +30,11 @@ might be easy to make with a custom @ref[`GraphStage`](stream-customize.md) The `GraphStage` abstraction can be used to create arbitrary operators with any number of input or output ports. It is a counterpart of the `GraphDSL.create()` method which creates new stream processing -stages by composing others. Where `GraphStage` differs is that it creates a stage that is itself not divisible into +operators by composing others. Where `GraphStage` differs is that it creates an operator that is itself not divisible into smaller ones, and allows state to be maintained inside it in a safe way. As a first motivating example, we will build a new `Source` that will emit numbers from 1 until it is -cancelled. To start, we need to define the "interface" of our stage, which is called *shape* in Akka Streams terminology +cancelled. To start, we need to define the "interface" of our operator, which is called *shape* in Akka Streams terminology (this is explained in more detail in the section @ref:[Modularity, Composition and Hierarchy](stream-composition.md)). This is how this looks like: Scala @@ -43,8 +43,8 @@ Scala Java : @@snip [GraphStageDocTest.java]($code$/java/jdocs/stream/GraphStageDocTest.java) { #simple-source } -As you see, in itself the `GraphStage` only defines the ports of this stage and a shape that contains the ports. -It also has, a currently unimplemented method called `createLogic`. If you recall, stages are reusable in multiple +As you see, in itself the `GraphStage` only defines the ports of this operator and a shape that contains the ports. +It also has, a currently unimplemented method called `createLogic`. If you recall, operators are reusable in multiple materializations, each resulting in a different executing entity. In the case of `GraphStage` the actual running logic is modeled as an instance of a `GraphStageLogic` which will be created by the materializer by calling the `createLogic` method. In other words, all we need to do is to create a suitable logic that will emit the @@ -62,7 +62,7 @@ To receive the necessary events one needs to register a subclass of @scala[`OutH (`Outlet`). This handler will receive events related to the lifecycle of the port. In our case we need to override `onPull()` which indicates that we are free to emit a single element. There is another callback, `onDownstreamFinish()` which is called if the downstream cancelled. Since the default behavior of that callback is -to stop the stage, we don't need to override it. In the `onPull` callback we will emit the next number. This +to stop the operator, we don't need to override it. In the `onPull` callback we will emit the next number. This is how it looks like in the end: Scala @@ -80,8 +80,8 @@ Scala Java : @@snip [GraphStageDocTest.java]($code$/java/jdocs/stream/GraphStageDocTest.java) { #simple-source-usage } -Similarly, to create a custom `Sink` one can register a subclass `InHandler` with the stage `Inlet`. -The `onPush()` callback is used to signal the handler a new element has been pushed to the stage, +Similarly, to create a custom `Sink` one can register a subclass `InHandler` with the operator `Inlet`. +The `onPush()` callback is used to signal the handler a new element has been pushed to the operator, and can hence be grabbed and used. `onPush()` can be overridden to provide custom behavior. Please note, most Sinks would need to request upstream elements as soon as they are created: this can be done by calling `pull(inlet)` in the `preStart()` callback. @@ -95,7 +95,7 @@ Java ### Port states, @scala[InHandler] @java[AbstractInHandler] and @scala[OutHandler] @java[AbstractOutHandler] -In order to interact with a port (`Inlet` or `Outlet`) of the stage we need to be able to receive events +In order to interact with a port (`Inlet` or `Outlet`) of the operator we need to be able to receive events and generate new events belonging to the port. From the `GraphStageLogic` the following operations are available on an output port: @@ -109,7 +109,7 @@ output port using `setHandler(out,handler)`. This handler has two callbacks: * `onPull()` is called when the output port is ready to emit the next element, `push(out, elem)` is now allowed to be called on this port. * `onDownstreamFinish()` is called once the downstream has cancelled and no longer allows messages to be pushed to it. -No more `onPull()` will arrive after this event. If not overridden this will default to stopping the stage. +No more `onPull()` will arrive after this event. If not overridden this will default to stopping the operator. Also, there are two query methods available for output ports: @@ -137,9 +137,9 @@ input port using `setHandler(in, handler)`. This handler has three callbacks: `grab(in)` and/or call `pull(in)` on the port to request the next element. It is not mandatory to grab the element, but if it is pulled while the element has not been grabbed it will drop the buffered element. * `onUpstreamFinish()` is called once the upstream has completed and no longer can be pulled for new elements. -No more `onPush()` will arrive after this event. If not overridden this will default to stopping the stage. +No more `onPush()` will arrive after this event. If not overridden this will default to stopping the operator. * `onUpstreamFailure()` is called if the upstream failed with an exception and no longer can be pulled for new elements. -No more `onPush()` will arrive after this event. If not overridden this will default to failing the stage. +No more `onPush()` will arrive after this event. If not overridden this will default to failing the operator. Also, there are three query methods available for input ports: @@ -154,7 +154,7 @@ in that state. ![inport_transitions.png](../images/inport_transitions.png) -Finally, there are two methods available for convenience to complete the stage and all of its ports: +Finally, there are two methods available for convenience to complete the operator and all of its ports: * `completeStage()` is equivalent to closing all output ports and cancelling all input ports. * `failStage(exception)` is equivalent to failing all output ports and cancelling all input ports. @@ -173,19 +173,19 @@ one or more elements when there is demand, and then reinstalls the current handl more elements as they are pushed and allows the handler to react once the requested number of elements has been read. * `abortEmitting()` and `abortReading()` which will cancel an ongoing emit or read -Note that since the above methods are implemented by temporarily replacing the handlers of the stage you should never +Note that since the above methods are implemented by temporarily replacing the handlers of the operator you should never call `setHandler` while they are running `emit` or `read` as that interferes with how they are implemented. The following methods are safe to call after invoking `emit` and `read` (and will lead to actually running the operation when those are done): `complete(out)`, `completeStage()`, `emit`, `emitMultiple`, `abortEmitting()` and `abortReading()` -An example of how this API simplifies a stage can be found below in the second version of the `Duplicator`. +An example of how this API simplifies an operator can be found below in the second version of the `Duplicator`. ### Custom linear operators using GraphStage To define custom linear operators, you should extend `GraphStage` using `FlowShape` which has one input and one output. -Such a stage can be illustrated as a box with two flows as it is +Such an operator can be illustrated as a box with two flows as it is seen in the illustration below. Demand flowing upstream leading to elements flowing downstream. @@ -207,7 +207,7 @@ Java Map is a typical example of a one-to-one transformation of a stream where demand is passed along upstream elements passed on downstream. -To demonstrate a many-to-one stage we will implement +To demonstrate a many-to-one operator we will implement filter. The conceptual wiring of `Filter` looks like this: ![graph_stage_filter.png](../images/graph_stage_filter.png) @@ -223,12 +223,12 @@ Scala Java : @@snip [GraphStageDocTest.java]($code$/java/jdocs/stream/GraphStageDocTest.java) { #many-to-one } -To complete the picture we define a one-to-many transformation as the next step. We chose a straightforward example stage -that emits every upstream element twice downstream. The conceptual wiring of this stage looks like this: +To complete the picture we define a one-to-many transformation as the next step. We chose a straightforward example operator +that emits every upstream element twice downstream. The conceptual wiring of this operator looks like this: ![graph_stage_duplicate.png](../images/graph_stage_duplicate.png) -This is a stage that has state: an option with the last element it has seen indicating if it +This is an operator that has state: an option with the last element it has seen indicating if it has duplicated this last element already or not. We must also make sure to emit the extra element if the upstream completes. @@ -238,10 +238,10 @@ Scala Java : @@snip [GraphStageDocTest.java]($code$/java/jdocs/stream/GraphStageDocTest.java) { #one-to-many } -In this case a pull from downstream might be consumed by the stage itself rather -than passed along upstream as the stage might contain an element it wants to +In this case a pull from downstream might be consumed by the operator itself rather +than passed along upstream as the operator might contain an element it wants to push. Note that we also need to handle the case where the upstream closes while -the stage still has elements it wants to push downstream. This is done by +the operator still has elements it wants to push downstream. This is done by overriding *onUpstreamFinish* in the @scala[*InHandler*] @java[*AbstractInHandler*] and provide custom logic that should happen when the upstream has been finished. @@ -255,21 +255,21 @@ Scala Java : @@snip [GraphStageDocTest.java]($code$/java/jdocs/stream/GraphStageDocTest.java) { #simpler-one-to-many } -Finally, to demonstrate all of the stages above, we put them together into a processing chain, +Finally, to demonstrate all of the operators above, we put them together into a processing chain, which conceptually would correspond to the following structure: ![graph_stage_chain.png](../images/graph_stage_chain.png) -In code this is only a few lines, using the `via` use our custom stages in a stream: +In code this is only a few lines, using the `via` use our custom operators in a stream: Scala -: @@snip [GraphStageDocSpec.scala]($code$/scala/docs/stream/GraphStageDocSpec.scala) { #graph-stage-chain } +: @@snip [GraphStageDocSpec.scala]($code$/scala/docs/stream/GraphStageDocSpec.scala) { #graph-operator-chain } Java -: @@snip [GraphStageDocTest.java]($code$/java/jdocs/stream/GraphStageDocTest.java) { #graph-stage-chain } +: @@snip [GraphStageDocTest.java]($code$/java/jdocs/stream/GraphStageDocTest.java) { #graph-operator-chain } If we attempt to draw the sequence of events, it shows that there is one "event token" -in circulation in a potential chain of stages, just like our conceptual "railroad tracks" representation predicts. +in circulation in a potential chain of operators, just like our conceptual "railroad tracks" representation predicts. ![graph_stage_tracks_1.png](../images/graph_stage_tracks_1.png) @@ -278,22 +278,22 @@ in circulation in a potential chain of stages, just like our conceptual "railroa Completion handling usually (but not exclusively) comes into the picture when operators need to emit a few more elements after their upstream source has been completed. We have seen an example of this in our first `Duplicator` implementation where the last element needs to be doubled even after the upstream neighbor -stage has been completed. This can be done by overriding the `onUpstreamFinish` method in @scala[`InHandler`]@java[`AbstractInHandler`]. +operator has been completed. This can be done by overriding the `onUpstreamFinish` method in @scala[`InHandler`]@java[`AbstractInHandler`]. -Stages by default automatically stop once all of their ports (input and output) have been closed externally or internally. -It is possible to opt out from this behavior by invoking `setKeepGoing(true)` (which is not supported from the stage’s -constructor and usually done in `preStart`). In this case the stage **must** be explicitly closed by calling `completeStage()` +Operators by default automatically stop once all of their ports (input and output) have been closed externally or internally. +It is possible to opt out from this behavior by invoking `setKeepGoing(true)` (which is not supported from the operator’s +constructor and usually done in `preStart`). In this case the operator **must** be explicitly closed by calling `completeStage()` or `failStage(exception)`. This feature carries the risk of leaking streams and actors, therefore it should be used with care. ### Logging inside GraphStages -Logging debug or other important information in your stages is often a very good idea, especially when developing -more advanced stages which may need to be debugged at some point. +Logging debug or other important information in your operators is often a very good idea, especially when developing +more advanced operators which may need to be debugged at some point. @@@ div { .group-scala } -The helper trait `akka.stream.stage.StageLogging` is provided to enable you to obtain a `LoggingAdapter` +The helper trait `akka.stream.operator.StageLogging` is provided to enable you to obtain a `LoggingAdapter` inside of a `GraphStage` as long as the `Materializer` you're using is able to provide you with a logger. In that sense, it serves a very similar purpose as `ActorLogging` does for Actors. @@ -302,26 +302,26 @@ In that sense, it serves a very similar purpose as `ActorLogging` does for Actor @@@ div { .group-java } You can extend the @unidoc[GraphStageLogicWithLogging] or @unidoc[TimerGraphStageLogicWithLogging] classes -instead of the usual `GraphStageLogic` to enable you to obtain a `LoggingAdapter` inside your stage as long as +instead of the usual `GraphStageLogic` to enable you to obtain a `LoggingAdapter` inside your operator as long as the `Materializer` you're using is able to provide you with a logger. @@@ @@@ note -Please note that you can always use a logging library directly inside a Stage. -Make sure to use an asynchronous appender however, to not accidentally block the stage when writing to files etc. +Please note that you can always use a logging library directly inside an operator. +Make sure to use an asynchronous appender however, to not accidentally block the operator when writing to files etc. See @ref:[Using the SLF4J API directly](../logging.md#slf4j-directly) for more details on setting up async appenders in SLF4J. @@@ -The stage then gets access to the `log` field which it can safely use from any `GraphStage` callbacks: +The operator then gets access to the `log` field which it can safely use from any `GraphStage` callbacks: Scala -: @@snip [GraphStageLoggingDocSpec.scala]($code$/scala/docs/stream/GraphStageLoggingDocSpec.scala) { #stage-with-logging } +: @@snip [GraphStageLoggingDocSpec.scala]($code$/scala/docs/stream/GraphStageLoggingDocSpec.scala) { #operator-with-logging } Java -: @@snip [GraphStageLoggingDocTest.java]($code$/java/jdocs/stream/GraphStageLoggingDocTest.java) { #stage-with-logging } +: @@snip [GraphStageLoggingDocTest.java]($code$/java/jdocs/stream/GraphStageLoggingDocTest.java) { #operator-with-logging } @@@ note @@ -337,13 +337,13 @@ the returned logic. Timers can be scheduled by calling one of `scheduleOnce(key, `schedulePeriodicallyWithInitialDelay(key,delay,period)` and passing an object as a key for that timer (can be any object, for example a `String`). The `onTimer(key)` method needs to be overridden and it will be called once the timer of `key` fires. It is possible to cancel a timer using `cancelTimer(key)` and check the status of a timer with -`isTimerActive(key)`. Timers will be automatically cleaned up when the stage completes. +`isTimerActive(key)`. Timers will be automatically cleaned up when the operator completes. Timers can not be scheduled from the constructor of the logic, but it is possible to schedule them from the `preStart()` lifecycle hook. -In this sample the stage toggles between open and closed, where open means no elements are passed through. The -stage starts out as closed but as soon as an element is pushed downstream the gate becomes open for a duration +In this sample the operator toggles between open and closed, where open means no elements are passed through. The +operator starts out as closed but as soon as an element is pushed downstream the gate becomes open for a duration of time during which it will consume and drop upstream messages: Scala @@ -356,7 +356,7 @@ Java In order to receive asynchronous events that are not arriving as stream elements (for example a completion of a future or a callback from a 3rd party API) one must acquire a `AsyncCallback` by calling `getAsyncCallback()` from the -stage logic. The method `getAsyncCallback` takes as a parameter a callback that will be called once the asynchronous +operator logic. The method `getAsyncCallback` takes as a parameter a callback that will be called once the asynchronous event fires. It is important to **not call the callback directly**, instead, the external API must call the `invoke(event)` method on the returned `AsyncCallback`. The execution engine will take care of calling the provided callback in a thread-safe way. The callback can safely access the state of the `GraphStageLogic` @@ -379,8 +379,8 @@ Java **This section is a stub and will be extended in the next release** **This is a @ref:[may change](../common/may-change.md) feature*** -It is possible to acquire an ActorRef that can be addressed from the outside of the stage, similarly how -`AsyncCallback` allows injecting asynchronous events into a stage logic. This reference can be obtained +It is possible to acquire an ActorRef that can be addressed from the outside of the operator, similarly how +`AsyncCallback` allows injecting asynchronous events into an operator logic. This reference can be obtained by calling `getStageActor(receive)` passing in a function that takes a `Pair` of the sender `ActorRef` and the received message. This reference can be used to watch other actors by calling its `watch(ref)` or `unwatch(ref)` methods. The reference can be also watched by external actors. The current limitations of this @@ -393,10 +393,10 @@ or `unwatch(ref)` methods. The reference can be also watched by external actors. ### Custom materialized values -Custom stages can return materialized values instead of `NotUsed` by inheriting from `GraphStageWithMaterializedValue` +Custom operators can return materialized values instead of `NotUsed` by inheriting from `GraphStageWithMaterializedValue` instead of the simpler `GraphStage`. The difference is that in this case the method `createLogicAndMaterializedValue(inheritedAttributes)` needs to be overridden, and in addition to the -stage logic the materialized value must be provided +operator logic the materialized value must be provided @@@ warning @@ -414,20 +414,20 @@ Scala Java : @@snip [GraphStageDocTest.java]($code$/java/jdocs/stream/GraphStageDocTest.java) { #materialized } -### Using attributes to affect the behavior of a stage +### Using attributes to affect the behavior of an operator **This section is a stub and will be extended in the next release** -Stages can access the `Attributes` object created by the materializer. This contains all the applied (inherited) -attributes applying to the stage, ordered from least specific (outermost) towards the most specific (innermost) -attribute. It is the responsibility of the stage to decide how to reconcile this inheritance chain to a final effective +Operators can access the `Attributes` object created by the materializer. This contains all the applied (inherited) +attributes applying to the operator, ordered from least specific (outermost) towards the most specific (innermost) +attribute. It is the responsibility of the operator to decide how to reconcile this inheritance chain to a final effective decision. See @ref:[Modularity, Composition and Hierarchy](stream-composition.md) for an explanation on how attributes work. ### Rate decoupled operators -Sometimes it is desirable to *decouple* the rate of the upstream and downstream of a stage, synchronizing only +Sometimes it is desirable to *decouple* the rate of the upstream and downstream of an operator, synchronizing only when needed. This is achieved in the model by representing a `GraphStage` as a *boundary* between two regions where the @@ -436,7 +436,7 @@ difference is that an `onPush` call does not always lead to calling `push` and a lead to calling `pull`. One of the important use-case for this is to build buffer-like entities, that allow independent progress -of upstream and downstream stages when the buffer is not full or empty, and slowing down the appropriate side if the +of upstream and downstream operators when the buffer is not full or empty, and slowing down the appropriate side if the buffer becomes empty or full. The next diagram illustrates the event sequence for a buffer with capacity of two elements in a setting where @@ -446,11 +446,11 @@ is seen from downstream. ![graph_stage_detached_tracks_1.png](../images/graph_stage_detached_tracks_1.png) Another scenario would be where the demand from downstream starts coming in before any element is pushed -into the buffer stage. +into the buffer operator. ![graph_stage_detached_tracks_2.png](../images/graph_stage_detached_tracks_2.png) -The first difference we can notice is that our `Buffer` stage is automatically pulling its upstream on +The first difference we can notice is that our `Buffer` operator is automatically pulling its upstream on initialization. The buffer has demand for up to two elements without any downstream demand. The following code example demonstrates a buffer class corresponding to the message sequence chart above. @@ -463,7 +463,7 @@ Java ## Thread safety of custom operators -All of the above custom stages (linear or graph) provide a few simple guarantees that implementors can rely on. +All of the above custom operators (linear or graph) provide a few simple guarantees that implementors can rely on. : * The callbacks exposed by all of these classes are never called concurrently. * The state encapsulated by these classes can be safely modified from the provided callbacks, without any further @@ -471,25 +471,25 @@ synchronization. In essence, the above guarantees are similar to what `Actor` s provide, if one thinks of the state of a custom -stage as state of an actor, and the callbacks as the `receive` block of the actor. +operator as state of an actor, and the callbacks as the `receive` block of the actor. @@@ warning -It is **not safe** to access the state of any custom stage outside of the callbacks that it provides, just like it +It is **not safe** to access the state of any custom operator outside of the callbacks that it provides, just like it is unsafe to access the state of an actor from the outside. This means that Future callbacks should **not close over** -internal state of custom stages because such access can be concurrent with the provided callbacks, leading to undefined +internal state of custom operators because such access can be concurrent with the provided callbacks, leading to undefined behavior. @@@ -## Resources and the stage lifecycle +## Resources and the operator lifecycle -If a stage manages a resource with a lifecycle, for example objects that need to be shutdown when they are not -used anymore it is important to make sure this will happen in all circumstances when the stage shuts down. +If an operator manages a resource with a lifecycle, for example objects that need to be shutdown when they are not +used anymore it is important to make sure this will happen in all circumstances when the operator shuts down. Cleaning up resources should be done in `GraphStageLogic.postStop` and not in the `InHandler` and `OutHandler` -callbacks. The reason for this is that when the stage itself completes or is failed there is no signal from the upstreams -or the downstreams. Even for stages that do not complete or fail in this manner, this can happen when the +callbacks. The reason for this is that when the operator itself completes or is failed there is no signal from the upstreams +or the downstreams. Even for operators that do not complete or fail in this manner, this can happen when the `Materializer` is shutdown or the `ActorSystem` is terminated while a stream is still running, what is called an "abrupt termination". diff --git a/akka-docs/src/main/paradox/stream/stream-dynamic.md b/akka-docs/src/main/paradox/stream/stream-dynamic.md index daa0cf4152..34c6d306be 100644 --- a/akka-docs/src/main/paradox/stream/stream-dynamic.md +++ b/akka-docs/src/main/paradox/stream/stream-dynamic.md @@ -132,7 +132,7 @@ backpressure the upstream producer until subscribers arrive. This behavior can b are no other subscribers, this will ensure that the producer is kept drained (dropping all elements) and once a new subscriber arrives it will adaptively slow down, ensuring no more messages are dropped. -### Combining dynamic stages to build a simple Publish-Subscribe service +### Combining dynamic operators to build a simple Publish-Subscribe service The features provided by the Hub implementations are limited by default. This is by design, as various combinations can be used to express additional features like unsubscribing producers or consumers externally. We show here diff --git a/akka-docs/src/main/paradox/stream/stream-error.md b/akka-docs/src/main/paradox/stream/stream-error.md index acd11d8acc..dffb8b60f1 100644 --- a/akka-docs/src/main/paradox/stream/stream-error.md +++ b/akka-docs/src/main/paradox/stream/stream-error.md @@ -12,15 +12,15 @@ To use Akka Streams, add the module to your project: ## Introduction -When a stage in a stream fails this will normally lead to the entire stream being torn down. -Each of the stages downstream gets informed about the failure and each upstream stage sees a cancellation. +When an operator in a stream fails this will normally lead to the entire stream being torn down. +Each of the operators downstream gets informed about the failure and each upstream operator sees a cancellation. In many cases you may want to avoid complete stream failure, this can be done in a few different ways: * `recover` to emit a final element then complete the stream normally on upstream failure * `recoverWithRetries` to create a new upstream and start consuming from that on failure * Restarting sections of the stream after a backoff - * Using a supervision strategy for stages that support it + * Using a supervision strategy for operators that support it In addition to these built in tools for error handling, a common pattern is to wrap the stream inside an actor, and have the actor restart the entire stream on failure. @@ -28,7 +28,7 @@ inside an actor, and have the actor restart the entire stream on failure. ## Logging errors `log()` enables logging of a stream, which is typically useful for error logging. -The below stream fails with `ArithmeticException` when the element `0` goes through the `map` stage, +The below stream fails with `ArithmeticException` when the element `0` goes through the `map` operator, Scala : @@snip [RecipeLoggingElements.scala]($code$/scala/docs/stream/cookbook/RecipeLoggingElements.scala) { #log-error } @@ -97,13 +97,13 @@ Java -## Delayed restarts with a backoff stage +## Delayed restarts with a backoff operator Just as Akka provides the @ref:[backoff supervision pattern for actors](../general/supervision.md#backoff-supervisor), Akka streams also provides a `RestartSource`, `RestartSink` and `RestartFlow` for implementing the so-called *exponential backoff -supervision strategy*, starting a stage again when it fails or completes, each time with a growing time delay between restarts. +supervision strategy*, starting an operator again when it fails or completes, each time with a growing time delay between restarts. -This pattern is useful when the stage fails or completes because some external resource is not available +This pattern is useful when the operator fails or completes because some external resource is not available and we need to give it some time to start-up again. One of the prime examples when this is useful is when a WebSocket connection fails due to the HTTP server it's running on going down, perhaps because it is overloaded. By using an exponential backoff, we avoid going into a tight reconnect loop, which both gives the HTTP server some time @@ -147,7 +147,7 @@ it cancels, while the `RestartFlow` is restarted when either the in port cancels Care should be taken when using @ref[`GraphStage`s](stream-customize.md) that conditionally propagate termination signals inside a `RestartSource`, `RestartSink` or `RestartFlow`. -An example is a `Broadcast` stage with the default `eagerCancel = false` where +An example is a `Broadcast` operator with the default `eagerCancel = false` where some of the outlets are for side-effecting branches (that do not re-join e.g. via a `Merge`). A failure on a side branch will not terminate the supervised stream which will not be restarted. Conversely, a failure on the main branch can trigger a restart but leave behind old @@ -162,32 +162,32 @@ or `divertTo` should be considered as alternatives. @@@ note -The stages that support supervision strategies are explicitly documented to do so, if there is -nothing in the documentation of a stage saying that it adheres to the supervision strategy it +The operators that support supervision strategies are explicitly documented to do so, if there is +nothing in the documentation of an operator saying that it adheres to the supervision strategy it means it fails rather than applies supervision. @@@ The error handling strategies are inspired by actor supervision strategies, but the semantics have been adapted to the domain of stream processing. The most important difference is that -supervision is not automatically applied to stream stages but instead something that each stage +supervision is not automatically applied to stream operators but instead something that each operator has to implement explicitly. -For many stages it may not even make sense to implement support for supervision strategies, -this is especially true for stages connecting to external technologies where for example a +For many operators it may not even make sense to implement support for supervision strategies, +this is especially true for operators connecting to external technologies where for example a failed connection will likely still fail if a new connection is tried immediately (see @ref:[Restart with back off](#restart-with-backoff) for such scenarios). -For stages that do implement supervision, the strategies for how to handle exceptions from +For operators that do implement supervision, the strategies for how to handle exceptions from processing stream elements can be selected when materializing the stream through use of an attribute. There are three ways to handle exceptions from application code: * `Stop` - The stream is completed with failure. * `Resume` - The element is dropped and the stream continues. - * `Restart` - The element is dropped and the stream continues after restarting the stage. -Restarting a stage means that any accumulated state is cleared. This is typically -performed by creating a new instance of the stage. + * `Restart` - The element is dropped and the stream continues after restarting the operator. +Restarting an operator means that any accumulated state is cleared. This is typically +performed by creating a new instance of the operator. By default the stopping strategy is used for all exceptions, i.e. the stream will be completed with failure when an exception is thrown. @@ -225,7 +225,7 @@ Java : @@snip [FlowErrorDocTest.java]($code$/java/jdocs/stream/FlowErrorDocTest.java) { #resume-section } `Restart` works in a similar way as `Resume` with the addition that accumulated state, -if any, of the failing processing stage will be reset. +if any, of the failing processing operator will be reset. Scala : @@snip [FlowErrorDocSpec.scala]($code$/scala/docs/stream/FlowErrorDocSpec.scala) { #restart-section } @@ -236,7 +236,7 @@ Java ### Errors from mapAsync Stream supervision can also be applied to the futures of `mapAsync` and `mapAsyncUnordered` even if such -failures happen in the future rather than inside the stage itself. +failures happen in the future rather than inside the operator itself. Let's say that we use an external service to lookup email addresses and we would like to discard those that cannot be found. 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 44a17e0016..78349f216a 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 @@ -97,8 +97,8 @@ Java @@@ div { .group-scala } -After running (materializing) the `RunnableGraph[T]` we get back the materialized value of type T. Every stream processing -stage can produce a materialized value, and it is the responsibility of the user to combine them to a new type. +After running (materializing) the `RunnableGraph[T]` we get back the materialized value of type T. Every stream +operator can produce a materialized value, and it is the responsibility of the user to combine them to a new type. In the above example we used `toMat` to indicate that we want to transform the materialized value of the source and sink, and we used the convenience function `Keep.right` to say that we are only interested in the materialized value of the sink. @@ -197,7 +197,7 @@ specification, which Akka is a founding member of. The user of the library does not have to write any explicit back-pressure handling code — it is built in and dealt with automatically by all of the provided Akka Streams operators. It is possible however to add -explicit buffer stages with overflow strategies that can influence the behavior of the stream. This is especially important +explicit buffer operators with overflow strategies that can influence the behavior of the stream. This is especially important in complex processing graphs which may even contain loops (which *must* be treated with very special care, as explained in @ref:[Graph cycles, liveness and deadlocks](stream-graphs.md#graph-cycles)). @@ -276,8 +276,8 @@ which will be running on the thread pools they have been configured to run on - @@@ note -Reusing *instances* of linear computation stages (Source, Sink, Flow) inside composite Graphs is legal, -yet will materialize that stage multiple times. +Reusing *instances* of linear computation operators (Source, Sink, Flow) inside composite Graphs is legal, +yet will materialize that operator multiple times. @@@ @@ -288,7 +288,7 @@ By default Akka Streams will fuse the stream operators. This means that the proc stream graph can be executed within the same Actor and has two consequences: * passing elements from one operator to the next is a lot faster between fused -stages due to avoiding the asynchronous messaging overhead +operators due to avoiding the asynchronous messaging overhead * fused stream operators do not run in parallel to each other, meaning that only up to one CPU core is used for each fused part @@ -319,7 +319,7 @@ operators that have been added since them. Without fusing (i.e. up to version 2.0-M2) each stream operator had an implicit input buffer that holds a few elements for efficiency reasons. If your flow graphs contain cycles then these buffers may have been crucial in order to avoid deadlocks. With fusing these implicit buffers are no longer -there, data elements are passed without buffering between fused stages. In those cases where buffering +there, data elements are passed without buffering between fused operators. In those cases where buffering is needed in order to allow the stream to run at all, you will have to insert explicit buffers with the `.buffer()` operator—typically a buffer of size 2 is enough to allow a feedback loop to function. @@ -329,7 +329,7 @@ is needed in order to allow the stream to run at all, you will have to insert ex ### Combining materialized values Since every operator in Akka Streams can provide a materialized value after being materialized, it is necessary -to somehow express how these values should be composed to a final value when we plug these stages together. For this, +to somehow express how these values should be composed to a final value when we plug these operators together. For this, many operator methods have variants that take an additional argument, a function, that will be used to combine the resulting values. Some examples of using these combiners are illustrated in the example below. @@ -361,7 +361,7 @@ Java ## Stream ordering -In Akka Streams almost all computation stages *preserve input order* of elements. This means that if inputs `{IA1,IA2,...,IAn}` +In Akka Streams almost all computation operators *preserve input order* of elements. This means that if inputs `{IA1,IA2,...,IAn}` "cause" outputs `{OA1,OA2,...,OAk}` and inputs `{IB1,IB2,...,IBm}` "cause" outputs `{OB1,OB2,...,OBl}` and all of `IAi` happened before all `IBi` then `OAi` happens before `OBi`. diff --git a/akka-docs/src/main/paradox/stream/stream-graphs.md b/akka-docs/src/main/paradox/stream/stream-graphs.md index 72cd5d3830..9bd3b0eb9d 100644 --- a/akka-docs/src/main/paradox/stream/stream-graphs.md +++ b/akka-docs/src/main/paradox/stream/stream-graphs.md @@ -175,7 +175,7 @@ In fact, these concepts can be expressed as special cases of a partially connect * `Flow` is a partial graph with *exactly one* input and *exactly one* output, that is it returns a `FlowShape`. Being able to hide complex graphs inside of simple elements such as Sink / Source / Flow enables you to create one -complex element and from there on treat it as simple compound stage for linear computations. +complex element and from there on treat it as simple compound operator for linear computations. In order to create a Source from a graph the method `Source.fromGraph` is used, to use it we must have a @scala[`Graph[SourceShape, T]`]@java[`Graph` with a `SourceShape`]. This is constructed using @@ -291,10 +291,10 @@ Scala ## Bidirectional Flows A graph topology that is often useful is that of two flows going in opposite -directions. Take for example a codec stage that serializes outgoing messages -and deserializes incoming octet streams. Another such stage could add a framing +directions. Take for example a codec operator that serializes outgoing messages +and deserializes incoming octet streams. Another such operator could add a framing protocol that attaches a length header to outgoing data and parses incoming -frames back into the original octet stream chunks. These two stages are meant +frames back into the original octet stream chunks. These two operators are meant to be composed, applying one atop the other as part of a protocol stack. For this purpose exists the special type `BidiFlow` which is a graph that has exactly two open inlets and two open outlets. The corresponding shape is @@ -328,7 +328,7 @@ Java In this way you can integrate any other serialization library that turns an object into a sequence of bytes. -The other stage that we talked about is a little more involved since reversing +The other operator that we talked about is a little more involved since reversing a framing protocol means that any received chunk of bytes may correspond to zero or more messages. This is best implemented using @ref[`GraphStage`](stream-customize.md) (see also @ref[Custom processing with GraphStage](stream-customize.md#graphstage)). diff --git a/akka-docs/src/main/paradox/stream/stream-integrations.md b/akka-docs/src/main/paradox/stream/stream-integrations.md index 108807bdda..4bd8a9d38b 100644 --- a/akka-docs/src/main/paradox/stream/stream-integrations.md +++ b/akka-docs/src/main/paradox/stream/stream-integrations.md @@ -27,7 +27,7 @@ materialized by `Source.actorRef`. A nice way to delegate some processing of elements in a stream to an actor is to use `ask`. The back-pressure of the stream is maintained by the @scala[`Future`]@java[`CompletionStage`] of the `ask` and the mailbox of the actor will not be filled with more messages than the given -`parallelism` of the `ask` stage (similarly to how the `mapAsync` stage works). +`parallelism` of the `ask` operator (similarly to how the `mapAsync` operator works). Scala : @@snip [IntegrationDocSpec.scala]($code$/scala/docs/stream/IntegrationDocSpec.scala) { #ask } @@ -45,7 +45,7 @@ message. The actor must reply to the @scala[`sender()`]@java[`getSender()`] for each message from the stream. That reply will complete the @scala[`Future`]@java[`CompletionStage`] of the `ask` and it will be the element that is emitted downstreams. -In case the target actor is stopped, the stage will fail with an `AskStageTargetActorTerminatedException` +In case the target actor is stopped, the operator will fail with an `AskStageTargetActorTerminatedException` Scala : @@snip [IntegrationDocSpec.scala]($code$/scala/docs/stream/IntegrationDocSpec.scala) { #ask-actor } @@ -57,17 +57,17 @@ The stream can be completed with failure by sending `akka.actor.Status.Failure` If the `ask` fails due to timeout the stream will be completed with `TimeoutException` failure. If that is not desired outcome you can use `recover` -on the `ask` @scala[`Future`]@java[`CompletionStage`], or use the other "restart" stages to restart it. +on the `ask` @scala[`Future`]@java[`CompletionStage`], or use the other "restart" operators to restart it. If you don't care about the reply values and only use them as back-pressure signals you -can use `Sink.ignore` after the `ask` stage and then actor is effectively a sink +can use `Sink.ignore` after the `ask` operator and then actor is effectively a sink of the stream. Note that while you may implement the same concept using `mapAsync`, that style would not be aware of the actor terminating. If you are intending to ask multiple actors by using @ref:[Actor routers](../routing.md), then you should use `mapAsyncUnordered` and perform the ask manually in there, as the ordering of the replies is not important, -since multiple actors are being asked concurrently to begin with, and no single actor is the one to be watched by the stage. +since multiple actors are being asked concurrently to begin with, and no single actor is the one to be watched by the operator. ### Sink.actorRefWithAck @@ -102,15 +102,15 @@ Note that replying to the sender of the elements (the "stream") is required as l as back-pressure (as intended), and no new elements will be sent into the actor until it acknowledges some elements. Handling the other signals while is not required, however is a good practice, to see the state of the streams lifecycle in the connected actor as well. Technically it is also possible to use multiple sinks targeting the same actor, -however it is not common practice to do so, and one should rather investigate using a `Merge` stage for this purpose. +however it is not common practice to do so, and one should rather investigate using a `Merge` operator for this purpose. @@@ note -Using `Sink.actorRef` or ordinary `tell` from a `map` or `foreach` stage means that there is +Using `Sink.actorRef` or ordinary `tell` from a `map` or `foreach` operator means that there is no back-pressure signal from the destination actor, i.e. if the actor is not consuming the messages fast enough the mailbox of the actor will grow, unless you use a bounded mailbox with zero -*mailbox-push-timeout-time* or use a rate limiting stage in front. It's often better to +*mailbox-push-timeout-time* or use a rate limiting operator in front. It's often better to use `Sink.actorRefWithAck` or `ask` in `mapAsync`, though. @@@ @@ -523,7 +523,7 @@ Scala Java : @@snip [ReactiveStreamsDocTest.java]($code$/java/jdocs/stream/ReactiveStreamsDocTest.java) { #source-fanoutPublisher } -The input buffer size of the stage controls how far apart the slowest subscriber can be from the fastest subscriber +The input buffer size of the operator controls how far apart the slowest subscriber can be from the fastest subscriber before slowing down the stream. To make the picture complete, it is also possible to expose a `Sink` as a `Subscriber` @@ -550,7 +550,7 @@ Please note that a factory is necessary to achieve reusability of the resulting As described above any Akka Streams `Source` can be exposed as a Reactive Streams `Publisher` and any `Sink` can be exposed as a Reactive Streams `Subscriber`. Therefore we recommend that you -implement Reactive Streams integrations with built-in stages or @ref:[custom stages](stream-customize.md). +implement Reactive Streams integrations with built-in operators or @ref:[custom operators](stream-customize.md). For historical reasons the `ActorPublisher` and `ActorSubscriber` traits are provided to support implementing Reactive Streams `Publisher` and `Subscriber` with @@ -572,10 +572,10 @@ the stream may deadlock. **Deprecation warning:** `ActorPublisher` is deprecated in favour of the vastly more type-safe and safe to implement @ref[`GraphStage`](stream-customize.md). It can also -expose a "stage actor ref" is needed to be addressed as-if an Actor. -Custom stages implemented using @ref[`GraphStage`](stream-customize.md) are also automatically fusable. +expose a "operator actor ref" is needed to be addressed as-if an Actor. +Custom operators implemented using @ref[`GraphStage`](stream-customize.md) are also automatically fusable. -To learn more about implementing custom stages using it refer to @ref:[Custom processing with GraphStage](stream-customize.md#graphstage). +To learn more about implementing custom operators using it refer to @ref:[Custom processing with GraphStage](stream-customize.md#graphstage). @@@ @@ -638,10 +638,10 @@ Java **Deprecation warning:** `ActorSubscriber` is deprecated in favour of the vastly more type-safe and safe to implement @ref[`GraphStage`](stream-customize.md). It can also -expose a "stage actor ref" is needed to be addressed as-if an Actor. -Custom stages implemented using @ref[`GraphStage`](stream-customize.md) are also automatically fusable. +expose a "operator actor ref" is needed to be addressed as-if an Actor. +Custom operators implemented using @ref[`GraphStage`](stream-customize.md) are also automatically fusable. -To learn more about implementing custom stages using it refer to @ref:[Custom processing with GraphStage](stream-customize.md#graphstage). +To learn more about implementing custom operators using it refer to @ref:[Custom processing with GraphStage](stream-customize.md#graphstage). @@@ diff --git a/akka-docs/src/main/paradox/stream/stream-introduction.md b/akka-docs/src/main/paradox/stream/stream-introduction.md index b705afbadc..8cb37656c1 100644 --- a/akka-docs/src/main/paradox/stream/stream-introduction.md +++ b/akka-docs/src/main/paradox/stream/stream-introduction.md @@ -48,8 +48,8 @@ or resource exhaustion. The relationship between these two is that the Akka Streams API is geared towards end-users while the Akka Streams implementation uses the Reactive -Streams interfaces internally to pass data between the different processing -stages. For this reason you will not find any resemblance between the Reactive +Streams interfaces internally to pass data between the different operators. +For this reason you will not find any resemblance between the Reactive Streams interfaces and the Akka Streams API. This is in line with the expectations of the Reactive Streams project, whose primary purpose is to define interfaces such that different streaming implementation can diff --git a/akka-docs/src/main/paradox/stream/stream-io.md b/akka-docs/src/main/paradox/stream/stream-io.md index 670e0d9ef6..1b2dfcd6d6 100644 --- a/akka-docs/src/main/paradox/stream/stream-io.md +++ b/akka-docs/src/main/paradox/stream/stream-io.md @@ -176,7 +176,7 @@ Please note that these operators are backed by Actors and by default are configu threadpool-backed dispatcher dedicated for File IO. This is very important as it isolates the blocking file IO operations from the rest of the ActorSystem allowing each dispatcher to be utilised in the most efficient way. If you want to configure a custom dispatcher for file IO operations globally, you can do so by changing the `akka.stream.materializer.blocking-io-dispatcher`, -or for a specific stage by specifying a custom Dispatcher in code, like this: +or for a specific operator by specifying a custom Dispatcher in code, like this: Scala : @@snip [StreamFileDocSpec.scala]($code$/scala/docs/stream/io/StreamFileDocSpec.scala) { #custom-dispatcher-code } diff --git a/akka-docs/src/main/paradox/stream/stream-parallelism.md b/akka-docs/src/main/paradox/stream/stream-parallelism.md index a8b5c4a3b0..ab3b136188 100644 --- a/akka-docs/src/main/paradox/stream/stream-parallelism.md +++ b/akka-docs/src/main/paradox/stream/stream-parallelism.md @@ -14,11 +14,11 @@ To use Akka Streams, add the module to your project: Akka Streams operators (be it simple operators on Flows and Sources or graph junctions) are "fused" together and executed sequentially by default. This avoids the overhead of events crossing asynchronous boundaries but -limits the flow to execute at most one stage at any given time. +limits the flow to execute at most one operator at any given time. -In many cases it is useful to be able to concurrently execute the stages of a flow, this is done by explicitly marking +In many cases it is useful to be able to concurrently execute the operators of a flow, this is done by explicitly marking them as asynchronous using the @scala[`async`]@java[`async()`] method. Each operator marked as asynchronous will run in a -dedicated actor internally, while all stages not marked asynchronous will run in one single actor. +dedicated actor internally, while all operators not marked asynchronous will run in one single actor. We will illustrate through the example of pancake cooking how streams can be used for various processing patterns, exploiting the available parallelism on modern computers. The setting is the following: both Patrik and Roland @@ -41,7 +41,7 @@ Scala Java : @@snip [FlowParallelismDocTest.java]($code$/java/jdocs/stream/FlowParallelismDocTest.java) { #pipelining } -The two `map` stages in sequence (encapsulated in the "frying pan" flows) will be executed in a pipelined way, +The two `map` operators in sequence (encapsulated in the "frying pan" flows) will be executed in a pipelined way, the same way that Roland was using his frying pans: 1. A `ScoopOfBatter` enters `fryingPan1` @@ -51,8 +51,8 @@ the same way that Roland was using his frying pans: The benefit of pipelining is that it can be applied to any sequence of processing steps that are otherwise not parallelisable (for example because the result of a processing step depends on all the information from the previous -step). One drawback is that if the processing times of the stages are very different then some of the stages will not -be able to operate at full throughput because they will wait on a previous or subsequent stage most of the time. In the +step). One drawback is that if the processing times of the operators are very different then some of the operators will not +be able to operate at full throughput because they will wait on a previous or subsequent operator most of the time. In the pancake example frying the second half of the pancake is usually faster than frying the first half, `fryingPan2` will not be able to operate at full capacity [1]. @@ -81,8 +81,8 @@ it is easy to add a third frying pan with Patrik's method, but Roland cannot add since that would require a third processing step, which is not practically possible in the case of frying pancakes. One drawback of the example code above that it does not preserve the ordering of pancakes. This might be a problem -if children like to track their "own" pancakes. In those cases the `Balance` and `Merge` stages should be replaced -by strict-round robing balancing and merging stages that put in and take out pancakes in a strict order. +if children like to track their "own" pancakes. In those cases the `Balance` and `Merge` operators should be replaced +by strict-round robing balancing and merging operators that put in and take out pancakes in a strict order. A more detailed example of creating a worker pool can be found in the cookbook: @ref:[Balancing jobs to a fixed pool of workers](stream-cookbook.md#cookbook-balance) @@ -108,7 +108,7 @@ the previous one. In our case individual pancakes do not depend on each other, t other hand it is not possible to fry both sides of the same pancake at the same time, so the two sides have to be fried in sequence. -It is also possible to organize parallelized stages into pipelines. This would mean employing four chefs: +It is also possible to organize parallelized operators into pipelines. This would mean employing four chefs: * the first two chefs prepare half-cooked pancakes from batter, in parallel, then putting those on a large enough flat surface. diff --git a/akka-docs/src/main/paradox/stream/stream-quickstart.md b/akka-docs/src/main/paradox/stream/stream-quickstart.md index 0b8985384c..02f3af50de 100644 --- a/akka-docs/src/main/paradox/stream/stream-quickstart.md +++ b/akka-docs/src/main/paradox/stream/stream-quickstart.md @@ -247,7 +247,7 @@ Java : @@snip [TwitterStreamQuickstartDocTest.java]($code$/java/jdocs/stream/TwitterStreamQuickstartDocTest.java) { #materializer-setup } The `ActorMaterializer` can optionally take `ActorMaterializerSettings` which can be used to define -materialization properties, such as default buffer sizes (see also @ref:[Buffers for asynchronous stages](stream-rate.md#async-stream-buffers)), the dispatcher to +materialization properties, such as default buffer sizes (see also @ref:[Buffers for asynchronous operators](stream-rate.md#async-stream-buffers)), the dispatcher to be used by the pipeline etc. These can be overridden with `withAttributes` on `Flow`, `Source`, `Sink` and `Graph`. Let's assume we have a stream of tweets readily available. In Akka this is expressed as a @scala[`Source[Out, M]`]@java[`Source`]: @@ -423,7 +423,7 @@ into an integer value `1`. Finally we connect the Flow to the previously prepar Remember those mysterious `Mat` type parameters on @scala[`Source[+Out, +Mat]`, `Flow[-In, +Out, +Mat]` and `Sink[-In, +Mat]`]@java[`Source`, `Flow` and `Sink`]? They represent the type of values these processing parts return when materialized. When you chain these together, you can explicitly combine their materialized values. In our example we used the @scala[`Keep.right`]@java[`Keep.right()`] predefined function, -which tells the implementation to only care about the materialized type of the stage currently appended to the right. +which tells the implementation to only care about the materialized type of the operator currently appended to the right. The materialized type of `sumSink` is @scala[`Future[Int]`]@java[`CompletionStage`] and because of using @scala[`Keep.right`]@java[`Keep.right()`], the resulting `RunnableGraph` has also a type parameter of @scala[`Future[Int]`]@java[`CompletionStage`]. @@ -457,7 +457,7 @@ Java @@@ note -`runWith()` is a convenience method that automatically ignores the materialized value of any other stages except +`runWith()` is a convenience method that automatically ignores the materialized value of any other operators except those appended by the `runWith()` itself. In the above example it translates to using @scala[`Keep.right`]@java[`Keep.right()`] as the combiner for materialized values. diff --git a/akka-docs/src/main/paradox/stream/stream-rate.md b/akka-docs/src/main/paradox/stream/stream-rate.md index 0adecaec9e..ba2daa5270 100644 --- a/akka-docs/src/main/paradox/stream/stream-rate.md +++ b/akka-docs/src/main/paradox/stream/stream-rate.md @@ -16,12 +16,12 @@ When upstream and downstream rates differ, especially when the throughput has sp buffers in a stream. In this chapter we cover how buffers are used in Akka Streams. -## Buffers for asynchronous stages +## Buffers for asynchronous operators -In this section we will discuss internal buffers that are introduced as an optimization when using asynchronous stages. +In this section we will discuss internal buffers that are introduced as an optimization when using asynchronous operators. -To run a stage asynchronously it has to be marked explicitly as such using the @scala[@scaladoc[`.async`](akka.stream.Graph#shape:S)]@java[@javadoc[`.async()`](akka.stream.Graph#async--)] method. Being run -asynchronously means that a stage, after handing out an element to its downstream consumer is able to immediately +To run an operator asynchronously it has to be marked explicitly as such using the @scala[@scaladoc[`.async`](akka.stream.Graph#shape:S)]@java[@javadoc[`.async()`](akka.stream.Graph#async--)] method. Being run +asynchronously means that an operator, after handing out an element to its downstream consumer is able to immediately process the next message. To demonstrate what we mean by this, let's take a look at the following example: Scala @@ -46,7 +46,7 @@ C: 3 Note that the order is *not* `A:1, B:1, C:1, A:2, B:2, C:2,` which would correspond to the normal fused synchronous execution model of flows where an element completely passes through the processing pipeline before the next element -enters the flow. The next element is processed by an asynchronous stage as soon as it is emitted the previous one. +enters the flow. The next element is processed by an asynchronous operator as soon as it is emitted the previous one. While pipelining in general increases throughput, in practice there is a cost of passing an element through the asynchronous (and therefore thread crossing) boundary which is significant. To amortize this cost Akka Streams uses @@ -58,7 +58,7 @@ propagating the backpressure signal through the asynchronous boundary. While this internal protocol is mostly invisible to the user (apart from its throughput increasing effects) there are situations when these details get exposed. In all of our previous examples we always assumed that the rate of the -processing chain is strictly coordinated through the backpressure signal causing all stages to process no faster than +processing chain is strictly coordinated through the backpressure signal causing all operators to process no faster than the throughput of the connected chain. There are tools in Akka Streams however that enable the rates of different segments of a processing chain to be "detached" or to define the maximum throughput of the stream through external timing sources. These situations are exactly those where the internal batching buffering strategy suddenly becomes non-transparent. @@ -217,7 +217,7 @@ Java ### Understanding extrapolate and expand -Now we will discuss two stages, `extrapolate` and `expand`, helping to deal with slow producers that are unable to keep +Now we will discuss two operators, `extrapolate` and `expand`, helping to deal with slow producers that are unable to keep up with the demand coming from consumers. They allow for additional values to be sent as elements to a consumer. diff --git a/akka-docs/src/main/paradox/stream/stream-refs.md b/akka-docs/src/main/paradox/stream/stream-refs.md index df2e216911..23e4fa739e 100644 --- a/akka-docs/src/main/paradox/stream/stream-refs.md +++ b/akka-docs/src/main/paradox/stream/stream-refs.md @@ -103,9 +103,9 @@ The process of preparing and running a `SourceRef` powered distributed stream is A `SourceRef` is *by design* "single-shot". i.e. it may only be materialized once. This is in order to not complicate the mental model of what materialization means. - Multicast can be mimicked by starting a `BroadcastHub` stage once then attaching multiple new streams to it, each + Multicast can be mimicked by starting a `BroadcastHub` operator once then attaching multiple new streams to it, each emitting a new stream ref. This way materialization of the `BroadcastHub`s Source creates a unique single-shot - stream ref, however they can all be powered using a single `Source` -- located before the `BroadcastHub` stage. + stream ref, however they can all be powered using a single `Source` -- located before the `BroadcastHub` operator. @@@ ### Sink Refs - offering to receive streaming data from a remote system @@ -146,9 +146,9 @@ The process of preparing and running a `SinkRef` powered distributed stream is s This is in order to not complicate the mental model what materializing such value would mean. If you have an use case for building a fan-in operation accepting writes from multiple remote nodes, - you can build your Sink and prepend it with a `MergeHub` stage, each time materializing a new `SinkRef` + you can build your Sink and prepend it with a `MergeHub` operator, each time materializing a new `SinkRef` targeting that `MergeHub`. This has the added benefit of giving you full control how to merge these streams - (i.e. by using "merge preferred" or any other variation of the fan-in stages). + (i.e. by using "merge preferred" or any other variation of the fan-in operators). @@@ ### Delivery guarantees diff --git a/akka-docs/src/main/paradox/stream/stream-substream.md b/akka-docs/src/main/paradox/stream/stream-substream.md index dc6a7beda8..1ae1844e9d 100644 --- a/akka-docs/src/main/paradox/stream/stream-substream.md +++ b/akka-docs/src/main/paradox/stream/stream-substream.md @@ -18,9 +18,9 @@ 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](operators/index.md#nesting-and-flattening-stages) +operators that create substreams are listed on @ref[Nesting and flattening operators](operators/index.md#nesting-and-flattening-operators) -## Nesting stages +## Nesting operators ### groupBy @@ -41,7 +41,7 @@ a new substream is opened and subsequently fed with all elements belonging to th If `allowClosedSubstreamRecreation` is set to `true` a substream belonging to a specific key will be recreated if it was closed before, otherwise elements belonging to that key will be dropped. -If you add a `Sink` or `Flow` right after the `groupBy` stage, +If you add a `Sink` or `Flow` right after the `groupBy` operator, all transformations are applied to all encountered substreams in the same fashion. So, if you add the following `Sink`, that is added to each of the substreams as in the below diagram. @@ -119,7 +119,7 @@ This prints out the following output. ![stream-substream-splitWhen-splitAfter.png](../../images/stream-substream-splitWhen-splitAfter.png) -## Flattening stages +## Flattening operators ### flatMapConcat diff --git a/akka-docs/src/test/java/jdocs/stream/GraphStageDocTest.java b/akka-docs/src/test/java/jdocs/stream/GraphStageDocTest.java index f69ef0685c..d81d500d4e 100644 --- a/akka-docs/src/test/java/jdocs/stream/GraphStageDocTest.java +++ b/akka-docs/src/test/java/jdocs/stream/GraphStageDocTest.java @@ -408,14 +408,14 @@ public class GraphStageDocTest extends AbstractJavaTest { public void demonstrateChainingOfGraphStages() throws Exception { Graph, CompletionStage> sink = Sink.fold("", (acc, n) -> acc + n.toString()); - //#graph-stage-chain + //#graph-operator-chain CompletionStage resultFuture = Source.from(Arrays.asList(1,2,3,4,5)) .via(new Filter((n) -> n % 2 == 0)) .via(new Duplicator()) .via(new Map((n) -> n / 2)) .runWith(sink, mat); - //#graph-stage-chain + //#graph-operator-chain assertEquals("1122", resultFuture.toCompletableFuture().get(3, TimeUnit.SECONDS)); } diff --git a/akka-docs/src/test/java/jdocs/stream/GraphStageLoggingDocTest.java b/akka-docs/src/test/java/jdocs/stream/GraphStageLoggingDocTest.java index 65d41f8f48..2971d68c73 100644 --- a/akka-docs/src/test/java/jdocs/stream/GraphStageLoggingDocTest.java +++ b/akka-docs/src/test/java/jdocs/stream/GraphStageLoggingDocTest.java @@ -28,7 +28,7 @@ public class GraphStageLoggingDocTest extends AbstractJavaTest { @Test public void compileOnlyTestClass() throws Exception { } - //#stage-with-logging + //#operator-with-logging public class RandomLettersSource extends GraphStage> { public final Outlet out = Outlet.create("RandomLettersSource.in"); @@ -65,6 +65,6 @@ public class GraphStageLoggingDocTest extends AbstractJavaTest { }; } } - //#stage-with-logging + //#operator-with-logging } diff --git a/akka-docs/src/test/scala/docs/stream/GraphStageDocSpec.scala b/akka-docs/src/test/scala/docs/stream/GraphStageDocSpec.scala index e416c11a1d..b5e247eac5 100644 --- a/akka-docs/src/test/scala/docs/stream/GraphStageDocSpec.scala +++ b/akka-docs/src/test/scala/docs/stream/GraphStageDocSpec.scala @@ -287,14 +287,14 @@ class GraphStageDocSpec extends AkkaSpec { "Demonstrate chaining of graph stages" in { val sink = Sink.fold[List[Int], Int](List.empty[Int])((acc, n) ⇒ acc :+ n) - //#graph-stage-chain + //#graph-operator-chain val resultFuture = Source(1 to 5) .via(new Filter(_ % 2 == 0)) .via(new Duplicator()) .via(new Map(_ / 2)) .runWith(sink) - //#graph-stage-chain + //#graph-operator-chain Await.result(resultFuture, 3.seconds) should ===(List(1, 1, 2, 2)) } diff --git a/akka-docs/src/test/scala/docs/stream/GraphStageLoggingDocSpec.scala b/akka-docs/src/test/scala/docs/stream/GraphStageLoggingDocSpec.scala index 72b57a3ffb..70d42443ad 100644 --- a/akka-docs/src/test/scala/docs/stream/GraphStageLoggingDocSpec.scala +++ b/akka-docs/src/test/scala/docs/stream/GraphStageLoggingDocSpec.scala @@ -15,7 +15,7 @@ class GraphStageLoggingDocSpec extends AkkaSpec("akka.loglevel = DEBUG") { implicit val materializer = ActorMaterializer() implicit val ec = system.dispatcher - //#stage-with-logging + //#operator-with-logging import akka.stream.stage.{ GraphStage, GraphStageLogic, OutHandler, StageLogging } final class RandomLettersSource extends GraphStage[SourceShape[String]] { @@ -39,7 +39,7 @@ class GraphStageLoggingDocSpec extends AkkaSpec("akka.loglevel = DEBUG") { def nextChar(): Char = ThreadLocalRandom.current().nextInt('a', 'z'.toInt + 1).toChar } - //#stage-with-logging + //#operator-with-logging "demonstrate logging in custom graphstage" in { val n = 10 diff --git a/project/StreamOperatorsIndexGenerator.scala b/project/StreamOperatorsIndexGenerator.scala index 53cd8ae03e..70a3e34c00 100644 --- a/project/StreamOperatorsIndexGenerator.scala +++ b/project/StreamOperatorsIndexGenerator.scala @@ -20,22 +20,22 @@ object StreamOperatorsIndexGenerator extends AutoPlugin { )) val categories = Seq( - "Source stages", - "Sink stages", + "Source operators", + "Sink operators", "Additional Sink and Source converters", "File IO Sinks and Sources", "Simple operators", - "Flow stages composed of Sinks and Sources", + "Flow operators composed of Sinks and Sources", "Asynchronous operators", - "Timer driven stages", - "Backpressure aware stages", - "Nesting and flattening stages", - "Time aware stages", - "Fan-in stages", + "Timer driven operators", + "Backpressure aware operators", + "Nesting and flattening operators", + "Time aware operators", + "Fan-in operators", // TODO these don't show up as def's yet so don't show up in the index.. -// "Fan-out stages", - "Watching status stages", - "Actor interop stages", +// "Fan-out operators", + "Watching status operators", + "Actor interop operators" ) def categoryId(name: String): String = name.toLowerCase.replace(' ', '-')