Merge pull request #19754 from akka/wip-19732-async-RK

nicer declarative .async boundaries and remove Module.nest()

akka-docs/rst/java/code/docs/stream/FlowDocTest.java

@@ -287,8 +287,7 @@ public class FlowDocTest {
     
     //#flow-async
     Source.range(1, 3)
-        .map(x -> x + 1)
-        .withAttributes(Attributes.asyncBoundary())
+        .map(x -> x + 1).async()
         .map(x -> x * 2)
         .to(Sink.ignore());
     //#flow-async

akka-docs/rst/java/code/docs/stream/MigrationsJava.java

@@ -5,6 +5,7 @@ package docs.stream;
 
 import java.util.stream.Stream;
 
+import akka.NotUsed;
 import akka.japi.Pair;
 import akka.stream.javadsl.*;
 //#asPublisher-import
@@ -27,6 +28,11 @@ public class MigrationsJava {
     Sink.asPublisher(WITH_FANOUT);    // instead of Sink.asPublisher(true)
     Sink.asPublisher(WITHOUT_FANOUT); // instead of Sink.asPublisher(false)
     //#asPublisher
+
+    //#async
+    Flow<Integer, Integer, NotUsed> flow = Flow.of(Integer.class).map(n -> n + 1);
+    Source.range(1, 10).via(flow.async());
+    //#async
   }
 
 }

akka-docs/rst/java/stream/migration-guide-2.0-2.4-java.rst

@@ -104,6 +104,21 @@ Which is the same as using ``conflateWithSeed`` with an identity function::
 
    Flow.of(Integer.class).conflateWithSeed(x -> x, (a, b) -> a + b) // Add numbers while downstream is not ready
 
+
+``viaAsync`` and ``viaAsyncMat`` has been replaced with ``async()``
+-------------------------------------------------------------------
+``async()`` is available from ``Sink``, ``Source``, ``Flow`` and the sub flows. It provides a shortcut for
+setting the attribute ``Attributes.asyncBoundary`` on a flow. The existing methods ``Flow.viaAsync`` and
+``Flow.viaAsyncMat`` has been removed to make marking out asynchronous boundaries more consistent::
+
+    // This no longer works
+    source.viaAsync(flow)
+
+In Akka 2.4.x this will instead look lile this:
+
+.. includecode:: ../code/docs/stream/MigrationsJava.java#async
+
+
 Changed Sources / Sinks
 =======================
 

akka-docs/rst/java/stream/stream-flows-and-basics.rst

@@ -243,8 +243,9 @@ The first point can be countered by pre-fusing and then reusing a stream bluepri
 .. includecode:: ../code/docs/stream/FlowDocTest.java#explicit-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.
+boundaries manually into your flows and graphs by way of adding ``Attributes.asyncBoundary`` using the method
+``async`` on ``Source``, ``Sink`` and ``Flow`` to pieces that shall communicate with the rest of the graph in
+an asynchronous fashion.
 
 .. includecode:: ../code/docs/stream/FlowDocTest.java#flow-async
 

akka-docs/rst/scala/code/docs/stream/FlowDocSpec.scala

@@ -237,11 +237,8 @@ class FlowDocSpec extends AkkaSpec {
 
   "defining asynchronous boundaries" in {
     //#flow-async
-    import akka.stream.Attributes.asyncBoundary
-
     Source(List(1, 2, 3))
-      .map(_ + 1)
-      .withAttributes(asyncBoundary)
+      .map(_ + 1).async
       .map(_ * 2)
       .to(Sink.ignore)
     //#flow-async

akka-docs/rst/scala/code/docs/stream/MigrationsScala.scala

@@ -23,6 +23,11 @@ class MigrationsScala extends AkkaSpec {
           })
         })
         //#expand-state
+
+        //#async
+        val flow = Flow[Int].map(_ + 1)
+        Source(1 to 10).via(flow.async)
+        //#async
       }
     }
   }

akka-docs/rst/scala/stream/migration-guide-2.0-2.4-scala.rst

@@ -91,6 +91,21 @@ Which is the same as using ``conflateWithSeed`` with an identity function
 
    Flow[Int].conflateWithSeed(identity)(_ + _) // Add numbers while downstream is not ready
 
+
+``viaAsync`` and ``viaAsyncMat`` has been replaced with ``async``
+-----------------------------------------------------------------
+``async`` is available from ``Sink``, ``Source``, ``Flow`` and the sub flows. It provides a shortcut for
+setting the attribute ``Attributes.asyncBoundary`` on a flow. The existing methods ``Flow.viaAsync`` and
+``Flow.viaAsyncMat`` has been removed to make marking out asynchronous boundaries more consistent::
+
+    // This no longer works
+    source.viaAsync(flow)
+
+In Akka 2.4.x this will instead look lile this:
+
+.. includecode:: ../code/docs/stream/MigrationsScala.scala#async
+
+
 Changes in Akka HTTP
 ====================
 

akka-docs/rst/scala/stream/stream-flows-and-basics.rst

@@ -245,8 +245,9 @@ The first point can be countered by pre-fusing and then reusing a stream bluepri
 .. includecode:: ../code/docs/stream/FlowDocSpec.scala#explicit-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.
+boundaries manually into your flows and graphs by way of adding ``Attributes.asyncBoundary`` using the method
+``async`` on ``Source``, ``Sink`` and ``Flow`` to pieces that shall communicate with the rest of the graph in an
+asynchronous fashion.
 
 .. includecode:: ../code/docs/stream/FlowDocSpec.scala#flow-async