Reentrancy

Overview

Reentrancy is the ability of an actor to process new messages while it is waiting for a response from another actor. In the default, non-reentrant model, an actor handles one message at a time: if it sends a request and waits for a reply, its mailbox is effectively blocked until that reply arrives. With reentrancy enabled, the actor can keep processing other messages and handle the reply later via a continuation (callback), so the mailbox stays responsive.

The default: one message at a time

In the actor model, each actor has a mailbox and processes messages sequentially. That gives you a simple mental model and avoids races on the actor’s state. As long as the handler runs to completion without waiting on external replies, this works well. The problem appears when an actor needs to ask another actor for something: if it blocks until the response comes back, it cannot process any other message in the meantime. The actor (and its mailbox) is stuck until the response arrives or times out.

What reentrancy changes

When reentrancy is enabled, the actor can issue an async request to another actor and register a continuation. The runtime does not block the actor’s message loop: as soon as the request is sent, the actor can move on to the next message. When the response (or error) arrives, the runtime invokes the continuation with that result. So the actor can have multiple requests in flight and still process new messages; responses are handled by their continuations, not by blocking in the middle of a handler.

In other words

With reentrancy, an actor can:

• Send async requests to other actors (Request or RequestName)

• Continue processing new messages while waiting for responses

• Handle responses via continuations (callbacks) when they arrive

• Avoid blocking the mailbox on request–response round-trips

Without reentrancy, the actor processes messages strictly one at a time; if it waits for a reply, nothing else is processed until that reply (or timeout). With reentrancy, multiple pending requests can be outstanding and the actor remains responsive to new work.

Trade-off

Reentrancy trades strict single-threaded-by-message safety for better concurrency and responsiveness. While a continuation is running, the actor’s state may have changed because other messages were processed in between. You must design your continuations with that in mind (e.g. avoid assuming state that might be stale, or use request correlation ids to match responses to the right logical operation). When used carefully, reentrancy lets you build responsive actors that coordinate with others without blocking the mailbox.

Importance

Traditional actor model (no reentrancy):

Process Msg1 → Send request → BLOCK → Wait → Response → Process Msg2
                                ↑
                         Mailbox blocked!

With reentrancy:

Process Msg1 → Send async request → Process Msg2 → Process Msg3
                                          ↓
                                    Response arrives
                                          ↓
                                  Continuation executes

Benefits:

• Higher throughput: Don't block on async operations

• Better resource utilization: Process messages while waiting

• Responsive actors: Handle new messages immediately

• Concurrent workflows: Multiple requests in flight

Modes

GoAkt provides three reentrancy modes:

Off (Default)

No reentrancy support. Async requests not allowed.

// Default behavior
pid, _ := actorSystem.Spawn(ctx, "actor", &MyActor{})
// Reentrancy is OFF by default

AllowAll

Allow concurrent request handling. New messages processed while requests pending.

pid, _ := actorSystem.Spawn(ctx, "actor", &MyActor{},
    actor.WithReentrancy(reentrancy.New(reentrancy.WithMode(reentrancy.AllowAll))))

Behavior:

• Multiple async requests can be in flight

• New messages processed immediately

• Continuations run when responses arrive

• No ordering guarantees for completion

Use when:

• Order of completion doesn't matter

• Higher throughput needed

• Independent requests

• Stateless operations

StashNonReentrant

pid, _ := actorSystem.Spawn(ctx, "actor", &MyActor{},
    actor.WithReentrancy(reentrancy.New(reentrancy.WithMode(reentrancy.StashNonReentrant))))

Behavior:

• One request at a time

• New messages stashed until request completes

• Continuations run when response arrives

• Sequential processing maintained

Use when:

• Order matters

• Stateful operations

• Need sequential consistency

• Avoid race conditions

Get Started

Reentrancy is enabled for actor during their creation using the WithReentrancy SpawnOption.

Once the reentrancy option is properly configured, the feature can be used through the following methods available on the ReceiveContext:

• Request: A non-blocking counterpart of Ask. This method can only be used locally or within a single-node actor system.

• RequestName: Similar to Request, but location-transparent.

Example

package main

import (
	"context"
	"fmt"
	"os"
	"os/signal"
	"syscall"
	"time"

	"google.golang.org/protobuf/proto"

	"github.com/tochemey/goakt/v3/actor"
	"github.com/tochemey/goakt/v3/goaktpb"
	"github.com/tochemey/goakt/v3/log"
	"github.com/tochemey/goakt/v3/reentrancy"
	"github.com/tochemey/goakt/v3/test/data/testpb"
)

const (
	actorAName     = "actor-a"
	actorBName     = "actor-b"
	requestTimeout = 2 * time.Second
)

