Actor runtime features

Learn more about the features and concepts of Actors in Dapr

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.

Invocation of actor methods, timers, and reminders reset the actor idle time. For example, a reminder firing keeps the actor active.

  • Actor reminders fire whether an actor is active or inactive. If fired for an inactive actor, it activates the actor first.
  • Actor timers firing reset the idle time; however, timers only fire while the actor is active.

The idle timeout and scan interval Dapr runtime uses to see if an actor can be garbage-collected is configurable. This information can be passed when Dapr runtime calls into the actor service to get supported actor types.

This virtual actor lifetime abstraction carries some caveats as a result of the virtual actor model, and in fact the Dapr Actors implementation deviates at times from this model.

An actor is automatically activated (causing an actor object to be constructed) the first time a message is sent to its actor ID. After some period of time, the actor object is garbage collected. In the future, using the actor ID again, causes a new actor object to be constructed. An actor’s state outlives the object’s lifetime as state is stored in configured state provider for Dapr runtime.

Distribution and failover

To provide scalability and reliability, actors instances are distributed throughout the cluster and Dapr automatically migrates them from failed nodes to healthy ones as required.

Actors are distributed across the instances of the actor service, and those instances are distributed across the nodes in a cluster. Each service instance contains a set of actors for a given actor type.

Actor placement service

The Dapr actor runtime manages distribution scheme and key range settings for you via the actor Placement service. When a new instance of a service is created:

  1. The sidecar makes a call to the actor service to retrieve registered actor types and configuration settings.
  2. The corresponding Dapr runtime registers the actor types it can create.
  3. The Placement service calculates the partitioning across all the instances for a given actor type.

This partition data table for each actor type is updated and stored in each Dapr instance running in the environment and can change dynamically as new instances of actor services are created and destroyed.

Three service instances registering their actor types with the Dapr Placement serviceOn the left, three dashed boundaries stacked, captioned Instance 1, Instance 2 and Instance 3. Each holds a green hexagon named Service code over the actor type it hosts - MyActor1, MyActor1 and MyActor2 - joined by a line with a head at each end to a hexagon carrying the Dapr logo, and beside that a small table of actor types and partitions. Each sidecar has an arrow to a filled panel in the middle named Dapr Placement service, which holds the same table larger. A line runs back from the panel under the stack and up into all three sidecars. On the right, four steps: the sidecar asks its service which actor types it has; the runtime registers those types with Placement; Placement calculates the partitioning across instances; the table is broadcast, and cached in every instance.Instance 1Service codeMyActor1Actor typePartitionsMyActor1Dapr instancesMyActor2Dapr instancesInstance 2Service codeMyActor1Actor typePartitionsMyActor1Dapr instancesMyActor2Dapr instancesInstance 3Service codeMyActor2Actor typePartitionsMyActor1Dapr instancesMyActor2Dapr instancesDapr Placement serviceActor typePartitionsMyActor1Dapr instancesMyActor2Dapr instances12341The sidecar asks its servicewhich actor types it has2The runtime registers thosetypes with Placement3Placement calculates thepartitioning across instances4The table is broadcast, andcached in every instance

When a client calls an actor with a particular id (for example, actor id 123), the Dapr instance for the client hashes the actor type and id, and uses the information to call onto the corresponding Dapr instance that can serve the requests for that particular actor id. As a result, the same partition (or service instance) is always called for any given actor id. This is shown in the diagram below.

A call for actor ID 123 routed to the service instance that holds itOn the left, three dashed boundaries stacked, captioned Instance 1, Instance 2 and Instance 3, each holding a green hexagon named Service code over the actor type it hosts, a hexagon carrying the Dapr logo, and a small table of actor types and partitions. Instance 2 shows Actor ID 123 created. In the middle, a filled panel named Dapr Placement service holding the same table larger, with a dashed line to a fourth boundary on the right captioned Caller, whose service reads Call Actor ID 123. A run leaves the caller, passes below the stack and arrives at Instance 2. Two steps below: the caller’s sidecar hashes the actor type and ID 123 and looks it up in its cache; the call goes straight to the instance that table names.partition tableInstance 1Service codeMyActor1Actor typePartitionsMyActor1Dapr instancesMyActor2Dapr instancesInstance 2Service codeMyActor1Actor typePartitionsMyActor1Dapr instancesMyActor2Dapr instancesInstance 3Service codeMyActor2Actor typePartitionsMyActor1Dapr instancesMyActor2Dapr instancesDapr Placement serviceActor typePartitionsMyActor1Dapr instancesMyActor2Dapr instancesCallerService codeCall ID 123Actor typePartitionsMyActor1Dapr instancesMyActor2Dapr instancesActor ID 123 created1231Client code calls actor ID 123 for actor type MyActor12The Dapr instance hashes the request for ID 123 to aDapr instance (partition) and looks this up in the local cache3Client call for actor ID 123 sent to the Dapr instanceto create the actor

