Adding docs for KillSwitch #20265

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

@@ -0,0 +1,108 @@
+package docs.stream
+
+import akka.stream.scaladsl._
+import akka.stream.{ ActorMaterializer, DelayOverflowStrategy, KillSwitches }
+import akka.testkit.AkkaSpec
+import docs.CompileOnlySpec
+
+import scala.concurrent.Await
+import scala.concurrent.duration._
+
+class KillSwitchDocSpec extends AkkaSpec with CompileOnlySpec {
+
+  implicit val materializer = ActorMaterializer()
+
+  "Unique kill switch" must {
+
+    "control graph completion with shutdown" in compileOnlySpec {
+
+      // format: OFF
+      //#unique-shutdown
+      val countingSrc = Source(Stream.from(1)).delay(1.second, DelayOverflowStrategy.backpressure)
+      val lastSnk = Sink.last[Int]
+
+      val (killSwitch, last) = countingSrc
+        .viaMat(KillSwitches.single)(Keep.right)
+        .toMat(lastSnk)(Keep.both)
+        .run()
+
+      doSomethingElse()
+
+      killSwitch.shutdown()
+
+      Await.result(last, 1.second) shouldBe 2
+      //#unique-shutdown
+      // format: ON
+    }
+
+    "control graph completion with abort" in compileOnlySpec {
+
+      // format: OFF
+      //#unique-abort
+      val countingSrc = Source(Stream.from(1)).delay(1.second, DelayOverflowStrategy.backpressure)
+      val lastSnk = Sink.last[Int]
+
+      val (killSwitch, last) = countingSrc
+        .viaMat(KillSwitches.single)(Keep.right)
+        .toMat(lastSnk)(Keep.both).run()
+
+      val error = new RuntimeException("boom!")
+      killSwitch.abort(error)
+
+      Await.result(last.failed, 1.second) shouldBe error
+      //#unique-abort
+      // format: ON
+    }
+  }
+
+  "Shared kill switch" must {
+
+    "control graph completion with shutdown" in compileOnlySpec {
+      // format: OFF
+      //#shared-shutdown
+      val countingSrc = Source(Stream.from(1)).delay(1.second, DelayOverflowStrategy.backpressure)
+      val lastSnk = Sink.last[Int]
+      val sharedKillSwitch = KillSwitches.shared("my-kill-switch")
+
+      val last = countingSrc
+        .via(sharedKillSwitch.flow)
+        .runWith(lastSnk)
+
+      val delayedLast = countingSrc
+        .delay(1.second, DelayOverflowStrategy.backpressure)
+        .via(sharedKillSwitch.flow)
+        .runWith(lastSnk)
+
+      doSomethingElse()
+
+      sharedKillSwitch.shutdown()
+
+      Await.result(last, 1.second) shouldBe 2
+      Await.result(delayedLast, 1.second) shouldBe 1
+      //#shared-shutdown
+      // format: ON
+    }
+
+    "control graph completion with abort" in compileOnlySpec {
+
+      // format: OFF
+      //#shared-abort
+      val countingSrc = Source(Stream.from(1)).delay(1.second)
+      val lastSnk = Sink.last[Int]
+      val sharedKillSwitch = KillSwitches.shared("my-kill-switch")
+
+      val last1 = countingSrc.via(sharedKillSwitch.flow).runWith(lastSnk)
+      val last2 = countingSrc.via(sharedKillSwitch.flow).runWith(lastSnk)
+
+      val error = new RuntimeException("boom!")
+      sharedKillSwitch.abort(error)
+
+      Await.result(last1.failed, 1.second) shouldBe error
+      Await.result(last2.failed, 1.second) shouldBe error
+      //#shared-abort
+      // format: ON
+    }
+  }
+
+  private def doSomethingElse() = ???
+}

akka-docs/rst/scala/stream/index.rst

@@ -13,6 +13,7 @@ Streams
    stream-graphs
    stream-composition
    stream-rate
+   stream-dynamic
    stream-customize
    stream-integrations
    stream-error

akka-docs/rst/scala/stream/stream-dynamic.rst

@@ -0,0 +1,63 @@
+.. _stream-dynamic-scala:
+
+#######################
+Dynamic stream handling
+#######################
+
+.. _kill-switch-scala:
+
+Controlling graph completion with KillSwitch
+--------------------------------------------
+
+A ``KillSwitch`` allows the completion of graphs of ``FlowShape`` from the outside. It consists of a flow element that
+can be linked to a graph of ``FlowShape`` needing completion control.
+The ``KillSwitch`` trait allows to complete or fail the graph(s).
+
+.. includecode:: ../../../../akka-stream/src/main/scala/akka/stream/KillSwitch.scala
+   :include: kill-switch
+
+After the first call to either ``shutdown`` and ``abort``, all subsequent calls to any of these methods will be ignored.
+Graph completion is performed by both
+
+* completing its downstream
+* cancelling (in case of ``shutdown``) or failing (in case of ``abort``) its upstream.
+
+A ``KillSwitch`` can control the completion of one or multiple streams, and therefore comes in two different flavours.
+
+.. _unique-kill-switch-scala:
+
+UniqueKillSwitch
+^^^^^^^^^^^^^^^^
+
+``UniqueKillSwitch`` allows to control the completion of **one** materialized ``Graph`` of ``FlowShape``. Refer to the
+below for usage examples.
+
+* **Shutdown**
+
+.. includecode:: ../code/docs/stream/KillSwitchDocSpec.scala#unique-shutdown
+
+* **Abort**
+
+.. includecode:: ../code/docs/stream/KillSwitchDocSpec.scala#unique-abort
+
+.. _shared-kill-switch-scala:
+
+SharedKillSwitch
+^^^^^^^^^^^^^^^^
+
+A ``SharedKillSwitch`` allows to control the completion of an arbitrary number graphs of ``FlowShape``. It can be
+materialized multiple times via its ``flow`` method, and all materialized graphs linked to it are controlled by the switch.
+Refer to the below for usage examples.
+
+* **Shutdown**
+
+.. includecode:: ../code/docs/stream/KillSwitchDocSpec.scala#shared-shutdown
+
+* **Abort**
+
+.. includecode:: ../code/docs/stream/KillSwitchDocSpec.scala#shared-abort
+
+.. note::
+   A ``UniqueKillSwitch`` is always a result of a materialization, whilst ``SharedKillSwitch`` needs to be constructed
+   before any materialization takes place.
+