func main() {
	ctx := context.Background()

	system, err := actor.NewActorSystem("reentrancy-demo", 
					actor.WithLogger(log.DiscardLogger))
	if err != nil {
		fmt.Printf("Error creating actor system: %v\n", err)
		os.Exit(1)
	}

	if err := system.Start(ctx); err != nil {
		fmt.Printf("Error starting actor system: %v\n", err)
		os.Exit(1)
	}

	actorA, err := system.Spawn(ctx, actorAName, &ActorA{targetName: actorBName}, 
					actor.WithReentrancy(
					reentrancy.New(reentrancy.WithMode(reentrancy.AllowAll), 
					reentrancy.WithMaxInFlight(4))))
	if err != nil {
		fmt.Printf("Error spawning %s: %v\n", actorAName, err)
		os.Exit(1)
	}

	_, err = system.Spawn(ctx, actorBName, &ActorB{actorA: actorA})
	if err != nil {
		fmt.Printf("Error spawning %s: %v\n", actorBName, err)
		os.Exit(1)
	}

	doneCh := make(chan struct{}, 1)
	_, err = system.Spawn(ctx, "client", &Client{target: actorA, doneCh: doneCh})
	if err != nil {
		fmt.Printf("Error spawning client: %v\n", err)
		os.Exit(1)
	}

	select {
	case <-doneCh:
		fmt.Println("Reentrancy cycle completed.")
	case <-time.After(3 * time.Second):
		fmt.Println("Timeout waiting for reentrancy cycle.")
		os.Exit(1)
	}

	fmt.Println("Press Ctrl+C to stop the actor system.")
	interruptSignal := make(chan os.Signal, 1)
	signal.Notify(interruptSignal, os.Interrupt, syscall.SIGINT, syscall.SIGTERM)
	<-interruptSignal

	if err := system.Stop(ctx); err != nil {
		fmt.Printf("Error stopping actor system: %v\n", err)
		os.Exit(1)
	}
}

type Client struct {
	target *actor.PID
	doneCh chan struct{}
}

var _ actor.Actor = (*Client)(nil)

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

func (c *Client) Receive(ctx *actor.ReceiveContext) {
	switch msg := ctx.Message().(type) {
	case *goaktpb.PostStart:
		ctx.Tell(c.target, new(testpb.TestPing))
	case *testpb.TestCount:
		fmt.Printf("Client received count=%d\n", msg.GetValue())
		select {
		case c.doneCh <- struct{}{}:
		default:
		}
	default:
		ctx.Unhandled()
	}
}

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

type ActorA struct {
	targetName string
}

var _ actor.Actor = (*ActorA)(nil)

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

func (a *ActorA) Receive(ctx *actor.ReceiveContext) {
	switch ctx.Message().(type) {
	case *testpb.TestPing:
		sender := ctx.Sender()
		self := ctx.Self()
		call := ctx.RequestName(a.targetName, new(testpb.TestPing), 
		actor.WithRequestTimeout(requestTimeout))
		// RequestName records the error on ctx.Err and returns nil on failure.
		if call == nil {
			fmt.Println("ActorA request failed")
			return
		}
		call.Then(func(resp proto.Message, err error) {
			// Then runs without a ReceiveContext; log or message yourself to record errors.
			if err != nil {
				fmt.Printf("ActorA request error: %v\n", err)
				return
			}
			if sender == nil {
				fmt.Println("ActorA missing sender for reply")
				return
			}
			if err := self.Tell(context.Background(), sender, resp); err != nil {
				fmt.Printf("ActorA reply failed: %v\n", err)
			}
		})
	case *testpb.TestGetCount:
		ctx.Response(&testpb.TestCount{Value: 42})
	default:
		ctx.Unhandled()
	}
}

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

type ActorB struct {
	actorA *actor.PID
}

var _ actor.Actor = (*ActorB)(nil)

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

func (b *ActorB) Receive(ctx *actor.ReceiveContext) {
	switch ctx.Message().(type) {
	case *testpb.TestPing:
		reply := ctx.Ask(b.actorA, new(testpb.TestGetCount), requestTimeout)
		if reply == nil {
			fmt.Println("ActorB ask failed")
			return
		}
		ctx.Response(reply)
	default:
		ctx.Unhandled()
	}
}

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

Request Options

Timeout

This help to set timeout for individual requests:

import "github.com/tochemey/goakt/v3/errors"

request := ctx.Request(pid, &Query{},
    actor.WithRequestTimeout(5*time.Second))

request.Then(func(response proto.Message, err error) {
    if errors.Is(err, errors.ErrRequestTimeout) {
        ctx.Logger().Warn("Request timed out")
        return
    }
    // Handle response
})

Reentrancy Mode

This helps override reentrancy mode for specific requests:

// Actor configured with AllowAll
// But this specific request should stash
request := ctx.Request(pid, &CriticalQuery{},
    actor.WithReentrancyMode(reentrancy.StashNonReentrant))

request.Then(func(response proto.Message, err error) {
    // Process response
})

Cancellation

Inflight reentrant requests can be cancelled:

func (a *MyActor) Receive(ctx *actor.ReceiveContext) {
    switch msg := ctx.Message().(type) {
    case *StartQuery:
        // send a query to the db actor using its pid
        request := ctx.Request(a.pid, &Query{})

        // Store request for cancellation
        a.pendingRequest = request

        request.Then(func(response proto.Message, err error) {
            if errors.Is(err, context.Canceled) {
                ctx.Logger().Info("Request was cancelled")
                return
            }
            // Handle response
        })

    case *CancelQuery:
        if a.pendingRequest != nil {
            a.pendingRequest.Cancel()
            a.pendingRequest = nil
        }
    }
}

Best Practices

1. Handle errors in continuations

2. Set request timeouts

3. Cancel requests when no longer needed

4. Use appropriate reentrancy mode

5. Keep continuations short

6. Don't block in continuations

7. Don't forget error handling

8. Don't use without timeouts

9. Don't access actor state unsafely

10. Don't leak request handles

Common Pitfalls

Reentrancy often causes bugs that are:

• Hard to reproduce

• Sensitive to timing

• Mistaken for “distributed system issues”

Typical mistakes include:

• Assuming state is unchanged after an await

• Updating shared state in multiple message handlers

• Performing multi-step workflows without protection

These bugs are logical, not technical — the system is doing exactly what it was told.