akka.actor
Interface Stash

All Superinterfaces:
Actor, RequiresMessageQueue<DequeBasedMessageQueueSemantics>, UnrestrictedStash
All Known Subinterfaces:
Creators.ActWithStash, akka.persistence.Eventsourced, EventsourcedProcessor, Processor, Recovery, View
All Known Implementing Classes:
AbstractActorWithStash, AbstractEventsourcedProcessor, AbstractProcessor, AbstractView, ClusterClient, ClusterSingletonProxy, ShardCoordinator, UntypedActorWithStash, UntypedEventsourcedProcessor, UntypedProcessor, UntypedView

public interface Stash
extends UnrestrictedStash, RequiresMessageQueue<DequeBasedMessageQueueSemantics>

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. By default Stash based actors request a Deque based mailbox since the stash trait extends RequiresMessageQueue[DequeBasedMessageQueueSemantics]. You can override the default mailbox provided when DequeBasedMessageQueueSemantics are requested via config:

    akka.actor.mailbox.requirements {
      "akka.dispatch.BoundedDequeBasedMessageQueueSemantics" = your-custom-mailbox
    }
  
Alternatively, you can add your own requirement marker to the actor and configure a mailbox type to be used for your marker.

For a Stash that also enforces unboundedness of the deque see UnboundedStash. For a Stash that does not enforce any mailbox type see UnrestrictedStash.

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.


Nested Class Summary
 
Nested classes/interfaces inherited from interface akka.actor.Actor
Actor.emptyBehavior$
 
Method Summary
 akka.actor.ActorCell actorCell()
           
 int capacity()
           
 scala.collection.immutable.Vector<Envelope> clearStash()
          INTERNAL API.
 ActorContext context()
          INTERNAL API.
 void enqueueFirst(Envelope envelope)
          Enqueues envelope at the first position in the mailbox.
 DequeBasedMessageQueueSemantics mailbox()
          INTERNAL API.
 void prepend(scala.collection.immutable.Seq<Envelope> others)
          Prepends others to this stash.
 ActorRef self()
          INTERNAL API.
 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 unstash()
          Prepends the oldest message in the stash to the mailbox, and then removes that message from the stash.
 void unstashAll()
          Prepends all messages in the stash to the mailbox, and then clears the stash.
 void unstashAll(scala.Function1<java.lang.Object,java.lang.Object> filterPredicate)
          INTERNAL API.
 
Methods inherited from interface akka.actor.UnrestrictedStash
postStop, preRestart
 
Methods inherited from interface akka.actor.Actor
aroundPostRestart, aroundPostStop, aroundPreRestart, aroundPreStart, aroundReceive, context, noSender, postRestart, preStart, receive, self, sender, supervisorStrategy, unhandled
 

Method Detail

context

ActorContext context()
INTERNAL API.

Context of the actor that uses this stash.


self

ActorRef self()
INTERNAL API.

Self reference of the actor that uses this stash.


theStash

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

actorCell

akka.actor.ActorCell actorCell()

capacity

int capacity()

mailbox

DequeBasedMessageQueueSemantics mailbox()
INTERNAL API.

The actor's deque-based message queue. mailbox.queue is the underlying Deque.


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

prepend

void prepend(scala.collection.immutable.Seq<Envelope> others)
Prepends others to this stash. This method is optimized for a large stash and small others.


unstash

void unstash()
Prepends the oldest message in the stash to the mailbox, and then removes that message from 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 unstashed message is guaranteed to be removed from the stash regardless if the unstash() call successfully returns or throws an exception.


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().


unstashAll

void unstashAll(scala.Function1<java.lang.Object,java.lang.Object> filterPredicate)
INTERNAL API.

Prepends selected messages in the stash, applying filterPredicate, 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(Any => Boolean).

Parameters:
filterPredicate - only stashed messages selected by this predicate are prepended to the mailbox.

clearStash

scala.collection.immutable.Vector<Envelope> clearStash()
INTERNAL API.

Clears the stash and and returns all envelopes that have not been unstashed.


enqueueFirst

void enqueueFirst(Envelope envelope)
Enqueues envelope at the first position in the mailbox. If the message contained in the envelope is a Terminated message, it will be ensured that it can be re-received by the actor.