From f385380cc277e40d323e086896251faa34f29d3b Mon Sep 17 00:00:00 2001
From: phaller <hallerp@gmail.com>
Date: Tue, 12 Jun 2012 15:51:54 +0200
Subject: [PATCH] Adding Stash section in Actors docs. Including example added
 to ActorDocSpec.

---
 akka-docs/scala/actors.rst                    | 42 +++++++++++++++++++
 .../scala/code/docs/actor/ActorDocSpec.scala  | 20 +++++++++
 2 files changed, 62 insertions(+)

diff --git a/akka-docs/scala/actors.rst b/akka-docs/scala/actors.rst
index 4a556cf6c2..15ec6c9054 100644
--- a/akka-docs/scala/actors.rst
+++ b/akka-docs/scala/actors.rst
@@ -627,6 +627,48 @@ Here's how you use the ``unbecome`` method:
   }
 
 
+Stash
+=====
+
+The `Stash` trait enables an actor to temporarily stash away messages
+that can not or should not be handled using the actor's current
+behavior. Upon changing the actor's message handler, i.e., right
+before invoking ``context.become`` or ``context.unbecome``, all
+stashed messages can be "unstashed" by prepending them to the actor's
+mailbox. This way, the stashed messages can be processed in the same
+order as they have been received originally.
+
+.. warning::
+
+  Please note that the ``Stash`` can only be used together with actors
+  that have a deque-based mailbox. For this, configure the
+  ``mailbox-type`` of the dispatcher to be a deque-based mailbox, such as
+  ``akka.dispatch.UnboundedDequeBasedMailbox``.
+
+Here is an example of the ``Stash`` in action:
+
+.. includecode:: code/docs/actor/ActorDocSpec.scala#stash
+
+Invoking ``stash()`` adds the current message (the message that the
+actor received last) to the actor's stash. It is typically invoked
+when handling the default case in the actor's message handler to stash
+messages that aren't handled by the other cases. It is illegal to
+stash the same message twice; to do so results in a
+``IllegalStateException`` being thrown. The stash may also be bounded
+in which case invoking ``stash()`` may lead to a capacity violation,
+which results in a ``StashOverflowException``. The capacity of the
+stash can be configured using the ``stash-capacity`` setting (an ``Int``) of the
+dispatcher's configuration.
+
+Invoking ``unstashAll()`` enqueues messages from the stash to the
+actor's mailbox until the capacity of the mailbox (if any) has been
+reached (note that messages from the stash are prepended to the
+mailbox). In case a bounded mailbox overflows, a
+``MessageQueueAppendFailedException`` is thrown.
+The stash is guaranteed to be empty after calling ``unstashAll()``.
+
+
+
 Killing an Actor
 ================
 
diff --git a/akka-docs/scala/code/docs/actor/ActorDocSpec.scala b/akka-docs/scala/code/docs/actor/ActorDocSpec.scala
index ee05e95d42..108aba33b2 100644
--- a/akka-docs/scala/code/docs/actor/ActorDocSpec.scala
+++ b/akka-docs/scala/code/docs/actor/ActorDocSpec.scala
@@ -300,6 +300,26 @@ class ActorDocSpec extends AkkaSpec(Map("akka.loglevel" -> "INFO")) {
     val actor = system.actorOf(Props(new HotSwapActor), name = "hot")
   }
 
+  "using Stash" in {
+    //#stash
+    import akka.actor.Stash
+    class ActorWithProtocol extends Actor with Stash {
+      def receive = {
+        case "open" ⇒
+          unstashAll()
+          context.become {
+            case "write" ⇒ // do writing...
+            case "close" ⇒
+              unstashAll()
+              context.unbecome()
+            case msg ⇒ stash()
+          }
+        case msg ⇒ stash()
+      }
+    }
+    //#stash
+  }
+
   "using watch" in {
     //#watch
     import akka.actor.{ Actor, Props, Terminated }