Reentrancy

Concept

By default, an actor processes messages strictly one at a time. Reentrancy allows an actor to process other messages while waiting for an async response from Request or RequestName. Request and RequestName are the non-blocking counterparts of Ask and SendSync. They return immediately with a RequestCall handle instead of blocking until a reply arrives. The reply is delivered back through the actor’s mailbox, preserving single-threaded processing.

Modes

Off: Strict sequential; Request/RequestName disabled. Use Ask/SendSync for sync calls.
AllowAll: All incoming messages can be processed while awaiting a response. Maximizes throughput.
StashNonReentrant: User messages are stashed while any stash-mode request is in flight; only async responses and system messages (e.g. PoisonPill, HealthCheckRequest) are processed. No user message is handled while the actor waits, at the cost of latency.

Enabling reentrancy

Reentrancy is opt-in. Pass WithReentrancy when spawning the actor:

Enabling reentrancy

import "github.com/tochemey/goakt/v4/reentrancy"

cfg := reentrancy.New(
    reentrancy.WithMode(reentrancy.AllowAll),
    reentrancy.WithMaxInFlight(10),  // optional: cap concurrent requests
)
pid, err := system.Spawn(ctx, "my-actor", actor, actor.WithReentrancy(cfg))

WithMode: Set reentrancy mode: Off, AllowAll, or StashNonReentrant.
WithMaxInFlight: Cap the number of outstanding async requests. When reached, Request/RequestName return ErrReentrancyInFlightLimit. Use n <= 0 for no limit.

Without a reentrancy policy, calls to Request, RequestName, or RequestGrain fail with ErrReentrancyDisabled.

Runtime toggle

An actor spawned without reentrancy can enable it from inside a handler when the capability is only needed for a particular case, and turn it off again afterward:

Runtime toggle

func (a *Migrator) Receive(ctx *actor.ReceiveContext) {
    switch ctx.Message().(type) {
    case *StartMigration:
        cfg := reentrancy.New(reentrancy.WithMode(reentrancy.AllowAll))
        if err := ctx.EnableReentrancy(cfg); err != nil {
            ctx.Err(err)
            return
        }
        // Request/RequestName/RequestGrain now work, from this message on
    case *MigrationDone:
        ctx.DisableReentrancy()
    }
}

EnableReentrancy installs the policy or retunes an existing one (mode, MaxInFlight) and takes effect for requests issued from that point on. DisableReentrancy flips the default mode back to Off: requests already in flight complete with the mode they were admitted with, stashed messages are released once the last blocking request finishes, and new requests fail with ErrReentrancyDisabled. After a runtime disable, a per-call WithReentrancyMode override still admits an individual request. Both methods also exist on GrainContext; see Grain Reentrancy.

Request, RequestName, and RequestGrain

ctx.Request: Send an async request to a PID. Returns a RequestCall or nil on failure.
ctx.RequestName: Send an async request to an actor by name (local or remote). Returns a RequestCall or nil.
ctx.RequestGrain: Send an async request to a grain, which activates on demand like any other grain send. Returns a RequestCall or nil.

Requests are location transparent: when the requester and the target sit on different nodes, the request and its reply travel over remoting, so cross-node payloads must be protobuf messages, like every other remote send. On failure to initiate the request, Err is set on the context and the returned call is nil. Check ctx.Err() or use ctx.getError() in tests.

RequestCall

The returned RequestCall lets you:

Then: Register a continuation func invoked when the request completes (success, error, timeout, or cancel). Only the first call is honored. If the request already completed, the callback runs immediately in the caller’s goroutine.
Cancel: Request cancellation. Best-effort; the request may still complete. Idempotent. Returns nil if already completed or cancel requested.

Continuations registered with Then run on the actor’s mailbox thread when the request completes, preserving single-threaded access to actor state. Call Then from within Receive to ensure correct execution.

Per-call options

WithReentrancyMode: Override the actor-level mode for this request only. Cannot enable if actor has reentrancy off.
WithRequestTimeout: Set a per-request timeout. On expiry, the request completes with ErrRequestTimeout. <= 0 disables.

Per-call options

call := ctx.Request(target, msg,
    actor.WithReentrancyMode(reentrancy.StashNonReentrant),
    actor.WithRequestTimeout(5*time.Second),
)
if call != nil {
    call.Then(func(resp any, err error) {
        if err != nil {
            // handle timeout, cancel, or remote error
            return
        }
        // use resp
    })
}

Errors

ErrReentrancyDisabled: The actor has no reentrancy policy (neither WithReentrancy at spawn nor a later EnableReentrancy), or the effective mode is Off.
ErrReentrancyInFlightLimit: MaxInFlight cap reached; no new async requests until some complete.
ErrRequestTimeout: Request timed out (via WithRequestTimeout).
ErrRequestCanceled: Request was canceled via Cancel, or by the actor stopping or restarting. In that case the continuation does not run: the actor abandons its in-flight requests as it abandons its mailbox, and a caller waiting on a deferred reply times out, as for any ask to an actor that stops before answering.

StashNonReentrant and stashing

In StashNonReentrant mode, user messages are automatically stashed while any stash-mode request is in flight. A stash buffer is created on demand; you do not need WithStashing() for reentrancy-driven stashing. When the last blocking request completes, the stashed messages are appended to the mailbox, oldest first. Messages that arrived after the response but before the actor handled it are already in the mailbox, so they run before the stashed ones. A restart cancels the request in flight and replays the stashed messages to the new incarnation, in order, after PostStart, as it keeps every queued message. Messages the actor stashed on its own with WithStashing, with no request in flight, are not replayed: they stay stashed for the new incarnation to unstash. A stop abandons the stash with the mailbox.

