Stash docs: add paragraphs about performance and restarts

akka-docs/java/untyped-actors.rst

@@ -599,6 +599,14 @@ mailbox). In case a bounded mailbox overflows, a
 ``MessageQueueAppendFailedException`` is thrown.
 The stash is guaranteed to be empty after calling ``unstashAll()``.
 
+The stash is backed by a ``scala.collection.immutable.Vector``. As a
+result, even a very large number of messages may be stashed without a
+major impact on performance.
+
+Note that the stash is not persisted across restarts of an actor,
+unlike the actor's mailbox. Therefore, it should be managed like other
+parts of the actor's state which have the same property.
+
 
 Killing an Actor
 ================

akka-docs/scala/actors.rst

@@ -660,6 +660,10 @@ mailbox). In case a bounded mailbox overflows, a
 ``MessageQueueAppendFailedException`` is thrown.
 The stash is guaranteed to be empty after calling ``unstashAll()``.
 
+The stash is backed by a ``scala.collection.immutable.Vector``. As a
+result, even a very large number of messages may be stashed without a
+major impact on performance.
+
 .. warning::
 
   Note that the ``Stash`` trait must be mixed into (a subclass of) the
@@ -667,6 +671,10 @@ The stash is guaranteed to be empty after calling ``unstashAll()``.
   callback. This means it's not possible to write
   ``Actor with MyActor with Stash`` if ``MyActor`` overrides ``preRestart``.
 
+Note that the stash is not persisted across restarts of an actor,
+unlike the actor's mailbox. Therefore, it should be managed like other
+parts of the actor's state which have the same property.
+
 
 Killing an Actor
 ================