From 8d94ef329413df960f3a77ff875dcc27c06bd229 Mon Sep 17 00:00:00 2001 From: Tim Harper Date: Mon, 18 Jan 2016 01:24:56 -0700 Subject: [PATCH] =doc expound on SubFlow motivation / upgrade procedure Incorporate Roland's comments from https://groups.google.com/d/msg/akka-user/_blLOcIHxJ4/i1DOoylmEgAJ --- .../stream/migration-guide-1.0-2.x-java.rst | 34 ++++++++++++------- .../stream/migration-guide-1.0-2.x-scala.rst | 32 +++++++++++------ 2 files changed, 43 insertions(+), 23 deletions(-) diff --git a/akka-docs/rst/java/stream/migration-guide-1.0-2.x-java.rst b/akka-docs/rst/java/stream/migration-guide-1.0-2.x-java.rst index f449debdea..11a72ec1da 100644 --- a/akka-docs/rst/java/stream/migration-guide-1.0-2.x-java.rst +++ b/akka-docs/rst/java/stream/migration-guide-1.0-2.x-java.rst @@ -428,22 +428,32 @@ read the* ``GraphStage`` *documentation (TODO) for details.* GroupBy, SplitWhen and SplitAfter now return SubFlow or SubSource ================================================================= -Previously the ``groupBy``, ``splitWhen``, and ``splitAfter`` combinators -returned a type that included a :class:`Source` within its elements. -Transforming these substreams was only possible by nesting the respective -combinators inside a ``map`` of the outer stream. This has been made more -convenient and also safer by dropping down into transforming the substreams -instead: the return type is now a :class:`SubSource` (for sources) or a -:class:`SubFlow` (for flows) that does not implement the :class:`Graph` -interface and therefore only represents an unfinished intermediate builder -step. +Previously the ``groupBy``, ``splitWhen``, and ``splitAfter`` +combinators returned a type that included a :class:`Source` within its +elements. Transforming these substreams was only possible by nesting +the respective combinators inside a ``map`` of the outer stream. +While this design enabled maximum flexibility for handling substreams, +it ultimately made it too easy to create a (potentially suprising) +deadlock. You can read more in `SubFlow-Motivation-Thread`_. + +These operations have been made more convenient and also safer by +dropping down into transforming the substreams instead: the return +type is now a :class:`SubFlow` that does not implement the +:class:`Graph` interface and therefore only represents an unfinished +intermediate builder step. The substream mode can be ended by closing +the substreams (i.e. attaching a :class:`Sink`) or merging them back +together. + +.. _SubFlow-Motivation-Thread: https://groups.google.com/d/msg/akka-user/_blLOcIHxJ4/i1DOoylmEgAJ Update Procedure ---------------- -The transformations that were done on the substreams need to be lifted up one -level. This only works for cases where the processing topology is homogenous -for all substreams. +The transformations that were done on the substreams need to be lifted +up one level. This only works for cases where the processing topology +is homogenous for all substreams. If your substream processing +topology is heterogeneous, consider creating a graph (see +:ref:`stream-graph-java`). Example ^^^^^^^ diff --git a/akka-docs/rst/scala/stream/migration-guide-1.0-2.x-scala.rst b/akka-docs/rst/scala/stream/migration-guide-1.0-2.x-scala.rst index ac75d53329..744a87fd96 100644 --- a/akka-docs/rst/scala/stream/migration-guide-1.0-2.x-scala.rst +++ b/akka-docs/rst/scala/stream/migration-guide-1.0-2.x-scala.rst @@ -399,22 +399,32 @@ read the* ``GraphStage`` *documentation (TODO) for details.* GroupBy, SplitWhen and SplitAfter now return SubFlow ==================================================== -Previously the ``groupBy``, ``splitWhen``, and ``splitAfter`` combinators -returned a type that included a :class:`Source` within its elements. -Transforming these substreams was only possible by nesting the respective -combinators inside a ``map`` of the outer stream. This has been made more -convenient and also safer by dropping down into transforming the substreams -instead: the return type is now a :class:`SubFlow` that does not implement the +Previously the ``groupBy``, ``splitWhen``, and ``splitAfter`` +combinators returned a type that included a :class:`Source` within its +elements. Transforming these substreams was only possible by nesting +the respective combinators inside a ``map`` of the outer stream. +While this design enabled maximum flexibility for handling substreams, +it ultimately made it too easy to create a (potentially suprising) +deadlock. You can read more in `SubFlow-Motivation-Thread`_. + +These operations have been made more convenient and also safer by +dropping down into transforming the substreams instead: the return +type is now a :class:`SubFlow` that does not implement the :class:`Graph` interface and therefore only represents an unfinished -intermediate builder step. The substream mode can be ended by closing the -substreams (i.e. attaching a :class:`Sink`) or merging them back together. +intermediate builder step. The substream mode can be ended by closing +the substreams (i.e. attaching a :class:`Sink`) or merging them back +together. + +.. _SubFlow-Motivation-Thread: https://groups.google.com/d/msg/akka-user/_blLOcIHxJ4/i1DOoylmEgAJ Update Procedure ---------------- -The transformations that were done on the substreams need to be lifted up one -level. This only works for cases where the processing topology is homogenous -for all substreams. +The transformations that were done on the substreams need to be lifted +up one level. This only works for cases where the processing topology +is homogenous for all substreams. If your substream processing +topology is heterogeneous, consider creating a graph (see +:ref:`stream-graph-scala`). Example ^^^^^^^