From 4f5bba04a954fb55133590e2003e3be2ddf21a12 Mon Sep 17 00:00:00 2001 From: Roland Kuhn Date: Mon, 21 Dec 2015 14:26:44 +0100 Subject: [PATCH] add fusing to migration guide --- .../rst/java/migration-guide-1.0-2.x-java.rst | 37 +++++++++++++++++- .../scala/migration-guide-1.0-2.x-scala.rst | 39 ++++++++++++++++++- 2 files changed, 73 insertions(+), 3 deletions(-) diff --git a/akka-docs-dev/rst/java/migration-guide-1.0-2.x-java.rst b/akka-docs-dev/rst/java/migration-guide-1.0-2.x-java.rst index ad8278d243..80dea20eb5 100644 --- a/akka-docs-dev/rst/java/migration-guide-1.0-2.x-java.rst +++ b/akka-docs-dev/rst/java/migration-guide-1.0-2.x-java.rst @@ -5,8 +5,43 @@ ############################ The 2.0 release contains some structural changes that require some -simple, mechanical source-level changes in client code. +simple, mechanical source-level changes in client code. While these are detailed below, +there is another change that may have an impact on the runtime behavior of your streams +and which therefore is listed first. +Operator Fusion is on by default +================================ + +Akka Streams 2.0 contains an initial version of stream operator fusion support. This means that +the processing steps of a flow or stream graph can be executed within the same Actor and has three +consequences: + + * starting up a stream may take longer than before due to executing the fusion algorithm + * passing elements from one processing stage to the next is a lot faster between fused + stages due to avoiding the asynchronous messaging overhead + * fused stream processing stages do no longer run in parallel to each other, meaning that + only up to one CPU core is used for each fused part + +The first point can be countered by pre-fusing and then reusing a stream blueprint, see ``akka.stream.Fusing``. +In order to balance the effects of the second and third bullet points you will have to insert asynchronous +boundaries manually into your flows and graphs by way of adding ``Attributes.asyncBoundary`` to pieces that +shall communicate with the rest of the graph in an asynchronous fashion. + +.. warning:: + + Without fusing (i.e. up to version 2.0-M2) each stream processing stage 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 + is needed in order to allow the stream to run at all, you will have to insert explicit buffers with the + ``.buffer()`` combinator—typically a buffer of size 2 is enough to allow a feedback loop to function. + +The new fusing behavior can be disabled by setting the configuration parameter ``akka.stream.materializer.auto-fusing=off``. +In that case you can still manually fuse those graphs which shall run on less Actors. Fusable elements are + + * all GraphStages (this includes all built-in junctions apart from ``groupBy``) + * all Stages (this includes all built-in linear operators) + * TCP connections Introduced proper named constructor methods insted of ``wrap()`` ================================================================ diff --git a/akka-docs-dev/rst/scala/migration-guide-1.0-2.x-scala.rst b/akka-docs-dev/rst/scala/migration-guide-1.0-2.x-scala.rst index e416b9fa2d..2cf07c3034 100644 --- a/akka-docs-dev/rst/scala/migration-guide-1.0-2.x-scala.rst +++ b/akka-docs-dev/rst/scala/migration-guide-1.0-2.x-scala.rst @@ -5,8 +5,43 @@ ############################ The 2.0 release contains some structural changes that require some -simple, mechanical source-level changes in client code. +simple, mechanical source-level changes in client code. While these are detailed below, +there is another change that may have an impact on the runtime behavior of your streams +and which therefore is listed first. +Operator Fusion is on by default +================================ + +Akka Streams 2.0 contains an initial version of stream operator fusion support. This means that +the processing steps of a flow or stream graph can be executed within the same Actor and has three +consequences: + + * starting up a stream may take longer than before due to executing the fusion algorithm + * passing elements from one processing stage to the next is a lot faster between fused + stages due to avoiding the asynchronous messaging overhead + * fused stream processing stages do no longer run in parallel to each other, meaning that + only up to one CPU core is used for each fused part + +The first point can be countered by pre-fusing and then reusing a stream blueprint, see ``akka.stream.Fusing``. +In order to balance the effects of the second and third bullet points you will have to insert asynchronous +boundaries manually into your flows and graphs by way of adding ``Attributes.asyncBoundary`` to pieces that +shall communicate with the rest of the graph in an asynchronous fashion. + +.. warning:: + + Without fusing (i.e. up to version 2.0-M2) each stream processing stage 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 + is needed in order to allow the stream to run at all, you will have to insert explicit buffers with the + ``.buffer()`` combinator—typically a buffer of size 2 is enough to allow a feedback loop to function. + +The new fusing behavior can be disabled by setting the configuration parameter ``akka.stream.materializer.auto-fusing=off``. +In that case you can still manually fuse those graphs which shall run on less Actors. Fusable elements are + + * all GraphStages (this includes all built-in junctions apart from ``groupBy``) + * all Stages (this includes all built-in linear operators) + * TCP connections Introduced proper named constructor methods insted of ``wrap()`` ================================================================ @@ -701,4 +736,4 @@ Example should be replaced by -.. includecode:: code/docs/MigrationsScala.scala#output-input-stream-source-sink \ No newline at end of file +.. includecode:: code/docs/MigrationsScala.scala#output-input-stream-source-sink