+doc: Updating basics, quickstart and some of graph docs

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

@@ -7,7 +7,7 @@ import akka.actor.Cancellable
 import akka.stream.scaladsl._
 import akka.stream.testkit.AkkaSpec
 
-import concurrent.Future
+import scala.concurrent.{ Promise, Future }
 
 class FlowDocSpec extends AkkaSpec {
 
@@ -54,7 +54,7 @@ class FlowDocSpec extends AkkaSpec {
     //#materialization-runWith
   }
 
-  "materializedMap is unique" in {
+  "materialization is unique" in {
     //#stream-reuse
     // connect the Source to the Sink, obtaining a RunnableFlow
     val sink = Sink.fold[Int, Int](0)(_ + _)
@@ -108,10 +108,10 @@ class FlowDocSpec extends AkkaSpec {
     Source.empty
 
     // Sink that folds over the stream and returns a Future
-    // of the final result in the MaterializedMap
+    // of the final result as its materialized value
     Sink.fold[Int, Int](0)(_ + _)
 
-    // Sink that returns a Future in the MaterializedMap,
+    // Sink that returns a Future as its materialized value,
     // containing the first element of the stream
     Sink.head
 
@@ -138,4 +138,79 @@ class FlowDocSpec extends AkkaSpec {
 
     //#flow-connecting
   }
+
+  "various ways of transforming materialized values" in {
+    import scala.concurrent.duration._
+
+    val throttler = Flow(Source(1.second, 1.second, "test")) { implicit builder =>
+      tickSource =>
+        import FlowGraph.Implicits._
+        val zip = builder.add(ZipWith[String, Int, Int](Keep.right))
+        tickSource ~> zip.in0
+        (zip.in1, zip.out)
+    }
+
+    //#flow-mat-combine
+    // An empty source that can be shut down explicitly from the outside
+    val source: Source[Int, Promise[Unit]] = Source.lazyEmpty[Int]()
+
+    // A flow that internally throttles elements to 1/second, and returns a Cancellable
+    // which can be used to shut down the stream
+    val flow: Flow[Int, Int, Cancellable] = throttler
+
+    // A sink that returns the first element of a stream in the returned Future
+    val sink: Sink[Int, Future[Int]] = Sink.head[Int]()
+
+    // By default, the materialized value of the leftmost stage is preserved
+    val r1: RunnableFlow[Promise[Unit]] = source.via(flow).to(sink)
+
+    // Simple selection of materialized values by using Keep.right
+    val r2: RunnableFlow[Cancellable] = source.viaMat(flow)(Keep.right).to(sink)
+    val r3: RunnableFlow[Future[Int]] = source.via(flow).toMat(sink)(Keep.right)
+
+    // Using runWith will always give the materialized values of the stages added
+    // by runWith() itself
+    val r4: Future[Int] = source.via(flow).runWith(sink)
+    val r5: Promise[Unit] = flow.to(sink).runWith(source)
+    val r6: (Promise[Unit], Future[Int]) = flow.runWith(source, sink)
+
+    // Using more complext combinations
+    val r7: RunnableFlow[(Promise[Unit], Cancellable)] =
+      source.viaMat(flow)(Keep.both).to(sink)
+
+    val r8: RunnableFlow[(Promise[Unit], Future[Int])] =
+      source.via(flow).toMat(sink)(Keep.both)
+
+    val r9: RunnableFlow[((Promise[Unit], Cancellable), Future[Int])] =
+      source.viaMat(flow)(Keep.both).toMat(sink)(Keep.both)
+
+    val r10: RunnableFlow[(Cancellable, Future[Int])] =
+      source.viaMat(flow)(Keep.right).toMat(sink)(Keep.both)
+
+    // It is also possible to map over the materialized values. In r9 we had a
+    // doubly nested pair, but we want to flatten it out
+    val r11: RunnableFlow[(Promise[Unit], Cancellable, Future[Int])] =
+      r9.mapMaterialized {
+        case ((promise, cancellable), future) =>
+          (promise, cancellable, future)
+      }
+
+    // Now we can use pattern matching to get the resulting materialized values
+    val (promise, cancellable, future) = r11.run()
+
+    // Type inference works as expected
+    promise.success(0)
+    cancellable.cancel()
+    future.map(_ + 3)
+
+    // The result of r11 can be also achieved by using the Graph API
+    val r12: RunnableFlow[(Promise[Unit], Cancellable, Future[Int])] =
+      FlowGraph.closed(source, flow, sink)((_, _, _)) { implicit builder =>
+        (src, f, dst) =>
+          import FlowGraph.Implicits._
+          src ~> f ~> dst
+      }
+
+    //#flow-mat-combine
+  }
 }