!str #16168: Expose materialized value in the graph as a "source"

akka-docs-dev/rst/scala/code/docs/stream/FlowGraphDocSpec.scala

@@ -8,7 +8,7 @@ import akka.stream.scaladsl._
 import akka.stream.testkit.AkkaSpec
 
 import scala.collection.immutable
-import scala.concurrent.Await
+import scala.concurrent.{ Future, Await }
 import scala.concurrent.duration._
 
 class FlowGraphDocSpec extends AkkaSpec {
@@ -20,7 +20,7 @@ class FlowGraphDocSpec extends AkkaSpec {
   "build simple graph" in {
     //format: OFF
     //#simple-flow-graph
-    val g = FlowGraph.closed() { implicit builder: FlowGraph.Builder =>
+    val g = FlowGraph.closed() { implicit builder: FlowGraph.Builder[Unit] =>
       import FlowGraph.Implicits._
       val in = Source(1 to 10)
       val out = Sink.ignore
@@ -43,7 +43,7 @@ class FlowGraphDocSpec extends AkkaSpec {
 
   "build simple graph without implicits" in {
     //#simple-flow-graph-no-implicits
-    val g = FlowGraph.closed() { builder: FlowGraph.Builder =>
+    val g = FlowGraph.closed() { builder: FlowGraph.Builder[Unit] =>
       val in = Source(1 to 10)
       val out = Sink.ignore
 
@@ -219,4 +219,33 @@ class FlowGraphDocSpec extends AkkaSpec {
 
   }
 
+  "access to materialized value" in {
+    //#flow-graph-matvalue
+    import FlowGraph.Implicits._
+    val foldFlow: Flow[Int, Int, Future[Int]] = Flow(Sink.fold[Int, Int](0)(_ + _)) {
+      implicit builder ⇒
+        fold ⇒
+          (fold.inlet, builder.matValue.mapAsync(identity).outlet)
+    }
+    //#flow-graph-matvalue
+
+    Await.result(Source(1 to 10).via(foldFlow).runWith(Sink.head), 3.seconds) should ===(55)
+
+    //#flow-graph-matvalue-cycle
+    import FlowGraph.Implicits._
+    // This cannot produce any value:
+    val cyclicFold: Source[Int, Future[Int]] = Source(Sink.fold[Int, Int](0)(_ + _)) {
+      implicit builder =>
+        fold =>
+          // - Fold cannot complete until its upstream mapAsync completes
+          // - mapAsync cannot complete until the materialized Future produced by
+          //   fold completes
+          // As a result this Source will never emit anything, and its materialited
+          // Future will never complete
+          builder.matValue.mapAsync(identity) ~> fold
+          builder.matValue.mapAsync(identity).outlet
+    }
+    //#flow-graph-matvalue-cycle
+  }
+
 }

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

@@ -210,6 +210,10 @@ resulting values. Some examples of using these combiners are illustrated in the
 
 .. includecode:: code/docs/stream/FlowDocSpec.scala#flow-mat-combine
 
+.. note::
+   In Graphs it is possible to access the materialized value from inside the stream processing graph. For details see
+   :ref:`graph-matvalue-scala`
+
 Stream ordering
 ===============
 In Akka Streams almost all computation stages *preserve input order* of elements. This means that if inputs ``{IA1,IA2,...,IAn}``

akka-docs-dev/rst/scala/stream-graphs.rst

@@ -248,6 +248,24 @@ together and also turned around with the ``.reversed`` method. The test
 simulates both parties of a network communication protocol without actually
 having to open a network connection—the flows can just be connected directly.
 
+.. _graph-matvalue-scala:
+
+Accessing the materialized value inside the Graph
+-------------------------------------------------
+
+In certain cases it might be necessary to feed back the materialized value of a Graph (partial, closed or backing a
+Source, Sink, Flow or BidiFlow). This is possible by using ``builder.matValue`` which gives an ``Outlet`` that
+can be used in the graph as an ordinary source or outlet, and which will eventually emit the materialized value.
+If the materialized value is needed at more than one place, it is possible to call ``matValue`` any number of times
+to acquire the necessary number of outlets.
+
+.. includecode:: code/docs/stream/FlowGraphDocSpec.scala#flow-graph-matvalue
+
+Be careful not to introduce a cycle where the materialized value actually contributes to the materialized value.
+The following example demonstrates a case where the materialized ``Future`` of a fold is fed back to the fold itself.
+
+.. includecode:: code/docs/stream/FlowGraphDocSpec.scala#flow-graph-matvalue-cycle
+
 .. _graph-cycles-scala:
 
 Graph cycles, liveness and deadlocks