From 23dd1170b0014117bfd3174021489b191b409d3a Mon Sep 17 00:00:00 2001 From: Patrik Nordwall Date: Fri, 11 Sep 2015 16:28:21 +0200 Subject: [PATCH] =per #18451 Recommend configuring stash capacity when persistence is used --- akka-docs/rst/java/lambda-actors.rst | 1 + akka-docs/rst/java/lambda-persistence.rst | 15 ++++++++++++++- akka-docs/rst/java/persistence.rst | 15 ++++++++++++++- akka-docs/rst/java/untyped-actors.rst | 2 ++ akka-docs/rst/scala/actors.rst | 1 + akka-docs/rst/scala/persistence.rst | 15 ++++++++++++++- 6 files changed, 46 insertions(+), 3 deletions(-) diff --git a/akka-docs/rst/java/lambda-actors.rst b/akka-docs/rst/java/lambda-actors.rst index d15c731a98..e9463bca28 100644 --- a/akka-docs/rst/java/lambda-actors.rst +++ b/akka-docs/rst/java/lambda-actors.rst @@ -788,6 +788,7 @@ behavior is not the default). .. includecode:: code/docs/actorlambda/ActorDocTest.java#swapper +.. _stash-lambda-java: Stash ===== diff --git a/akka-docs/rst/java/lambda-persistence.rst b/akka-docs/rst/java/lambda-persistence.rst index 7b4b46b1ef..05944cd568 100644 --- a/akka-docs/rst/java/lambda-persistence.rst +++ b/akka-docs/rst/java/lambda-persistence.rst @@ -117,7 +117,20 @@ about successful state changes by publishing events. When persisting events with ``persist`` it is guaranteed that the persistent actor will not receive further commands between the ``persist`` call and the execution(s) of the associated event handler. This also holds for multiple ``persist`` -calls in context of a single command. +calls in context of a single command. Incoming messages are :ref:`stashed ` until the ``persist`` +is completed. You should be careful to not send more messages to a persistent actor than it can keep up with, +otherwise the number of stashed messages will grow. It can be wise to protect against `OutOfMemoryError` +by defining a maximum stash capacity in the mailbox configuration:: + + akka.actor.default-mailbox.stash-capacity=10000 + +If the stash capacity is exceeded for an actor the stashed messages are discarded and a +``MessageQueueAppendFailedException`` is thrown, causing actor restart if default supervision +strategy is used. + +Note that the stash capacity is per actor. If you have many persistent actors, e.g. when using cluster sharding, +you may need to define a small stash capacity to ensure that the total number of stashed messages in the system +don't consume too much memory. If persistence of an event fails, ``onPersistFailure`` will be invoked (logging the error by default) and the actor will unconditionally be stopped. If persistence of an event is rejected before it is diff --git a/akka-docs/rst/java/persistence.rst b/akka-docs/rst/java/persistence.rst index 8548a41c7f..971202c78f 100644 --- a/akka-docs/rst/java/persistence.rst +++ b/akka-docs/rst/java/persistence.rst @@ -118,7 +118,20 @@ about successful state changes by publishing events. When persisting events with ``persist`` it is guaranteed that the persistent actor will not receive further commands between the ``persist`` call and the execution(s) of the associated event handler. This also holds for multiple ``persist`` -calls in context of a single command. +calls in context of a single command. Incoming messages are :ref:`stashed ` until the ``persist`` +is completed. You should be careful to not send more messages to a persistent actor than it can keep up with, +otherwise the number of stashed messages will grow. It can be wise to protect against `OutOfMemoryError` +by defining a maximum stash capacity in the mailbox configuration:: + + akka.actor.default-mailbox.stash-capacity=10000 + +If the stash capacity is exceeded for an actor the stashed messages are discarded and a +``MessageQueueAppendFailedException`` is thrown, causing actor restart if default supervision +strategy is used. + +Note that the stash capacity is per actor. If you have many persistent actors, e.g. when using cluster sharding, +you may need to define a small stash capacity to ensure that the total number of stashed messages in the system +don't consume too much memory. If persistence of an event fails, ``onPersistFailure`` will be invoked (logging the error by default) and the actor will unconditionally be stopped. If persistence of an event is rejected before it is diff --git a/akka-docs/rst/java/untyped-actors.rst b/akka-docs/rst/java/untyped-actors.rst index 2ffa9095de..bd33bba554 100644 --- a/akka-docs/rst/java/untyped-actors.rst +++ b/akka-docs/rst/java/untyped-actors.rst @@ -742,6 +742,8 @@ behavior is not the default). .. includecode:: code/docs/actor/UntypedActorSwapper.java#swapper +.. _stash-java: + Stash ===== diff --git a/akka-docs/rst/scala/actors.rst b/akka-docs/rst/scala/actors.rst index 41b6a60333..725f761090 100644 --- a/akka-docs/rst/scala/actors.rst +++ b/akka-docs/rst/scala/actors.rst @@ -787,6 +787,7 @@ Encoding Scala Actors nested receives without accidentally leaking memory See this `Unnested receive example <@github@/akka-docs/rst/scala/code/docs/actor/UnnestedReceives.scala>`_. +.. _stash-scala: Stash ===== diff --git a/akka-docs/rst/scala/persistence.rst b/akka-docs/rst/scala/persistence.rst index 787c89c286..b707cb82f8 100644 --- a/akka-docs/rst/scala/persistence.rst +++ b/akka-docs/rst/scala/persistence.rst @@ -102,7 +102,20 @@ about successful state changes by publishing events. When persisting events with ``persist`` it is guaranteed that the persistent actor will not receive further commands between the ``persist`` call and the execution(s) of the associated event handler. This also holds for multiple ``persist`` -calls in context of a single command. +calls in context of a single command. Incoming messages are :ref:`stashed ` until the ``persist`` +is completed. You should be careful to not send more messages to a persistent actor than it can keep up with, +otherwise the number of stashed messages will grow. It can be wise to protect against `OutOfMemoryError` +by defining a maximum stash capacity in the mailbox configuration:: + + akka.actor.default-mailbox.stash-capacity=10000 + +If the stash capacity is exceeded for an actor the stashed messages are discarded and a +``MessageQueueAppendFailedException`` is thrown, causing actor restart if default supervision +strategy is used. + +Note that the stash capacity is per actor. If you have many persistent actors, e.g. when using cluster sharding, +you may need to define a small stash capacity to ensure that the total number of stashed messages in the system +don't consume too much memory. If persistence of an event fails, ``onPersistFailure`` will be invoked (logging the error by default) and the actor will unconditionally be stopped. If persistence of an event is rejected before it is