How-to: Enable and use actor reentrancy in Dapr

Learn more about actor reentrancy

Actor reentrancy

A core tenet of the virtual actor pattern is the single-threaded nature of actor execution. Without reentrancy, the Dapr runtime locks on all actor requests, even those that are in the same call chain. A second request could not start until the first had completed. This means an actor cannot call itself, or have another actor call into it even if it is part of the same chain. Reentrancy solves this by allowing requests from the same chain, or context, to re-enter into an already locked actor. This is especially useful in scenarios where an actor wants to call a method on itself or when actors are used in workflows where other actors are used to perform work, and they then call back onto the coordinating actor. Examples of chains that reentrancy allows are shown below:

Actor A -> Actor A
ActorA -> Actor B -> Actor A

With reentrancy, there can be more complex actor calls without sacrificing the single-threaded behavior of virtual actors.

Diagram showing reentrancy for a coordinator workflow actor calling worker actors or an actor calling an method on itself

The maxStackDepth parameter sets a value that controls how many reentrant calls be made to the same actor. By default this is set to 32, which is more than sufficient in most cases.

Enable Actor Reentrancy with Actor Configuration

The actor that will be reentrant must provide configuration to use reentrancy. This is done by the actor’s endpoint for GET /dapr/config, similar to other actor configuration elements.

public class Startup
	public void ConfigureServices(IServiceCollection services)
		services.AddActors(options =>
		options.ReentrancyConfig = new Dapr.Actors.ActorReentrancyConfig()
			Enabled = true,
			MaxStackDepth = 32,

from fastapi import FastAPI
from dapr.ext.fastapi import DaprActor
from import ActorRuntimeConfig, ActorReentrancyConfig
from import ActorRuntime
from demo_actor import DemoActor

reentrancyConfig = ActorReentrancyConfig(enabled=True)
config = ActorRuntimeConfig(reentrancy=reentrancyConfig)
app = FastAPI(title=f'{DemoActor.__name__}Service')
actor = DaprActor(app)

async def startup_event():
	# Register DemoActor
	await actor.register_actor(DemoActor)

def do_something_reentrant():
	# invoke another actor here, reentrancy will be handled automatically

Here is a snippet of an actor written in Golang providing the reentrancy configuration via the HTTP API. Reentrancy has not yet been included into the Go SDK.

type daprConfig struct {
	Entities                []string                `json:"entities,omitempty"`
	ActorIdleTimeout        string                  `json:"actorIdleTimeout,omitempty"`
	ActorScanInterval       string                  `json:"actorScanInterval,omitempty"`
	DrainOngoingCallTimeout string                  `json:"drainOngoingCallTimeout,omitempty"`
	DrainRebalancedActors   bool                    `json:"drainRebalancedActors,omitempty"`
	Reentrancy              config.ReentrancyConfig `json:"reentrancy,omitempty"`

var daprConfigResponse = daprConfig{
	config.ReentrancyConfig{Enabled: true, MaxStackDepth: &maxStackDepth},

func configHandler(w http.ResponseWriter, r *http.Request) {
	w.Header().Set("Content-Type", "application/json")

Handling reentrant requests

The key to a reentrant request is the Dapr-Reentrancy-Id header. The value of this header is used to match requests to their call chain and allow them to bypass the actor’s lock.

The header is generated by the Dapr runtime for any actor request that has a reentrant config specified. Once it is generated, it is used to lock the actor and must be passed to all future requests. Below are the snippets of code from an actor handling this:

func reentrantCallHandler(w http.ResponseWriter, r *http.Request) {
     * Omitted.

	req, _ := http.NewRequest("PUT", url, bytes.NewReader(nextBody))

	reentrancyID := r.Header.Get("Dapr-Reentrancy-Id")
	req.Header.Add("Dapr-Reentrancy-Id", reentrancyID)

	client := http.Client{}
	resp, err := client.Do(req)

     * Omitted.

Watch this video on how to use actor reentrancy.