This simplifies some choices, but also carries some consideration:

  • By default, actors are randomly placed into pods resulting in uniform distribution.
  • Because actors are randomly placed, it should be expected that actor operations always require network communication, including serialization and deserialization of method call data, incurring latency and overhead.

Actor communication

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

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

You can provide any data for the actor method in the request body, and the response for the request would be in the response body which is the data from actor call.

Another, and perhaps more convenient, way of interacting with actors is via SDKs. Dapr currently supports actors SDKs in .NET, Java, and Python.

Refer to Dapr Actor Features for more details.

Concurrency

The Dapr actor runtime provides a simple turn-based access model for accessing actor methods. This means that no more than one thread can be active inside an actor object’s code at any time. Turn-based access greatly simplifies concurrent systems as there is no need for synchronization mechanisms for data access. It also means systems must be designed with special considerations for the single-threaded access nature of each actor instance.

A single actor instance cannot process more than one request at a time. An actor instance can cause a throughput bottleneck if it is expected to handle concurrent requests.

Actors can deadlock on each other if there is a circular request between two actors while an external request is made to one of the actors simultaneously. The Dapr actor runtime automatically times out on actor calls and throw an exception to the caller to interrupt possible deadlock situations.

One actor serving many clients is a bottleneck; one actor per client, or one client over many actors, is notThree dashed panels side by side. The first, captioned Many clients, one actor, shows four client chips all pointing at a single gold disc named Actor, and is marked with a red cross. The second, captioned Many clients, many actors, pairs each client with its own actor and is marked with a navy tick. The third, captioned One client, many actors, has a single client pointing at four actors and is also marked with a navy tick. Three dots in each panel say the rows go on.Many clients, one actorMany clients, many actorsOne client, many actorsClientClientClientClientActorClientClientClientClientActorActorActorActorClientActorActorActorActor

Reentrancy

To allow actors to “re-enter” and invoke methods on themselves, see Actor Reentrancy.

Turn-based access

A turn consists of the complete execution of an actor method in response to a request from other actors or clients, or the complete execution of a timer/reminder callback. Even though these methods and callbacks are asynchronous, the Dapr actor runtime does not interleave them. A turn must be fully finished before a new turn is allowed. In other words, an actor method or timer/reminder callback that is currently executing must be fully finished before a new call to a method or callback is allowed. A method or callback is considered to have finished if the execution has returned from the method or callback and the task returned by the method or callback has finished. It is worth emphasizing that turn-based concurrency is respected even across different methods, timers, and callbacks.

The Dapr actor runtime enforces turn-based concurrency by acquiring a per-actor lock at the beginning of a turn and releasing the lock at the end of the turn. Thus, turn-based concurrency is enforced on a per-actor basis and not across actors. Actor methods and timer/reminder callbacks can execute simultaneously on behalf of different actors.

The following example illustrates the above concepts. Consider an actor type that implements two asynchronous methods (say, Method1 and Method2), a timer, and a reminder. The diagram below shows an example of a timeline for the execution of these methods and callbacks on behalf of two actors (ActorId1 and ActorId2) that belong to this actor type.

A timeline of six requests against two actors, showing each actor’s lock held by one turn at a timeTime runs down the page, marked by an arrow on the left. Six vertical lines stand side by side, headed ActorId1 Method1, ActorId1 Method2, ActorId1 Timer, ActorId2 Method1 for client request xyz789, ActorId2 Method1 for client request abc123, and ActorId2 Reminder. On each line a run of six dots is drawn over a tinted band: Lock acquired, Entered the method or callback, Created Task, the method exited and the task completed, and Lock released. The first column of each actor takes the lock on arrival; the other two show the request arriving early and waiting for the lock asynchronously. The three ActorId1 bands never overlap one another and neither do the three ActorId2 bands, but the two actors’ bands run at the same times - a lock is per actor, not across actors.TimeActorId1Method1Request arrived, lockacquired without waitEntered Method1Created TaskExited Method1Task completedLock releasedActorId1Method2Request arrived,waiting for lockasynchronouslyLock acquiredEntered Method2Created TaskExited Method2Task completedLock releasedActorId1TimerRequest arrived,waiting for lockasynchronouslyLock acquiredEntered callbackCreated TaskTask completedExited callbackLock releasedActorId2Method1(client request ‘xyz789’)Request arrived, lockacquired without waitEntered Method1Created TaskExited Method1Task completedLock releasedActorId2Method1(client request ‘abc123’)Request arrived,waiting for lockasynchronouslyLock acquiredEntered Method1Created TaskExited Method1Task completedLock releasedActorId2ReminderRequest arrived,waiting for lockasynchronouslyLock acquiredEntered callbackCreated TaskTask completedExited callbackLock released

Next steps

Timers and reminders >>