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

Mode	Behavior
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. Preserves strict ordering at the cost of latency.

Enabling reentrancy

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

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

Option	Purpose
`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:

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

Method	Purpose
`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:

Method	Purpose
`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

Option	Purpose
`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.

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

Error	When
`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`.

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, stashed messages are unstashed and processed in order.

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.
Strict ordering when you must not interleave user messages with async responses: 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.
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.

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.")
    }
}

Core Concepts

Messaging

Fault Tolerance

Scaling & Placement

Testing

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