Actors on Dapr Docs

Actors overview

Mon, 01 Jan 0001 00:00:00 +0000

The actor pattern describes actors as the lowest-level “unit of computation”. In other words, you write your code in a self-contained unit (called an actor) that receives messages and processes them one at a time, without any kind of concurrency or threading.

While your code processes a message, it can send one or more messages to other actors, or create new actors. An underlying runtime manages how, when and where each actor runs, and also routes messages between actors.

Actor runtime features

Mon, 01 Jan 0001 00:00:00 +0000

Now that you’ve learned about the actor building block at a high level, let’s deep dive into the features and concepts included with actors in Dapr.

Actor lifetime

Dapr actors are virtual, meaning that their lifetime is not tied to their in-memory representation. As a result, they do not need to be explicitly created or destroyed. The Dapr actor runtime automatically activates an actor the first time it receives a request for that actor ID. If an actor is not used for a period of time, the Dapr actor runtime garbage-collects the in-memory object. It will also maintain knowledge of the actor’s existence should it need to be reactivated later.

Actor runtime configuration parameters

Mon, 01 Jan 0001 00:00:00 +0000

You can modify the default Dapr actor runtime behavior using the following configuration parameters.

Parameter	Description	Default
`entities`	The actor types supported by this host.	N/A
`actorIdleTimeout`	The timeout before deactivating an idle actor. Checks for timeouts occur every `actorScanInterval` interval.	60 minutes
`actorScanInterval`	The duration which specifies how often to scan for actors to deactivate idle actors. Actors that have been idle longer than actor_idle_timeout will be deactivated.	30 seconds
`drainOngoingCallTimeout`	The duration when in the process of draining rebalanced actors. This specifies the timeout for the current active actor method to finish. If there is no current actor method call, this is ignored.	60 seconds
`drainRebalancedActors`	If true, Dapr will wait for `drainOngoingCallTimeout` duration to allow a current actor call to complete before trying to deactivate an actor.	true
`reentrancy` (`ActorReentrancyConfig`)	Configure the reentrancy behavior for an actor. If not provided, reentrancy is disabled.	disabled, false
`entitiesConfig`	Configure each actor type individually with an array of configurations. Any entity specified in the individual entity configurations must also be specified in the top level `entities` field.	N/A

Examples

// In Startup.cs
public void ConfigureServices(IServiceCollection services)
{
 // Register actor runtime with DI
 services.AddActors(options =>
 {
 // Register actor types and configure actor settings
 options.Actors.RegisterActor<MyActor>();

 // Configure default settings
 options.ActorIdleTimeout = TimeSpan.FromMinutes(60);
 options.ActorScanInterval = TimeSpan.FromSeconds(30);
 options.DrainOngoingCallTimeout = TimeSpan.FromSeconds(60);
 options.DrainRebalancedActors = true;
 options.ReentrancyConfig = new() { Enabled = false };

 // Add a configuration for a specific actor type.
 // This actor type must have a matching value in the base level 'entities' field. If it does not, the configuration will be ignored.
 // If there is a matching entity, the values here will be used to overwrite any values specified in the root configuration.
 // In this example, `ReentrantActor` has reentrancy enabled; however, 'MyActor' will not have reentrancy enabled.
 options.Actors.RegisterActor<ReentrantActor>(typeOptions: new()
 {
 ReentrancyConfig = new()
 {
 Enabled = true,
 }
 });
 });

 // Register additional services for use with actors
 services.AddSingleton<BankService>();
}

See the .NET SDK documentation on registering actors.

Namespaced actors

Mon, 01 Jan 0001 00:00:00 +0000

Namespacing in Dapr provides isolation, and thus multi-tenancy. With actor namespacing, the same actor type can be deployed into different namespaces. You can call instances of these actors in the same namespace.

Note

Each namespaced actor deployment must use its own separate state store, especially if the same actor type is used across namespaces. In other words, no namespace information is written as part of the actor record, and hence separate state stores are required for each namespace. See Configuring actor state stores for namespacing section for examples.

Creating and configuring namespaces

You can use namespaces either in self-hosted mode or on Kubernetes.

Actors timers and reminders

Mon, 01 Jan 0001 00:00:00 +0000

Actors can schedule periodic work on themselves by registering either timers or reminders.

The functionality of timers and reminders is very similar. The main difference is that Dapr actor runtime is not retaining any information about timers after deactivation, while persisting the information about reminders using Dapr Scheduler.

This distinction allows users to trade off between light-weight but stateless timers vs. more resource-demanding but stateful reminders.

The scheduling configuration of timers and reminders is summarized below:

How-to: Interact with virtual actors using scripting

Mon, 01 Jan 0001 00:00:00 +0000

Learn how to use virtual actors by calling HTTP/gRPC endpoints.

Invoke the actor method

You can interact with Dapr to invoke the actor method by calling HTTP/gRPC endpoint.

POST/GET/PUT/DELETE http://localhost:3500/v1.0/actors/<actorType>/<actorId>/method/<method>

Provide data for the actor method in the request body. The response for the request, which is data from actor method call, is in the response body.

Refer to the Actors API spec for more details.

Note

Alternatively, you can use Dapr SDKs to use actors.

Save state with actors

You can interact with Dapr via HTTP/gRPC endpoints to save state reliably using the Dapr actor state management capabaility.

How-to: Enable and use actor reentrancy in Dapr

Mon, 01 Jan 0001 00:00:00 +0000

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. A second request wouldn’t be able to start until the first had completed. This means an actor cannot call itself, or have another actor call into it, even if it’s part of the same call chain.

Reentrancy solves this by allowing requests from the same chain, or context, to re-enter into an already locked actor. This proves useful in scenarios where: