tellus
How-to guides

Defer messages while an actor waits

Stash the requests which arrive while an actor waits for a piped future, and answer them in order once it has what it needs.

receive is a plain function, so an actor pipes async code to itself and keeps handling messages while the future runs. A request which needs the future's output cannot be answered before it arrives, and a stash defers it until then. The actor keeps receive synchronous and decides for each message whether it waits; an await would defer everything.

The examples on this page come from the directory actor of the previous page. It now loads its whole customer table once, at startup, and answers lookups from it.

Declare a stash

Stashing is opt-in per actor type. Every actor declares type Stash. With Unstashed, the context has no stash and no unstash_all, and the actor runs a loop without stash code. Stashed adds the two methods:

tellus/examples/how_to/defer_messages.rs
type Message = Message;
type Timers = Untimed;
type Stash = Stashed;
type State = State;
type Error = !;

The mode is the context's third type parameter, which defaults to Unstashed. init and receive take &ActorContext<Self::Message, Self::Timers, Self::Stash>, as init below shows.

Pipe the future and wait

init starts the load and returns the state Loading. The table arrives later as the Loaded message:

tellus/examples/how_to/defer_messages.rs
fn init(
    &self,
    context: &ActorContext<Self::Message, Self::Timers, Self::Stash>,
) -> Result<Self::State, Self::Error> {
    context.pipe_to_self(load_customers(), Message::Loaded);
    Ok(State::Loading)
}

The load itself is an ordinary async function, here a simulated database read which takes 300 ms:

tellus/examples/how_to/defer_messages.rs
async fn load_customers() -> HashMap<u64, String> {
    sleep(Duration::from_millis(300)).await;

    [(1, "Alice"), (2, "Bob"), (3, "Carol")]
        .into_iter()
        .map(|(id, name)| (id, name.to_string()))
        .collect()
}
tellus/examples/how_to/defer_messages.rs
enum State {
    Loading,
    Ready { customers: HashMap<u64, String> },
}
tellus/examples/how_to/defer_messages.rs
enum Message {
    Lookup {
        id: u64,
        reply_to: ReplyTo<Result<String, LookupError>>,
    },

    Loaded(HashMap<u64, String>),
}

Stash while waiting

While the table loads, the actor stashes every incoming but Loaded, since it cannot answer a lookup yet. stash takes the Incoming as receive got it, which keeps a terminated signal in its place behind the messages of the stopped actor:

tellus/examples/how_to/defer_messages.rs
(State::Loading, Incoming::Message(Message::Loaded(customers))) => {
    println!("Loaded {} customers", customers.len());
    context.unstash_all();
    State::Ready { customers }
}

(State::Loading, incoming) => {
    match context.stash(incoming) {
        Ok(()) => {}
        Err(Incoming::Message(Message::Lookup { reply_to, .. })) => {
            reply_to.reply(Err(LookupError::Busy));
        }
        Err(_) => unreachable!("only a lookup can be refused"),
    }
    State::Loading
}

The stash has the capacity of the mailbox, three in this example (see main below). A full stash neither drops the message nor panics: stash hands it back as its error, and the actor decides. Here it answers Busy, so the caller can try again. Akka's StashBuffer, the model for this API, throws when it is full.

Unstash when the output arrives

When Loaded arrives, the actor calls unstash_all and becomes Ready. unstash_all hands every stashed item back to the run loop, which receives them one receive each, in the order they were stashed. The Ready state answers them from the table like any later lookup:

tellus/examples/how_to/defer_messages.rs
(State::Ready { customers }, Incoming::Message(Message::Lookup { id, reply_to })) => {
    reply_to.reply(customers.get(&id).cloned().ok_or(LookupError::Unknown(id)));
    State::Ready { customers }
}

What to keep in mind

stash and unstash_all are requests. They take effect once the item at hand is settled: when receive or init has returned successfully, and for an event-sourced actor when recovered has returned or once the command's events are durable. They apply in the order they were made: stash(x) followed by unstash_all hands x back, unstash_all followed by stash(x) keeps x stashed. A failure before they take effect discards them.

Unstashed items come first. The run loop receives them ahead of a due timer and of the mailbox; only a stop by the parent comes before them. The run below cannot show the order against the mailbox, since the actor is idle while it waits; tests/stash.rs proves it. A drain cannot starve the mailbox, as Message delivery explains.

The stash has the mailbox's capacity. The outputs of piped futures and the replies to reply_to destinations pass a full mailbox but not a full stash. Message delivery has the accounting.

A restart hands the stash back. The new state receives every stashed item first, in order, after init, or after recovery and recovered for an event-sourced actor. Termination drops the stash with the mailbox, so a ReplyTo stashed inside a request resolves its ask as NoReply.

Terminated signals can be stashed. A stashed signal keeps its place and skips the stash's capacity. unwatch drops the stashed signals of the unwatched actor as it drops the queued ones, with one exception.

Testing. TestContext::stashed creates the context of a stashed actor, take_stashed returns what the actor has stashed, and take_unstashed what unstash_all handed back, in the order it would be received. See Unit test an actor.

Run it

tellus/examples/how_to/defer_messages.rs
#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let config =
        ActorConfig::default().with_mailbox_capacity(MailboxCapacity::Bounded(MAILBOX_CAPACITY));
    let system = ActorSystem::with_config(Directory, config);
    let directory = system.root();

    let (first, second, third, fourth) = tokio::join!(
        lookup(directory, 1),
        lookup(directory, 2),
        lookup(directory, 3),
        async {
            // Full until the directory has received one of the first three lookups!
            loop {
                match lookup(directory, 4).await {
                    Err(AskError::MailboxFull) => yield_now().await,
                    result => break result,
                }
            }
        },
    );
    for (id, customer) in [(1, first?), (2, second?), (3, third?), (4, fourth?)] {
        print_customer(id, customer);
    }

    print_customer(9, lookup(directory, 9).await?);

    system.stop();
    system
        .terminated()
        .await
        .context("awaiting actor system termination")
}

The mailbox is bounded to three, so the stash is too. tokio::join! sends all four lookups at once. The mailbox refuses the fourth with MailboxFull while the first three fill it. The fourth is retried until the directory has received one of them. The directory stashes the first three and finds the stash full on the fourth, while the table still loads. From a clone of the tellus repository:

cargo run --quiet -p tellus --example how_to_defer_messages
Loaded 3 customers
Customer 1: Alice
Customer 2: Bob
Customer 3: Carol
Customer 4: busy, try again later
Customer 9: unknown customer 9

Lookup 4 was answered at once, while the first three waited for the table. The directory answered those three in the order they were stashed; main prints every answer in id order, so the output shows the answers, not that order. Lookup 9 came after the table and was answered right away.