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

Merge pull request #19626 from MQ-EL/master

Browse source 
=per #19551 support stash overflow strategy
This commit is contained in:
Roland Kuhn 2016-02-16 13:50:40 +01:00
commit 2f9cc7d04f
8 changed files with 352 additions and 50 deletions
Download patch file Download diff file Expand all files Collapse all files

58
akka-docs/rst/scala/persistence.rst
View file

@ -102,20 +102,8 @@ 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. Incoming messages are :ref:`stashed <stash-scala>` 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.
calls in context of a single command. Incoming messages are :ref:`stashed <internal-stash>` until the ``persist``
is completed.
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
@ -187,6 +175,48 @@ and before any other received messages.
If there is a problem with recovering the state of the actor from the journal, ``onRecoveryFailure``
is called (logging the error by default) and the actor will be stopped.
.. _internal-stash:
Internal stash
--------------
The persistent actor has a private :ref:`stash <stash-scala>` for internally caching incoming messages during
:ref:`recovery` or the ``persist\persistAll`` method persisting events. However You can use inherited stash or create
one or more stashes if needed. The internal stash doesn't interfere with these stashes apart from user inherited
``unstashAll`` method, which prepends all messages in the inherited stash to the internal stash instead of mailbox.
Hence, If the message in the inherited stash need to be handled after the messages in the internal stash, you should
call inherited ``unstash`` method.
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
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. Additionally, The persistent actor defines three strategies to handle failure when the
internal stash capacity is exceeded. The default overflow strategy is the ``ThrowOverflowExceptionStrategy``, which
discards the current received message and throws a ``StashOverflowException``, causing actor restart if default
supervision strategy is used. you can override the ``internalStashOverflowStrategy`` method to return
``DiscardToDeadLetterStrategy`` or ``ReplyToStrategy`` for any "individual" persistent actor, or define the "default"
for all persistent actors by providing FQCN, which must be a subclass of ``StashOverflowStrategyConfigurator``, in the
persistence configuration::
akka.persistence.internal-stash-overflow-strategy=
"akka.persistence.ThrowExceptionConfigurator"
The ``DiscardToDeadLetterStrategy`` strategy also has a pre-packaged companion configurator
``akka.persistence.DiscardConfigurator``.
You can also query default strategy via the Akka persistence extension singleton::
Persistence(context.system).defaultInternalStashOverflowStrategy
.. note::
The bounded mailbox should be avoid in the persistent actor, because it may be discarding the messages come from
Storage backends. You can use bounded stash instead of bounded mailbox.
.. _persist-async-scala:
Relaxed local consistency requirements and high throughput use-cases