raboof/pekko
1
0
Fork 0
Code Issues Pull requests Projects Releases 6 Packages Wiki Activity Actions 10

Adding docs for KillSwitch #20265

Browse source
This commit is contained in:
Stefano Bonetti 2016-06-03 13:23:11 +01:00 • committed by Johan Andrén
parent 896ea53dd3
commit b84c6c5271
7 changed files with 380 additions and 2 deletions
Download patch file Download diff file Expand all files Collapse all files

63
akka-docs/rst/java/stream/stream-dynamic.rst Normal file
View file

@ -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/KillSwitchDocTest.java#unique-shutdown
* **Abort**
.. includecode:: ../code/docs/stream/KillSwitchDocTest.java#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/KillSwitchDocTest.java#shared-shutdown
* **Abort**
.. includecode:: ../code/docs/stream/KillSwitchDocTest.java#shared-abort
.. note::
A ``UniqueKillSwitch`` is always a result of a materialization, whilst ``SharedKillSwitch`` needs to be constructed
before any materialization takes place.