akka.actor
Interface Stash

All Known Subinterfaces:

Creators.ActWithStash

All Known Implementing Classes:

UntypedActorWithStash

public interface 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.

Example:

    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()
          }, discardOld = false)
        case "done" ⇒ // done
        case msg    ⇒ stash()
      }
    }
  

Note that the Stash trait can only be used together with actors that have a deque-based mailbox. Actors can be configured to use a deque-based mailbox using a configuration like the following (see the documentation on dispatchers on how to configure a custom dispatcher):

  akka {
    actor {
      my-custom-dispatcher {
        mailbox-type = "akka.dispatch.UnboundedDequeBasedMailbox"
      }
    }
  }
  

Note that the Stash trait must be mixed into (a subclass of) the Actor trait before any trait/class that overrides the preRestart callback. This means it's not possible to write Actor with MyActor with Stash if MyActor overrides preRestart.

Method Summary

int	capacity()
DequeBasedMessageQueue	mailbox()
void	postStop() Overridden callback.
void	preRestart(java.lang.Throwable reason, scala.Option<java.lang.Object> message) Overridden callback.
void	stash() Adds the current message (the message that the actor received last) to the actor's stash.
scala.collection.immutable.Vector<Envelope>	theStash()
void	unstashAll() Prepends all messages in the stash to the mailbox, and then clears the stash.

Method Detail

theStash

scala.collection.immutable.Vector<Envelope> theStash()

capacity

int capacity()

mailbox

DequeBasedMessageQueue mailbox()

stash

void stash()

Adds the current message (the message that the actor received last) to the actor's stash.

Throws:

StashOverflowException - in case of a stash capacity violation

java.lang.IllegalStateException - if the same message is stashed more than once

unstashAll

void unstashAll()

Prepends all messages in the stash to the mailbox, and then clears the stash.

Messages from the stash are enqueued to the mailbox until the capacity of the mailbox (if any) has been reached. In case a bounded mailbox overflows, a MessageQueueAppendFailedException is thrown.

The stash is guaranteed to be empty after calling unstashAll().

preRestart

void preRestart(java.lang.Throwable reason,
                scala.Option<java.lang.Object> message)

Overridden callback. Prepends all messages in the stash to the mailbox, clears the stash, stops all children and invokes the postStop() callback.

postStop

void postStop()

Overridden callback. Prepends all messages in the stash to the mailbox and clears the stash. Must be called when overriding this method, otherwise stashed messages won't be propagated to DeadLetters when actor stops.