When to use

Actors that make async requests and need to stay responsive (e.g. fan-out, long I/O via PipeTo).
Avoiding deadlock in call cycles (A -> B -> A). Use AllowAll so A can process B’s reply while waiting.
No interleaving when user messages must not run while a request is in flight: use StashNonReentrant.

Production notes

Prefer AllowAll for throughput and to avoid deadlocks in call cycles.
Use StashNonReentrant only when strict message ordering is required. Pair it with:
- A finite MaxInFlight limit to bound memory.
- Per-request timeouts (WithRequestTimeout) to avoid unbounded stashing if dependencies stall.
AllowAll can introduce state races if your logic assumes strict ordering between request and response.
Passivation is not held for an in-flight request: an actor waiting on a reply is idle to its passivation strategy. Set the idle timeout above the request timeout, or the actor can be passivated before the reply arrives.
Mixed-version clusters may decode unknown modes as Off, disabling async requests.

Example

Reentrancy enables safe request/response cycles without deadlock. Flow: Client → ActorA → ActorB → ActorA → Client. ActorA uses RequestName (non-blocking); ActorB uses Ask (blocking). Without reentrancy, ActorA would block and the cycle would deadlock.

Example

package main

import (
    "context"
    "fmt"
    "time"

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

// Message types for the reentrancy cycle.
type Ping struct{}
type GetCount struct{}
type Count struct{ Value int } // Expected response: Value 42

// Client starts the cycle on PostStart and signals doneCh when it receives Count.
type Client struct {
    target *actor.PID
    doneCh chan struct{}
}

func (c *Client) PreStart(ctx *actor.Context) error { return nil }
func (c *Client) PostStop(ctx *actor.Context) error  { return nil }

func (c *Client) Receive(ctx *actor.ReceiveContext) {
    switch msg := ctx.Message().(type) {
    case *actor.PostStart:
        ctx.Tell(c.target, &Ping{}) // 1. Kick off the cycle
    case *Count:
        fmt.Println("Count:", msg.Value) // 6. Expected: Count: 42
        select {
        case c.doneCh <- struct{}{}:
        default:
        }
    default:
        ctx.Unhandled()
    }
}

// ActorA uses RequestName (non-blocking) so it can process ActorB's Ask while waiting.
type ActorA struct{ targetName string }

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

func (a *ActorA) Receive(ctx *actor.ReceiveContext) {
    switch ctx.Message().(type) {
    case *Ping:
        sender := ctx.Sender()
        self := ctx.Self()
        // 2. Non-blocking request to ActorB; returns immediately
        call := ctx.RequestName(a.targetName, &Ping{}, actor.WithRequestTimeout(2*time.Second))
        if call == nil { return }
        call.Then(func(resp any, err error) {
            if err != nil || sender == nil { return }
            // 5. Forward response back to Client
            _ = self.Tell(context.Background(), sender, resp)
        })
    case *GetCount:
        // 4. ActorB's Ask arrives while we wait; reentrancy allows us to handle it
        ctx.Response(&Count{Value: 42})
    default:
        ctx.Unhandled()
    }
}

// ActorB uses Ask (blocking) to call back into ActorA.
type ActorB struct{ actorA *actor.PID }

func (b *ActorB) PreStart(ctx *actor.Context) error { return nil }
func (b *ActorB) PostStop(ctx *actor.Context) error { return nil }

func (b *ActorB) Receive(ctx *actor.ReceiveContext) {
    switch ctx.Message().(type) {
    case *Ping:
        // 3. Ask ActorA for count; ActorA must be reentrant to respond
        resp := ctx.Ask(b.actorA, &GetCount{}, 2*time.Second)
        ctx.Response(resp)
    default:
        ctx.Unhandled()
    }
}

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

    doneCh := make(chan struct{}, 1)
    actorA, _ := system.Spawn(ctx, "actor-a", &ActorA{targetName: "actor-b"},
        actor.WithReentrancy(reentrancy.New(
            reentrancy.WithMode(reentrancy.AllowAll),
            reentrancy.WithMaxInFlight(4),
        )))
    _, _ = system.Spawn(ctx, "actor-b", &ActorB{actorA: actorA})
    _, _ = system.Spawn(ctx, "client", &Client{target: actorA, doneCh: doneCh})

    // Expected: "Count: 42" then "Reentrancy cycle completed."
    select {
    case <-doneCh:
        fmt.Println("Reentrancy cycle completed.")
    case <-time.After(3 * time.Second):
        fmt.Println("Timeout.")
    }
}

Quickstart

Actors

Grains

AI Agents

Remoting

Clustering

Advanced

Architecture

Concept

Modes

Enabling reentrancy

Runtime toggle

Request, RequestName, and RequestGrain

RequestCall

Per-call options

Errors

StashNonReentrant and stashing

When to use

Production notes

Example

See also

​Concept

​Modes

​Enabling reentrancy

​Runtime toggle

​Request, RequestName, and RequestGrain

​RequestCall

​Per-call options

​Errors

​StashNonReentrant and stashing

​When to use

​Production notes

​Example

​See also

Concept

Modes

Enabling reentrancy

Runtime toggle

Request, RequestName, and RequestGrain

RequestCall

Per-call options

Errors

StashNonReentrant and stashing

When to use

Production notes

Example

See also