Stashing

Stashing lets an actor temporarily buffer messages instead of processing them. Use it when the actor cannot handle certain messages in its current state (e.g., waiting for a resource, or during a behavior transition).

Enabling stashing

Pass WithStashing() as a SpawnOption:

Enabling stashing

pid, err := system.Spawn(ctx, "my-actor", actor, actor.WithStashing())

Without WithStashing(), calls to Stash, Unstash, or UnstashAll record ErrStashBufferNotSet.

API

ctx.Stash: Buffer the current message. It will not be processed until unstashed. The message is moved to a side buffer; the actor continues with the next message.
ctx.Unstash: Take the oldest stashed message and send it to the actor again. It is appended to the mailbox, so it is handled after the messages already queued.
ctx.UnstashAll: Send every stashed message to the actor again, oldest first, behind the messages already queued.

Stashed messages are processed in FIFO order when unstashed.

When to use

Behavior transitions: Stash messages you cannot handle in the current behavior; unstash after switching.
Conditional processing: Stash messages until a condition is met (e.g., dependency ready, lock acquired).
Reentrancy: With StashNonReentrant mode, in-flight Ask requests cause user messages to be stashed automatically until the request completes.

Example

A gate actor that buffers requests until opened:

Example

package main

import (
    "context"
    "fmt"
    "time"

    "github.com/tochemey/goakt/v4/actor"
)

type Open struct{}
type Request struct{ Id string }

type GateActor struct {
    open   bool
    served []string
}

func (a *GateActor) PreStart(ctx *actor.Context) error { return nil }
func (a *GateActor) PostStop(ctx *actor.Context) error  { return nil }

func (a *GateActor) Receive(ctx *actor.ReceiveContext) {
    switch msg := ctx.Message().(type) {
    case *Open:
        a.open = true
        ctx.UnstashAll()
    case *Request:
        if a.open {
            a.served = append(a.served, msg.Id)
        } else {
            ctx.Stash()
        }
    default:
        ctx.Unhandled()
    }
}

func main() {
    ctx := context.Background()
    system, _ := actor.NewActorSystem("stash-demo", actor.WithLoggingDisabled())
    _ = system.Start(ctx)
    defer system.Stop(ctx)

    gate := &GateActor{}
    pid, _ := system.Spawn(ctx, "gate", gate, actor.WithStashing())

    // Request arrives before gate is open -> stashed
    _ = actor.Tell(ctx, pid, &Request{Id: "req-1"})
    _ = actor.Tell(ctx, pid, &Request{Id: "req-2"})
    time.Sleep(10 * time.Millisecond)

    // Open gate -> unstashes and processes req-1, req-2
    _ = actor.Tell(ctx, pid, &Open{})
    time.Sleep(10 * time.Millisecond)

    fmt.Println("Served:", gate.served) // [req-1 req-2]
}

Stash size

pid.StashSize() returns the number of messages currently in the stash. Useful for metrics or backpressure.

Stash and lifecycle

A restart keeps the stash. Messages the actor stashed on its own stay stashed for the new incarnation to unstash when it decides to; messages a StashNonReentrant request had stashed are replayed to the new incarnation after PostStart (see Reentrancy). A stop drops the stashed messages with the mailbox: an actor restarted later under the same name starts with an empty stash and can stash again.

Quickstart

Actors

Grains

AI Agents

Remoting

Clustering

Advanced

Architecture

Enabling stashing

API

When to use

Example

Stash size

Stash and lifecycle

​Enabling stashing

​API

​When to use

​Example

​Stash size

​Stash and lifecycle

Enabling stashing

API

When to use

Example

Stash size

Stash and lifecycle