Java and Scala overview separated. delay and initialDelay added

akka-docs/rst/java/stream/index.rst

@@ -19,7 +19,7 @@ Streams
    stream-io
    stream-parallelism
    stream-testkit
-   ../../general/stream/stages-overview
+   stages-overview
    stream-cookbook
    ../../general/stream/stream-configuration
    migration-guide-1.0-2.x-java

akka-docs/rst/scala/stream/index.rst

@@ -19,7 +19,7 @@ Streams
    stream-io
    stream-parallelism
    stream-testkit
-   ../../general/stream/stages-overview
+   stages-overview
    stream-cookbook
    ../../general/stream/stream-configuration
    migration-guide-1.0-2.x-scala

akka-docs/rst/scala/stream/stages-overview.rst

@@ -6,19 +6,29 @@ Overview of built-in stages and their semantics
 
 Source stages
 -------------
-These built-in sources are available from `akka.stream.scaladsl.Source` and `akka.stream.javadsl.Source`
+These built-in sources are available from ``akka.stream.scaladsl.Source``:
 
 
 
 fromIterator
 ^^^^^^^^^^^^
-Stream the values from an iterator, requesting the next value when there is demand.
+Stream the values from an ``Iterator``, requesting the next value when there is demand. The iterator will be created anew
+for each materialization, which is the reason the method takes a function rather than an iterator directly.
 
 If the iterator perform blocking operations, make sure to run it on a separate dispatcher.
 
-*emits* when the next value returned from the iterator
+*emits* the next value returned from the iterator
+
+*completes* when the iterator reaches its end
+
+apply
+^^^^^
+Stream the values of an ``immutable.Seq``.
+
+*emits* the next value of the seq
+
+*completes* when the last element of the seq has been emitted
 
-*completes* when the iterator reaches it's end
 
 single
 ^^^^^^
@@ -54,10 +64,20 @@ If the future fails the stream is failed with that exception.
 
 *completes* after the future has completed
 
+fromCompletionStage
+^^^^^^^^^^^^^^^^^^^
+Send the single value of the Java ``CompletionStage`` when it completes and there is demand.
+If the future fails the stream is failed with that exception.
+
+*emits* the future completes
+
+*completes* after the future has completed
+
+
 unfold
 ^^^^^^
-Stream the result of a function as long as it returns a ``Some`` or non-empty ``Optional``, the value inside the optional
-consists of a tuple (or ``Pair``) where the first value is a state passed back into the next call to the function allowing
+Stream the result of a function as long as it returns a ``Some``, the value inside the option
+consists of a tuple where the first value is a state passed back into the next call to the function allowing
 to pass a state. The first invocation of the provided fold function will receive the ``zero`` state.
 
 Can be used to implement many stateful sources without having to touch the more low level ``GraphStage`` API.
@@ -68,7 +88,7 @@ Can be used to implement many stateful sources without having to touch the more
 
 unfoldAsync
 ^^^^^^^^^^^
-Just like ``unfold`` but the fold function returns a ``Future`` or ``CompletionStage`` which will cause the source to
+Just like ``unfold`` but the fold function returns a ``Future`` which will cause the source to
 complete or emit when it completes.
 
 Can be used to implement many stateful sources without having to touch the more low level ``GraphStage`` API.
@@ -88,8 +108,8 @@ an API but there are no elements to emit.
 
 maybe
 ^^^^^
-Either emit one value if the ``Option`` or ``Optional`` contains a value, or complete directly
-if the optional value is empty.
+Materialize a ``Promise[Option[T]]`` that if completed with a ``Some[T]`` will emit that `T` and then complete
+the stream, or if completed with ``None`` complete the stream right away.
 
 *emits* when the returned promise is completed with some value
 
@@ -154,12 +174,12 @@ Integration with Reactive Streams, subscribes to a ``org.reactivestreams.Publish
 
 Sink stages
 -----------
-These built-in sinks are available from ``akka.stream.scaladsl.Sink`` and ``akka.stream.javadsl.Sink``:
+These built-in sinks are available from ``akka.stream.scaladsl.Sink``:
 
 
 head
 ^^^^
-Materializes into a ``Future`` or ``CompletionStage`` which completes with the first value arriving,
+Materializes into a ``Future`` which completes with the first value arriving,
 after this the stream is canceled. If no element is emitted, the future is be failed.
 
 *cancels* after receiving one element
