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

+str #15750 Prototype of stream supervision

Browse source 
* add supervion for stages and built in ops run by interpreter
* add supervision for mapAsync and mapAsyncUnordered
* add supervision to groupBy and splitWhen
* reference doc for scala and java
This commit is contained in:
Patrik Nordwall 2015-02-04 09:26:32 +01:00
parent 3b46966240
commit 693dcbefcc
33 changed files with 1563 additions and 179 deletions
Download patch file Download diff file Expand all files Collapse all files

71
akka-docs-dev/rst/java/stream-error.rst Normal file
View file

@ -0,0 +1,71 @@
.. _stream-error-java:
##############
Error Handling
##############
Strategies for how to handle exceptions from processing stream elements can be defined when
materializing the stream. The error handling strategies are inspired by actor supervision
strategies, but the semantics has been adapted to the domain of stream processing.
Supervision Strategies
======================
There are three ways to handle exceptions from application code:
* ``Stop`` - The stream is completed with failure.
* ``Resume`` - The element is dropped and the stream continues.
* ``Restart`` - The element is dropped and the stream continues after restarting the stage.
Restarting a stage means that any accumulated state is cleared. This is typically
performed by creating a new instance of the stage.
By default the stopping strategy is used for all exceptions, i.e. the stream will be completed with
failure when an exception is thrown.
.. includecode:: ../../../akka-samples/akka-docs-java-lambda/src/test/java/docs/stream/FlowErrorDocTest.java#stop
The default supervision strategy for a stream can be defined on the settings of the materializer.
.. includecode:: ../../../akka-samples/akka-docs-java-lambda/src/test/java/docs/stream/FlowErrorDocTest.java#resume
Here you can see that all ``ArithmeticException`` will resume the processing, i.e. the
elements that cause the division by zero are effectively dropped.
Be aware that dropping elements may result in deadlocks in graphs with cycles, as explained in :ref:`graph-cycles-java`.
The supervision strategy can also be defined for a section of flow operators.
.. includecode:: ../../../akka-samples/akka-docs-java-lambda/src/test/java/docs/stream/FlowErrorDocTest.java#resume-section
``Restart`` works in a similar way as ``Resume`` with the addition that accumulated state,
if any, of the failing processing stage will be reset.
.. includecode:: ../../../akka-samples/akka-docs-java-lambda/src/test/java/docs/stream/FlowErrorDocTest.java#restart-section
Errors from mapAsync
====================
Stream supervision can also be applied to the futures of ``mapAsync``.
Let's say that we use an external service to lookup email addresses and we would like to
discard those that cannot be found.
We start with the tweet stream of authors:
.. includecode:: ../../../akka-samples/akka-docs-java-lambda/src/test/java/docs/stream/IntegrationDocTest.java#tweet-authors
Assume that we can lookup their email address using:
.. includecode:: ../../../akka-samples/akka-docs-java-lambda/src/test/java/docs/stream/IntegrationDocTest.java#email-address-lookup2
The ``Future`` is completed with ``Failure`` if the email is not found.
Transforming the stream of authors to a stream of email addresses by using the ``lookupEmail``
service can be done with ``mapAsync`` and we use ``Supervision.getResumingDecider`` to drop
unknown email addresses:
.. includecode:: ../../../akka-samples/akka-docs-java-lambda/src/test/java/docs/stream/IntegrationDocTest.java#email-addresses-mapAsync-supervision
If we would not use ``Resume`` the default stopping strategy would complete the stream
with failure on the first ``Future`` that was completed with ``Failure``.

1
akka-docs-dev/rst/java/stream-index.rst
View file

@ -14,6 +14,7 @@ Streams
stream-rate
stream-customize
stream-integrations
stream-error
stream-io
stream-cookbook
../stream-configuration