@@ -168,8 +188,8 @@ after this the stream is canceled. If no element is emitted, the future is be fa
 
 headOption
 ^^^^^^^^^^
-Materializes into a ``Future[Option[T]]`` or ``CompletionStage<Optional<T>>`` which completes with the first value
-arriving wrapped in the optional, or an empty optional if the stream completes without any elements emitted.
+Materializes into a ``Future[Option[T]]`` which completes with the first value arriving wrapped in a ``Some``,
+or a ``None`` if the stream completes without any elements emitted.
 
 *cancels* after receiving one element
 
@@ -187,8 +207,8 @@ completes. If the stream completes with no elements the future is failed.
 lastOption
 ^^^^^^^^^^
 Materialize a ``Future[Option[T]]`` which completes with the last value
-emitted wrapped in an optional when the stream completes. if the stream completes with no elements the future is
-completed with an empty optional.
+emitted wrapped in an ``Some`` when the stream completes. if the stream completes with no elements the future is
+completed with ``None``.
 
 *cancels* never
 
@@ -221,7 +241,7 @@ foreach
 ^^^^^^^
 Invoke a given procedure for each element received. Note that it is not safe to mutate shared state from the procedure.
 
-The sink materializes into a  ``Future[Option[Done]]`` or ``CompletionStage<Optional<Done>>`` which completes when the
+The sink materializes into a  ``Future[Option[Done]]`` which completes when the
 stream completes, or fails if the stream fails.
 
 Note that it is not safe to mutate state from the procedure.
@@ -338,7 +358,7 @@ fromOutputStream
 Create a sink that wraps an ``OutputStream``. Takes a function that produces an ``OutputStream``, when the sink is
 materialized the function will be called and bytes sent to the sink will be written to the returned ``OutputStream``.
 
-Materializes into a ``Future`` or ``CompletionStage`` which will complete with a ``IOResult`` when the stream
+Materializes into a ``Future`` which will complete with a ``IOResult`` when the stream
 completes.
 
 Note that a flow can be materialized multiple times, so the function producing the ``OutputStream`` must be able
@@ -354,7 +374,7 @@ fromInputStream
 Create a source that wraps an ``InputStream``. Takes a function that produces an ``InputStream``, when the source is
 materialized the function will be called and bytes from the ``InputStream`` will be emitted into the stream.
 
-Materializes into a ``Future`` or ``CompletionStage`` which will complete with a ``IOResult`` when the stream
+Materializes into a ``Future`` which will complete with a ``IOResult`` when the stream
 completes.
 
 Note that a flow can be materialized multiple times, so the function producing the ``InputStream`` must be able
@@ -373,7 +393,7 @@ Sources and sinks for reading and writing files can be found on ``FileIO``.
 
 fromFile
 ^^^^^^^^
-Emit the contents of a file, as ``ByteString`` s, materializes into a ``Future`` or ``CompletionStage`` which will be completed with
+Emit the contents of a file, as ``ByteString`` s, materializes into a ``Future`` which will be completed with
 a ``IOResult`` upon reaching the end of the file or if there is a failure.
 
 toFile
@@ -560,6 +580,18 @@ Detach upstream demand from downstream demand without detaching the stream rates
 *completes* when upstream completes
 
 
+throttle
+^^^^^^^^
+Limit the throughput to a specific number of elements per time unit, or a specific total cost per time unit, where
+a function has to be provided to calculate the individual cost of each element.
+
+*emits* when upstream emits an element and configured time per each element elapsed
+
+*backpressures* when downstream backpressures
+
+*completes* when upstream completes
+
+
 Asynchronous processing stages
 ------------------------------
 
@@ -633,6 +665,29 @@ whichever happens first.
 *completes* when upstream completes
 
 
+initialDelay
+^^^^^^^^^^^^
+Delay the initial element by a user specified duration from stream materialization.
+
+*emits* upstream emits an element if the initial delay already elapsed
+
+*backpressures* downstream backpressures or initial delay not yet elapsed
+
+*completes* when upstream completes
+
+
+delay
+^^^^^
+Delay every element passed through with a specific duration.
+
+*emits* there is a pending element in the buffer and configured time for this element elapsed
+
+*backpressures* differs, depends on ``OverflowStrategy`` set
+
+*completes* when upstream completes and buffered elements has been drained
+
+
+
 .. _detached-stages-overview:
 
 Backpressure aware stages