mirror of https://github.com/dapr/docs.git
Merge branch 'dapr:v1.10' into update-js-sdk
This commit is contained in:
Wralith
GitHub
commit
499da5f746
|
|
@ -2,31 +2,37 @@
|
|||
type: docs
|
||||
title: "How-to: Enable and use actor reentrancy in Dapr"
|
||||
linkTitle: "How-To: Actor reentrancy"
|
||||
weight: 30
|
||||
weight: 70
|
||||
description: 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:
|
||||
A core tenet of the [virtual actor pattern](https://www.microsoft.com/research/project/orleans-virtual-actors/) 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:
|
||||
- An actor wants to call a method on itself
|
||||
- Actors are used in workflows to perform work, 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.
|
||||
With reentrancy, you can perform more complex actor calls, without sacrificing the single-threaded behavior of virtual actors.
|
||||
|
||||
<img src="/images/actor-reentrancy.png" width=1000 height=500 alt="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.
|
||||
The `maxStackDepth` parameter sets a value that controls how many reentrant calls can 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
|
||||
## Configure the actor runtime to enable reentrancy
|
||||
|
||||
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.
|
||||
The reentrant actor must provide the appropriate configuration. This is done by the actor's endpoint for `GET /dapr/config`, similar to other actor configuration elements.
|
||||
|
||||
{{< tabs Dotnet Python Go >}}
|
||||
{{< tabs ".NET" JavaScript Python Java Go >}}
|
||||
|
||||
{{% codetab %}}
|
||||
<!--dotnet-->
|
||||
|
||||
```csharp
|
||||
public class Startup
|
||||
|
|
@ -50,6 +56,27 @@ public class Startup
|
|||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
<!--javascript-->
|
||||
|
||||
```js
|
||||
import { CommunicationProtocolEnum, DaprClient, DaprServer } from "@dapr/dapr";
|
||||
|
||||
// Configure the actor runtime with the DaprClientOptions.
|
||||
const clientOptions = {
|
||||
actor: {
|
||||
reentrancy: {
|
||||
enabled: true,
|
||||
maxStackDepth: 32,
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
<!--python-->
|
||||
|
||||
```python
|
||||
from fastapi import FastAPI
|
||||
from dapr.ext.fastapi import DaprActor
|
||||
|
|
@ -75,6 +102,16 @@ def do_something_reentrant():
|
|||
```
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
<!--java-->
|
||||
|
||||
```java
|
||||
|
||||
```
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
|
||||
{{% codetab %}}
|
||||
|
||||
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.
|
||||
|
|
@ -105,10 +142,11 @@ func configHandler(w http.ResponseWriter, r *http.Request) {
|
|||
}
|
||||
```
|
||||
|
||||
### Handling reentrant requests
|
||||
### Handle 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:
|
||||
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 is an example of an actor handling a reentrant request:
|
||||
|
||||
```go
|
||||
func reentrantCallHandler(w http.ResponseWriter, r *http.Request) {
|
||||
|
|
@ -134,7 +172,19 @@ func reentrantCallHandler(w http.ResponseWriter, r *http.Request) {
|
|||
|
||||
{{< /tabs >}}
|
||||
|
||||
## Demo
|
||||
|
||||
Watch this [video](https://www.youtube.com/watch?v=QADHQ5v-gww&list=PLcip_LgkYwzuF-OV6zKRADoiBvUvGhkao&t=674s) on how to use actor reentrancy.
|
||||
|
||||
<div class="embed-responsive embed-responsive-16by9">
|
||||
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/QADHQ5v-gww?start=674" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
|
||||
</div>
|
||||
|
||||
## Next steps
|
||||
|
||||
{{< button text="Actors in the Dapr SDKs" page="developing-applications/sdks/#sdk-languages" >}}
|
||||
|
||||
## Related links
|
||||
|
||||
- [Actors API reference]({{< ref actors_api.md >}})
|
||||
- [Actors overview]({{< ref actors-overview.md >}})
|
||||
|
|
@ -0,0 +1,102 @@
|
|||
---
|
||||
type: docs
|
||||
title: "Actor runtime features"
|
||||
linkTitle: "Runtime features"
|
||||
weight: 20
|
||||
description: "Learn more about the features and concepts of Actors in Dapr"
|
||||
aliases:
|
||||
- "/developing-applications/building-blocks/actors/actors-background"
|
||||
---
|
||||
|
||||
Now that you've learned about the [actor building block]({{< ref "actors-overview.md" >}}) 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 and reminders reset the idle time, e.g. reminder firing will keep the actor active. Actor reminders fire whether an actor is active or inactive, if fired for inactive actor, it will activate the actor first. Actor timers do not reset the idle time, so timer firing will not keep the actor active. 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 instance 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.
|
||||
1. The corresponding Dapr runtime registers the actor types it can create.
|
||||
1. 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.
|
||||
|
||||
<img src="/images/actors_background_placement_service_registration.png" width=600>
|
||||
|
||||
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.
|
||||
|
||||
<img src="/images/actors_background_id_hashing_calling.png" width=600>
|
||||
|
||||
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.
|
||||
|
||||
{{% alert title="Note" color="primary" %}}
|
||||
Note: The Dapr actor Placement service is only used for actor placement and therefore is not needed if your services are not using Dapr actors. The Placement service can run in all [hosting environments]({{< ref hosting >}}), including self-hosted and Kubernetes.
|
||||
{{% /alert %}}
|
||||
|
||||
## Actor communication
|
||||
|
||||
You can interact with Dapr to invoke the actor method by calling HTTP/gRPC endpoint.
|
||||
|
||||
```bash
|
||||
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]({{< ref "dotnet-actors" >}}), [Java]({{< ref "java#actors" >}}), and [Python]({{< ref "python-actor" >}}).
|
||||
|
||||
Refer to [Dapr Actor Features]({{< ref howto-actors.md >}}) 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.
|
||||
|
||||
<img src="/images/actors_background_communication.png" width=600>
|
||||
|
||||
#### Reentrancy
|
||||
|
||||
To allow actors to "re-enter" and invoke methods on themselves, see [Actor Reentrancy]({{<ref actor-reentrancy.md>}}).
|
||||
|
||||
### 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.
|
||||
|
||||
<img src="/images/actors_background_concurrency.png" width=600>
|
||||
|
||||
## Next steps
|
||||
|
||||
{{< button text="Timers and reminders >>" page="actors-timers-reminders.md" >}}
|
||||
|
||||
## Related links
|
||||
|
||||
- [Actors API reference]({{< ref actors_api.md >}})
|
||||
- [Actors overview]({{< ref actors-overview.md >}})
|
||||
- [How to: Use virtual actors in Dapr]({{< ref howto-actors.md >}})
|
||||
|
|
@ -8,100 +8,101 @@ aliases:
|
|||
- "/developing-applications/building-blocks/actors/actors-background"
|
||||
---
|
||||
|
||||
## Introduction
|
||||
The [actor pattern](https://en.wikipedia.org/wiki/Actor_model) 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.
|
||||
|
||||
A large number of actors can execute simultaneously, and actors execute independently from each other.
|
||||
|
||||
Dapr includes a runtime that specifically implements the [Virtual Actor pattern](https://www.microsoft.com/research/project/orleans-virtual-actors/). With Dapr's implementation, you write your Dapr actors according to the Actor model, and Dapr leverages the scalability and reliability guarantees that the underlying platform provides.
|
||||
## Actors in Dapr
|
||||
|
||||
### When to use actors
|
||||
|
||||
As with any other technology decision, you should decide whether to use actors based on the problem you're trying to solve.
|
||||
|
||||
The actor design pattern can be a good fit to a number of distributed systems problems and scenarios, but the first thing you should consider are the constraints of the pattern. Generally speaking, consider the actor pattern to model your problem or scenario if:
|
||||
|
||||
* Your problem space involves a large number (thousands or more) of small, independent, and isolated units of state and logic.
|
||||
* You want to work with single-threaded objects that do not require significant interaction from external components, including querying state across a set of actors.
|
||||
* Your actor instances won't block callers with unpredictable delays by issuing I/O operations.
|
||||
|
||||
## Actors in dapr
|
||||
Dapr includes a runtime that specifically implements the [Virtual Actor pattern](https://www.microsoft.com/research/project/orleans-virtual-actors/). With Dapr's implementation, you write your Dapr actors according to the actor model, and Dapr leverages the scalability and reliability guarantees that the underlying platform provides.
|
||||
|
||||
Every actor is defined as an instance of an actor type, identical to the way an object is an instance of a class. For example, there may be an actor type that implements the functionality of a calculator and there could be many actors of that type that are distributed on various nodes across a cluster. Each such actor is uniquely identified by an actor ID.
|
||||
|
||||
<img src="/images/actor_background_game_example.png" width=400>
|
||||
|
||||
## Actor lifetime
|
||||
## Dapr actors vs. Dapr Workflow
|
||||
|
||||
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.
|
||||
Dapr actors builds on the state management and service invocation APIs to create stateful, long running objects with identity. [Dapr Workflow]({{< ref workflow-overview.md >}}) and Dapr Actors are related, with workflows building on actors to provide a higher level of abstraction to orchestrate a set of actors, implementing common workflow patterns and managing the lifecycle of actors on your behalf.
|
||||
|
||||
Invocation of actor methods and reminders reset the idle time, e.g. reminder firing will keep the actor active. Actor reminders fire whether an actor is active or inactive, if fired for inactive actor, it will activate the actor first. Actor timers do not reset the idle time, so timer firing will not keep the actor active. Timers only fire while the actor is active.
|
||||
Dapr actors are designed to provide a way to encapsulate state and behavior within a distributed system. An actor can be activated on demand by a client application. When an actor is activated, it is assigned a unique identity, which allows it to maintain its state across multiple invocations. This makes actors useful for building stateful, scalable, and fault-tolerant distributed applications.
|
||||
|
||||
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.
|
||||
On the other hand, Dapr Workflow provides a way to define and orchestrate complex workflows that involve multiple services and components within a distributed system. Workflows allow you to define a sequence of steps or tasks that need to be executed in a specific order, and can be used to implement business processes, event-driven workflows, and other similar scenarios.
|
||||
|
||||
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.
|
||||
As mentioned above, Dapr Workflow builds on Dapr Actors managing their activation and lifecycle.
|
||||
|
||||
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.
|
||||
### When to use Dapr actors
|
||||
|
||||
## Distribution and failover
|
||||
As with any other technology decision, you should decide whether to use actors based on the problem you're trying to solve. For example, if you were building a chat application, you might use Dapr actors to implement the chat rooms and the individual chat sessions between users, as each chat session needs to maintain its own state and be scalable and fault-tolerant.
|
||||
|
||||
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.
|
||||
Generally speaking, consider the actor pattern to model your problem or scenario if:
|
||||
|
||||
Actors are distributed across the instances of the actor service, and those instance are distributed across the nodes in a cluster. Each service instance contains a set of actors for a given actor type.
|
||||
- Your problem space involves a large number (thousands or more) of small, independent, and isolated units of state and logic.
|
||||
- You want to work with single-threaded objects that do not require significant interaction from external components, including querying state across a set of actors.
|
||||
- Your actor instances won't block callers with unpredictable delays by issuing I/O operations.
|
||||
|
||||
### Actor placement service
|
||||
The Dapr actor runtime manages distribution scheme and key range settings for you. This is done by the actor `Placement` service. When a new instance of a service is created, the corresponding Dapr runtime registers the actor types it can create and the `Placement` service calculates the partitioning across all the instances for a given actor type. This table of partition information for each actor type is updated and stored in each Dapr instance running in the environment and can change dynamically as new instance of actor services are created and destroyed. This is shown in the diagram below.
|
||||
### When to use Dapr Workflow
|
||||
|
||||
You would use Dapr Workflow when you need to define and orchestrate complex workflows that involve multiple services and components. For example, using the [chat application example earlier]({{< ref "#when-to-use-dapr-actors" >}}), you might use Dapr Workflows to define the overall workflow of the application, such as how new users are registered, how messages are sent and received, and how the application handles errors and exceptions.
|
||||
|
||||
[Learn more about Dapr Workflow and how to use workflows in your application.]({{< ref workflow-overview.md >}})
|
||||
|
||||
## Features
|
||||
|
||||
### Actor lifetime
|
||||
|
||||
Since Dapr actors are virtual, they do not need to be explicitly created or destroyed. The Dapr actor runtime:
|
||||
1. Automatically activates an actor once it receives an initial request for that actor ID.
|
||||
1. Garbage-collects the in-memory object of unused actors.
|
||||
1. Maintains knowledge of the actor's existence in case it's reactivated later.
|
||||
|
||||
An actor's state outlives the object's lifetime, as state is stored in the configured state provider for Dapr runtime.
|
||||
|
||||
[Learn more about actor lifetimes.]({{< ref "actors-features-concepts.md#actor-lifetime" >}})
|
||||
|
||||
### Distribution and failover
|
||||
|
||||
To provide scalability and reliability, actors instances are throughout the cluster and Dapr distributes actor instances throughout the cluster and automatically migrates them to healthy nodes.
|
||||
|
||||
[Learn more about Dapr actor placement.]({{< ref "actors-features-concepts.md#actor-placement-service" >}})
|
||||
|
||||
### Actor communication
|
||||
|
||||
You can invoke actor methods by calling them over HTTP, as shown in the general example below.
|
||||
|
||||
<img src="/images/actors_background_placement_service_registration.png" width=600>
|
||||
|
||||
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.
|
||||
1. The service calls the actor API on the sidecar.
|
||||
1. With the cached partitioning information from the placement service, the sidecar determines which actor service instance will host actor ID **3**. The call is forwarded to the appropriate sidecar.
|
||||
1. The sidecar instance in pod 2 calls the service instance to invoke the actor and execute the actor method.
|
||||
|
||||
<img src="/images/actors_background_id_hashing_calling.png" width=600>
|
||||
[Learn more about calling actor methods.]({{< ref "actors-features-concepts.md#actor-communication" >}})
|
||||
|
||||
This simplifies some choices but also carries some consideration:
|
||||
#### Concurrency
|
||||
|
||||
* 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.
|
||||
The Dapr actor runtime provides a simple turn-based access model for accessing actor methods. Turn-based access greatly simplifies concurrent systems as there is no need for synchronization mechanisms for data access.
|
||||
|
||||
Note: The Dapr actor Placement service is only used for actor placement and therefore is not needed if your services are not using Dapr actors. The Placement service can run in all [hosting environments]({{< ref hosting >}}), including self-hosted and Kubernetes.
|
||||
- [Learn more about actor reentrancy]({{< ref "actor-reentrancy.md" >}})
|
||||
- [Learn more about the turn-based access model]({{< ref "actors-features-concepts.md#turn-based-access" >}})
|
||||
|
||||
## Actor communication
|
||||
### Actor timers and reminders
|
||||
|
||||
You can interact with Dapr to invoke the actor method by calling HTTP/gRPC endpoint.
|
||||
Actors can schedule periodic work on themselves by registering either timers or reminders.
|
||||
|
||||
```bash
|
||||
POST/GET/PUT/DELETE http://localhost:3500/v1.0/actors/<actorType>/<actorId>/<method/state/timers/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 actor state provider.
|
||||
|
||||
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.
|
||||
This distinction allows users to trade off between light-weight but stateless timers vs. more resource-demanding but stateful reminders.
|
||||
|
||||
Another, and perhaps more convenient, way of interacting with actors is via SDKs. Dapr currently supports actors SDKs in [.NET]({{< ref "dotnet-actors" >}}), [Java]({{< ref "java#actors" >}}), and [Python]({{< ref "python-actor" >}}).
|
||||
- [Learn more about actor timers.]({{< ref "actors-features-concepts.md#timers" >}})
|
||||
- [Learn more about actor reminders.]({{< ref "actors-features-concepts.md#reminders" >}})
|
||||
- [Learn more about timer and reminder error handling and failover.]({{< ref "actors-features-concepts.md#timers-and-reminders-error-handling" >}})
|
||||
|
||||
Refer to [Dapr Actor Features]({{< ref howto-actors.md >}}) for more details.
|
||||
## Next steps
|
||||
|
||||
### Concurrency
|
||||
{{< button text="Actors features and concepts >>" page="actors-features-concepts.md" >}}
|
||||
|
||||
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.
|
||||
|
||||
<img src="/images/actors_background_communication.png" width=600>
|
||||
|
||||
#### Reentrancy
|
||||
|
||||
To allow actors to "re-enter" and invoke methods on themselves, see [Actor Reentrancy]({{<ref actor-reentrancy.md>}}).
|
||||
|
||||
### 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.
|
||||
|
||||
<img src="/images/actors_background_concurrency.png" width=600>
|
||||
## Related links
|
||||
|
||||
- [Actors API reference]({{< ref actors_api.md >}})
|
||||
- Refer to the [Dapr SDK documentation and examples]({{< ref "developing-applications/sdks/#sdk-languages" >}}).
|
||||
|
|
@ -0,0 +1,206 @@
|
|||
---
|
||||
type: docs
|
||||
title: "Actor runtime configuration parameters"
|
||||
linkTitle: "Runtime configuration"
|
||||
weight: 30
|
||||
description: Modify the default Dapr actor runtime configuration behavior
|
||||
---
|
||||
|
||||
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 |
|
||||
| `remindersStoragePartitions` | Configure the number of partitions for actor's reminders. If not provided, all reminders are saved as a single record in actor's state store. | 0 |
|
||||
| `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
|
||||
|
||||
{{< tabs ".NET" JavaScript Python Java Go >}}
|
||||
|
||||
{{% codetab %}}
|
||||
```csharp
|
||||
// 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.RemindersStoragePartitions = 7;
|
||||
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 registring actors]({{< ref "dotnet-actors-usage.md#registring-actors" >}}).
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
|
||||
<!--javascript-->
|
||||
|
||||
```js
|
||||
import { CommunicationProtocolEnum, DaprClient, DaprServer } from "@dapr/dapr";
|
||||
|
||||
// Configure the actor runtime with the DaprClientOptions.
|
||||
const clientOptions = {
|
||||
actor: {
|
||||
actorIdleTimeout: "1h",
|
||||
actorScanInterval: "30s",
|
||||
drainOngoingCallTimeout: "1m",
|
||||
drainRebalancedActors: true,
|
||||
reentrancy: {
|
||||
enabled: true,
|
||||
maxStackDepth: 32,
|
||||
},
|
||||
remindersStoragePartitions: 0,
|
||||
},
|
||||
};
|
||||
|
||||
// Use the options when creating DaprServer and DaprClient.
|
||||
|
||||
// Note, DaprServer creates a DaprClient internally, which needs to be configured with clientOptions.
|
||||
const server = new DaprServer(serverHost, serverPort, daprHost, daprPort, clientOptions);
|
||||
|
||||
const client = new DaprClient(daprHost, daprPort, CommunicationProtocolEnum.HTTP, clientOptions);
|
||||
```
|
||||
|
||||
[See the documentation on writing actors with the JavaScript SDK]({{< ref "js-actors.md#registering-actors" >}}).
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
|
||||
<!--python-->
|
||||
|
||||
```python
|
||||
from datetime import timedelta
|
||||
from dapr.actor.runtime.config import ActorRuntimeConfig, ActorReentrancyConfig
|
||||
|
||||
ActorRuntime.set_actor_config(
|
||||
ActorRuntimeConfig(
|
||||
actor_idle_timeout=timedelta(hours=1),
|
||||
actor_scan_interval=timedelta(seconds=30),
|
||||
drain_ongoing_call_timeout=timedelta(minutes=1),
|
||||
drain_rebalanced_actors=True,
|
||||
reentrancy=ActorReentrancyConfig(enabled=False),
|
||||
remindersStoragePartitions=7
|
||||
)
|
||||
)
|
||||
```
|
||||
|
||||
[See the documentation on running actors with the Python SDK]({{< ref "python-actor.md" >}})
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
|
||||
<!--java-->
|
||||
|
||||
```java
|
||||
// import io.dapr.actors.runtime.ActorRuntime;
|
||||
// import java.time.Duration;
|
||||
|
||||
ActorRuntime.getInstance().getConfig().setActorIdleTimeout(Duration.ofMinutes(60));
|
||||
ActorRuntime.getInstance().getConfig().setActorScanInterval(Duration.ofSeconds(30));
|
||||
ActorRuntime.getInstance().getConfig().setDrainOngoingCallTimeout(Duration.ofSeconds(60));
|
||||
ActorRuntime.getInstance().getConfig().setDrainBalancedActors(true);
|
||||
ActorRuntime.getInstance().getConfig().setActorReentrancyConfig(false, null);
|
||||
ActorRuntime.getInstance().getConfig().setRemindersStoragePartitions(7);
|
||||
```
|
||||
|
||||
[See the documentation on writing actors with the Java SDK]({{< ref "java.md#actors" >}}).
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
<!--go-->
|
||||
|
||||
```go
|
||||
const (
|
||||
defaultActorType = "basicType"
|
||||
reentrantActorType = "reentrantType"
|
||||
)
|
||||
|
||||
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"`
|
||||
EntitiesConfig []config.EntityConfig `json:"entitiesConfig,omitempty"`
|
||||
}
|
||||
|
||||
var daprConfigResponse = daprConfig{
|
||||
Entities: []string{defaultActorType, reentrantActorType},
|
||||
ActorIdleTimeout: actorIdleTimeout,
|
||||
ActorScanInterval: actorScanInterval,
|
||||
DrainOngoingCallTimeout: drainOngoingCallTimeout,
|
||||
DrainRebalancedActors: drainRebalancedActors,
|
||||
Reentrancy: config.ReentrancyConfig{Enabled: false},
|
||||
EntitiesConfig: []config.EntityConfig{
|
||||
{
|
||||
// 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, `reentrantActorType` has reentrancy enabled; however, 'defaultActorType' will not have reentrancy enabled.
|
||||
Entities: []string{reentrantActorType},
|
||||
Reentrancy: config.ReentrancyConfig{
|
||||
Enabled: true,
|
||||
MaxStackDepth: &maxStackDepth,
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
func configHandler(w http.ResponseWriter, r *http.Request) {
|
||||
w.Header().Set("Content-Type", "application/json")
|
||||
w.WriteHeader(http.StatusOK)
|
||||
json.NewEncoder(w).Encode(daprConfigResponse)
|
||||
}
|
||||
```
|
||||
|
||||
[See an example for using actors with the Go SDK](https://github.com/dapr/go-sdk/tree/main/examples/actor).
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{< /tabs >}}
|
||||
|
||||
## Next steps
|
||||
|
||||
{{< button text="Enable actor reminder partitioning >>" page="howto-actors-partitioning.md" >}}
|
||||
|
||||
## Related links
|
||||
|
||||
- Refer to the [Dapr SDK documentation and examples]({{< ref "developing-applications/sdks/#sdk-languages" >}}).
|
||||
- [Actors API reference]({{< ref actors_api.md >}})
|
||||
- [Actors overview]({{< ref actors-overview.md >}})
|
||||
|
|
@ -0,0 +1,156 @@
|
|||
---
|
||||
type: docs
|
||||
title: "Actors timers and reminders"
|
||||
linkTitle: "Timers and reminders"
|
||||
weight: 40
|
||||
description: "Setting timers and reminders and performing error handling for your actors"
|
||||
aliases:
|
||||
- "/developing-applications/building-blocks/actors/actors-background"
|
||||
---
|
||||
|
||||
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 actor state provider.
|
||||
|
||||
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 identical, as summarized below:
|
||||
|
||||
---
|
||||
`dueTime` is an optional parameter that sets time at which or time interval before the callback is invoked for the first time. If `dueTime` is omitted, the callback is invoked immediately after timer/reminder registration.
|
||||
|
||||
Supported formats:
|
||||
- RFC3339 date format, e.g. `2020-10-02T15:00:00Z`
|
||||
- time.Duration format, e.g. `2h30m`
|
||||
- [ISO 8601 duration](https://en.wikipedia.org/wiki/ISO_8601#Durations) format, e.g. `PT2H30M`
|
||||
|
||||
---
|
||||
`period` is an optional parameter that sets time interval between two consecutive callback invocations. When specified in `ISO 8601-1 duration` format, you can also configure the number of repetition in order to limit the total number of callback invocations.
|
||||
If `period` is omitted, the callback will be invoked only once.
|
||||
|
||||
Supported formats:
|
||||
- time.Duration format, e.g. `2h30m`
|
||||
- [ISO 8601 duration](https://en.wikipedia.org/wiki/ISO_8601#Durations) format, e.g. `PT2H30M`, `R5/PT1M30S`
|
||||
|
||||
---
|
||||
`ttl` is an optional parameter that sets time at which or time interval after which the timer/reminder will be expired and deleted. If `ttl` is omitted, no restrictions are applied.
|
||||
|
||||
Supported formats:
|
||||
* RFC3339 date format, e.g. `2020-10-02T15:00:00Z`
|
||||
* time.Duration format, e.g. `2h30m`
|
||||
* [ISO 8601 duration](https://en.wikipedia.org/wiki/ISO_8601#Durations) format. Example: `PT2H30M`
|
||||
|
||||
---
|
||||
The actor runtime validates correctness of the scheduling configuration and returns error on invalid input.
|
||||
|
||||
When you specify both the number of repetitions in `period` as well as `ttl`, the timer/reminder will be stopped when either condition is met.
|
||||
|
||||
## Actor timers
|
||||
|
||||
You can register a callback on actor to be executed based on a timer.
|
||||
|
||||
The Dapr actor runtime ensures that the callback methods respect the turn-based concurrency guarantees. This means that no other actor methods or timer/reminder callbacks will be in progress until this callback completes execution.
|
||||
|
||||
The Dapr actor runtime saves changes made to the actor's state when the callback finishes. If an error occurs in saving the state, that actor object is deactivated and a new instance will be activated.
|
||||
|
||||
All timers are stopped when the actor is deactivated as part of garbage collection. No timer callbacks are invoked after that. Also, the Dapr actor runtime does not retain any information about the timers that were running before deactivation. It is up to the actor to register any timers that it needs when it is reactivated in the future.
|
||||
|
||||
You can create a timer for an actor by calling the HTTP/gRPC request to Dapr as shown below, or via Dapr SDK.
|
||||
|
||||
```md
|
||||
POST/PUT http://localhost:3500/v1.0/actors/<actorType>/<actorId>/timers/<name>
|
||||
```
|
||||
|
||||
### Examples
|
||||
|
||||
The timer parameters are specified in the request body.
|
||||
|
||||
The following request body configures a timer with a `dueTime` of 9 seconds and a `period` of 3 seconds. This means it will first fire after 9 seconds, then every 3 seconds after that.
|
||||
```json
|
||||
{
|
||||
"dueTime":"0h0m9s0ms",
|
||||
"period":"0h0m3s0ms"
|
||||
}
|
||||
```
|
||||
|
||||
The following request body configures a timer with a `period` of 3 seconds (in ISO 8601 duration format). It also limits the number of invocations to 10. This means it will fire 10 times: first, immediately after registration, then every 3 seconds after that.
|
||||
```json
|
||||
{
|
||||
"period":"R10/PT3S",
|
||||
}
|
||||
```
|
||||
|
||||
The following request body configures a timer with a `period` of 3 seconds (in ISO 8601 duration format) and a `ttl` of 20 seconds. This means it fires immediately after registration, then every 3 seconds after that for the duration of 20 seconds.
|
||||
```json
|
||||
{
|
||||
"period":"PT3S",
|
||||
"ttl":"20s"
|
||||
}
|
||||
```
|
||||
|
||||
The following request body configures a timer with a `dueTime` of 10 seconds, a `period` of 3 seconds, and a `ttl` of 10 seconds. It also limits the number of invocations to 4. This means it will first fire after 10 seconds, then every 3 seconds after that for the duration of 10 seconds, but no more than 4 times in total.
|
||||
```json
|
||||
{
|
||||
"dueTime":"10s",
|
||||
"period":"R4/PT3S",
|
||||
"ttl":"10s"
|
||||
}
|
||||
```
|
||||
|
||||
You can remove the actor timer by calling
|
||||
|
||||
```md
|
||||
DELETE http://localhost:3500/v1.0/actors/<actorType>/<actorId>/timers/<name>
|
||||
```
|
||||
|
||||
Refer [api spec]({{< ref "actors_api.md#invoke-timer" >}}) for more details.
|
||||
|
||||
## Actor reminders
|
||||
|
||||
Reminders are a mechanism to trigger *persistent* callbacks on an actor at specified times. Their functionality is similar to timers. But unlike timers, reminders are triggered under all circumstances until the actor explicitly unregisters them or the actor is explicitly deleted or the number in invocations is exhausted. Specifically, reminders are triggered across actor deactivations and failovers because the Dapr actor runtime persists the information about the actors' reminders using Dapr actor state provider.
|
||||
|
||||
You can create a persistent reminder for an actor by calling the HTTP/gRPC request to Dapr as shown below, or via Dapr SDK.
|
||||
|
||||
```md
|
||||
POST/PUT http://localhost:3500/v1.0/actors/<actorType>/<actorId>/reminders/<name>
|
||||
```
|
||||
|
||||
The request structure for reminders is identical to those of actors. Please refer to the [actor timers examples]({{< ref "#actor-timers" >}}).
|
||||
|
||||
### Retrieve actor reminder
|
||||
|
||||
You can retrieve the actor reminder by calling
|
||||
|
||||
```md
|
||||
GET http://localhost:3500/v1.0/actors/<actorType>/<actorId>/reminders/<name>
|
||||
```
|
||||
|
||||
### Remove the actor reminder
|
||||
|
||||
You can remove the actor reminder by calling
|
||||
|
||||
```md
|
||||
DELETE http://localhost:3500/v1.0/actors/<actorType>/<actorId>/reminders/<name>
|
||||
```
|
||||
|
||||
Refer [api spec]({{< ref "actors_api.md#invoke-reminder" >}}) for more details.
|
||||
|
||||
## Error handling
|
||||
|
||||
When an actor's method completes successfully, the runtime will contineu to invoke the method at the specified timer or reminder schedule. However, if the method throws an exception, the runtime catches it and logs the error message in the Dapr sidecar logs, without retrying.
|
||||
|
||||
To allow actors to recover from failures and retry after a crash or restart, you can persist an actor's state by configuring a state store, like Redis or Azure Cosmos DB.
|
||||
|
||||
If an invocation of the method fails, the timer is not removed. Timers are only removed when:
|
||||
- The sidecar crashes
|
||||
- The executions run out
|
||||
- You delete it explicitly
|
||||
|
||||
## Next steps
|
||||
|
||||
{{< button text="Configure actor runtime behavior >>" page="actors-runtime-config.md" >}}
|
||||
|
||||
## Related links
|
||||
|
||||
- [Actors API reference]({{< ref actors_api.md >}})
|
||||
- [Actors overview]({{< ref actors-overview.md >}})
|
||||
|
|
@ -0,0 +1,196 @@
|
|||
---
|
||||
type: docs
|
||||
title: "How to: Enable partitioning of actor reminders"
|
||||
linkTitle: "How to: Partition reminders"
|
||||
weight: 50
|
||||
description: "Enable actor reminders partitioning for your application"
|
||||
aliases:
|
||||
- "/developing-applications/building-blocks/actors/actors-background"
|
||||
---
|
||||
|
||||
[Actor reminders]({{< ref "howto-actors-partitioning.md#actor-reminders" >}}) are persisted and continue to be triggered after sidecar restarts. Applications with multiple reminders registered can experience the following issues:
|
||||
|
||||
- Low throughput on reminders registration and de-registration
|
||||
- Limited number of reminders registered based on the single record size limit on the state store
|
||||
|
||||
To sidestep these issues, applications can enable partitioning of actor reminders while data is distributed in multiple keys in the state store.
|
||||
|
||||
1. A metadata record in `actors\|\|<actor type>\|\|metadata` is used to store the persisted configuration for a given actor type.
|
||||
1. Multiple records store subsets of the reminders for the same actor type.
|
||||
|
||||
| Key | Value |
|
||||
| ----------- | ----------- |
|
||||
| `actors\|\|<actor type>\|\|metadata` | `{ "id": <actor metadata identifier>, "actorRemindersMetadata": { "partitionCount": <number of partitions for reminders> } }` |
|
||||
| `actors\|\|<actor type>\|\|<actor metadata identifier>\|\|reminders\|\|1` | `[ <reminder 1-1>, <reminder 1-2>, ... , <reminder 1-n> ]` |
|
||||
| `actors\|\|<actor type>\|\|<actor metadata identifier>\|\|reminders\|\|2` | `[ <reminder 1-1>, <reminder 1-2>, ... , <reminder 1-m> ]` |
|
||||
|
||||
If you need to change the number of partitions, Dapr's sidecar will automatically redistribute the reminders' set.
|
||||
|
||||
## Configure the actor runtime to partition actor reminders
|
||||
|
||||
Similar to other actor configuration elements, the actor runtime provides the appropriate configuration to partition actor reminders via the actor's endpoint for `GET /dapr/config`. Select your preferred language for an actor runtime configuration example.
|
||||
|
||||
{{< tabs ".NET" JavaScript Python Java Go >}}
|
||||
|
||||
{{% codetab %}}
|
||||
|
||||
<!--dotnet-->
|
||||
|
||||
```csharp
|
||||
// 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.RemindersStoragePartitions = 7;
|
||||
});
|
||||
|
||||
// Register additional services for use with actors
|
||||
services.AddSingleton<BankService>();
|
||||
}
|
||||
```
|
||||
|
||||
[See the .NET SDK documentation on registring actors]({{< ref "dotnet-actors-usage.md#registring-actors" >}}).
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
<!--javascript-->
|
||||
|
||||
```js
|
||||
import { CommunicationProtocolEnum, DaprClient, DaprServer } from "@dapr/dapr";
|
||||
|
||||
// Configure the actor runtime with the DaprClientOptions.
|
||||
const clientOptions = {
|
||||
actor: {
|
||||
remindersStoragePartitions: 0,
|
||||
},
|
||||
};
|
||||
|
||||
const actor = builder.build(new ActorId("my-actor"));
|
||||
|
||||
// Register a reminder, it has a default callback: `receiveReminder`
|
||||
await actor.registerActorReminder(
|
||||
"reminder-id", // Unique name of the reminder.
|
||||
Temporal.Duration.from({ seconds: 2 }), // DueTime
|
||||
Temporal.Duration.from({ seconds: 1 }), // Period
|
||||
Temporal.Duration.from({ seconds: 1 }), // TTL
|
||||
100, // State to be sent to reminder callback.
|
||||
);
|
||||
|
||||
// Delete the reminder
|
||||
await actor.unregisterActorReminder("reminder-id");
|
||||
```
|
||||
|
||||
[See the documentation on writing actors with the JavaScript SDK]({{< ref "js-actors.md#registering-actors" >}}).
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
|
||||
<!--python-->
|
||||
|
||||
```python
|
||||
from datetime import timedelta
|
||||
|
||||
ActorRuntime.set_actor_config(
|
||||
ActorRuntimeConfig(
|
||||
actor_idle_timeout=timedelta(hours=1),
|
||||
actor_scan_interval=timedelta(seconds=30),
|
||||
remindersStoragePartitions=7
|
||||
)
|
||||
)
|
||||
```
|
||||
|
||||
[See the documentation on running actors with the Python SDK]({{< ref "python-actor.md" >}})
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
<!--java-->
|
||||
|
||||
```java
|
||||
// import io.dapr.actors.runtime.ActorRuntime;
|
||||
// import java.time.Duration;
|
||||
|
||||
ActorRuntime.getInstance().getConfig().setActorIdleTimeout(Duration.ofMinutes(60));
|
||||
ActorRuntime.getInstance().getConfig().setActorScanInterval(Duration.ofSeconds(30));
|
||||
ActorRuntime.getInstance().getConfig().setRemindersStoragePartitions(7);
|
||||
```
|
||||
|
||||
[See the documentation on writing actors with the Java SDK]({{< ref "java.md#actors" >}}).
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
<!--go-->
|
||||
|
||||
```go
|
||||
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"`
|
||||
RemindersStoragePartitions int `json:"remindersStoragePartitions,omitempty"`
|
||||
}
|
||||
|
||||
var daprConfigResponse = daprConfig{
|
||||
[]string{defaultActorType},
|
||||
actorIdleTimeout,
|
||||
actorScanInterval,
|
||||
drainOngoingCallTimeout,
|
||||
drainRebalancedActors,
|
||||
7,
|
||||
}
|
||||
|
||||
func configHandler(w http.ResponseWriter, r *http.Request) {
|
||||
w.Header().Set("Content-Type", "application/json")
|
||||
w.WriteHeader(http.StatusOK)
|
||||
json.NewEncoder(w).Encode(daprConfigResponse)
|
||||
}
|
||||
```
|
||||
|
||||
[See an example for using actors with the Go SDK](https://github.com/dapr/go-sdk/tree/main/examples/actor).
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{< /tabs >}}
|
||||
|
||||
The following is an example of a valid configuration for reminder partitioning:
|
||||
|
||||
```json
|
||||
{
|
||||
"entities": [ "MyActorType", "AnotherActorType" ],
|
||||
"remindersStoragePartitions": 7
|
||||
}
|
||||
```
|
||||
|
||||
## Handle configuration changes
|
||||
|
||||
To configure actor reminders partitioning, Dapr persists the actor type metadata in the actor's state store. This allows the configuration changes to be applied globally, not just in a single sidecar instance.
|
||||
|
||||
In addition, **you can only increase the number of partitions**, not decrease. This allows Dapr to automatically redistribute the data on a rolling restart, where one or more partition configurations might be active.
|
||||
|
||||
## Demo
|
||||
|
||||
Watch [this video for a demo of actor reminder partitioning](https://youtu.be/ZwFOEUYe1WA?t=1493):
|
||||
|
||||
<div class="embed-responsive embed-responsive-16by9">
|
||||
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/ZwFOEUYe1WA?start=1495" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
|
||||
|
||||
## Next steps
|
||||
|
||||
{{< button text="Interact with virtual actors >>" page="howto-actors.md" >}}
|
||||
|
||||
## Related links
|
||||
|
||||
- [Actors API reference]({{< ref actors_api.md >}})
|
||||
- [Actors overview]({{< ref actors-overview.md >}})
|
||||
|
|
@ -1,14 +1,14 @@
|
|||
---
|
||||
type: docs
|
||||
title: "How-to: Use virtual actors in Dapr"
|
||||
linkTitle: "How-To: Virtual actors"
|
||||
weight: 20
|
||||
description: Learn more about the actor pattern
|
||||
title: "How-to: Interact with virtual actors using scripting"
|
||||
linkTitle: "How-To: Interact with virtual actors"
|
||||
weight: 60
|
||||
description: Invoke the actor method for state management
|
||||
---
|
||||
|
||||
The Dapr actor runtime provides support for [virtual actors]({{< ref actors-overview.md >}}) through following capabilities:
|
||||
Learn how to use virtual actors by calling HTTP/gRPC endpoints.
|
||||
|
||||
## Actor method invocation
|
||||
## Invoke the actor method
|
||||
|
||||
You can interact with Dapr to invoke the actor method by calling HTTP/gRPC endpoint.
|
||||
|
||||
|
|
@ -16,424 +16,28 @@ You can interact with Dapr to invoke the actor method by calling HTTP/gRPC endpo
|
|||
POST/GET/PUT/DELETE http://localhost:3500/v1.0/actors/<actorType>/<actorId>/method/<method>
|
||||
```
|
||||
|
||||
You can provide any data for the actor method in the request body and the response for the request is in response body which is data from actor method call.
|
||||
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 [api spec]({{< ref "actors_api.md#invoke-actor-method" >}}) for more details.
|
||||
Refer [to the Actors API spec]({{< ref "actors_api.md#invoke-actor-method" >}}) for more details.
|
||||
|
||||
Alternatively, you can use the Dapr SDK in [.NET]({{< ref "dotnet-actors" >}}), [Java]({{< ref "java#actors" >}}), or [Python]({{< ref "python-actor" >}}).
|
||||
{{% alert title="Note" color="primary" %}}
|
||||
Alternatively, you can use [Dapr SDKs to use actors]({{< ref "developing-applications/sdks/#sdk-languages" >}}).
|
||||
{{% /alert %}}
|
||||
|
||||
## Actor state management
|
||||
## Save state with actors
|
||||
|
||||
Actors can save state reliably using state management capability.
|
||||
You can interact with Dapr through HTTP/gRPC endpoints for state management.
|
||||
You can interact with Dapr via HTTP/gRPC endpoints to save state reliably using the Dapr actor state mangement capabaility.
|
||||
|
||||
To use actors, your state store must support multi-item transactions. This means your state store [component](https://github.com/dapr/components-contrib/tree/master/state) must implement the [TransactionalStore](https://github.com/dapr/components-contrib/blob/master/state/transactional_store.go) interface. The list of components that support transactions/actors can be found here: [supported state stores]({{< ref supported-state-stores.md >}}). Only a single state store component can be used as the statestore for all actors.
|
||||
To use actors, your state store must support multi-item transactions. This means your state store component must implement the `TransactionalStore` interface.
|
||||
|
||||
## Actor timers and reminders
|
||||
[See the list of components that support transactions/actors]({{< ref supported-state-stores.md >}}). Only a single state store component can be used as the state store for all actors.
|
||||
|
||||
Actors can schedule periodic work on themselves by registering either timers or reminders.
|
||||
## Next steps
|
||||
|
||||
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 actor state provider.
|
||||
{{< button text="Actor reentrancy >>" page="actor-reentrancy.md" >}}
|
||||
|
||||
This distinction allows users to trade off between light-weight but stateless timers vs. more resource-demanding but stateful reminders.
|
||||
## Related links
|
||||
|
||||
The scheduling configuration of timers and reminders is identical, as summarized below:
|
||||
|
||||
---
|
||||
`dueTime` is an optional parameter that sets time at which or time interval before the callback is invoked for the first time. If `dueTime` is omitted, the callback is invoked immediately after timer/reminder registration.
|
||||
|
||||
Supported formats:
|
||||
- RFC3339 date format, e.g. `2020-10-02T15:00:00Z`
|
||||
- time.Duration format, e.g. `2h30m`
|
||||
- [ISO 8601 duration](https://en.wikipedia.org/wiki/ISO_8601#Durations) format, e.g. `PT2H30M`
|
||||
|
||||
---
|
||||
`period` is an optional parameter that sets time interval between two consecutive callback invocations. When specified in `ISO 8601-1 duration` format, you can also configure the number of repetition in order to limit the total number of callback invocations.
|
||||
If `period` is omitted, the callback will be invoked only once.
|
||||
|
||||
Supported formats:
|
||||
- time.Duration format, e.g. `2h30m`
|
||||
- [ISO 8601 duration](https://en.wikipedia.org/wiki/ISO_8601#Durations) format, e.g. `PT2H30M`, `R5/PT1M30S`
|
||||
|
||||
---
|
||||
`ttl` is an optional parameter that sets time at which or time interval after which the timer/reminder will be expired and deleted. If `ttl` is omitted, no restrictions are applied.
|
||||
|
||||
Supported formats:
|
||||
* RFC3339 date format, e.g. `2020-10-02T15:00:00Z`
|
||||
* time.Duration format, e.g. `2h30m`
|
||||
* [ISO 8601 duration](https://en.wikipedia.org/wiki/ISO_8601#Durations) format. Example: `PT2H30M`
|
||||
|
||||
---
|
||||
The actor runtime validates correctness of the scheduling configuration and returns error on invalid input.
|
||||
|
||||
When you specify both the number of repetitions in `period` as well as `ttl`, the timer/reminder will be stopped when either condition is met.
|
||||
|
||||
### Actor timers
|
||||
|
||||
You can register a callback on actor to be executed based on a timer.
|
||||
|
||||
The Dapr actor runtime ensures that the callback methods respect the turn-based concurrency guarantees. This means that no other actor methods or timer/reminder callbacks will be in progress until this callback completes execution.
|
||||
|
||||
The Dapr actor runtime saves changes made to the actor's state when the callback finishes. If an error occurs in saving the state, that actor object is deactivated and a new instance will be activated.
|
||||
|
||||
All timers are stopped when the actor is deactivated as part of garbage collection. No timer callbacks are invoked after that. Also, the Dapr actor runtime does not retain any information about the timers that were running before deactivation. It is up to the actor to register any timers that it needs when it is reactivated in the future.
|
||||
|
||||
You can create a timer for an actor by calling the HTTP/gRPC request to Dapr as shown below, or via Dapr SDK.
|
||||
|
||||
```md
|
||||
POST/PUT http://localhost:3500/v1.0/actors/<actorType>/<actorId>/timers/<name>
|
||||
```
|
||||
|
||||
**Examples**
|
||||
|
||||
The timer parameters are specified in the request body.
|
||||
|
||||
The following request body configures a timer with a `dueTime` of 9 seconds and a `period` of 3 seconds. This means it will first fire after 9 seconds, then every 3 seconds after that.
|
||||
```json
|
||||
{
|
||||
"dueTime":"0h0m9s0ms",
|
||||
"period":"0h0m3s0ms"
|
||||
}
|
||||
```
|
||||
|
||||
The following request body configures a timer with a `period` of 3 seconds (in ISO 8601 duration format). It also limits the number of invocations to 10. This means it will fire 10 times: first, immediately after registration, then every 3 seconds after that.
|
||||
```json
|
||||
{
|
||||
"period":"R10/PT3S",
|
||||
}
|
||||
```
|
||||
|
||||
The following request body configures a timer with a `period` of 3 seconds (in ISO 8601 duration format) and a `ttl` of 20 seconds. This means it fires immediately after registration, then every 3 seconds after that for the duration of 20 seconds.
|
||||
```json
|
||||
{
|
||||
"period":"PT3S",
|
||||
"ttl":"20s"
|
||||
}
|
||||
```
|
||||
|
||||
The following request body configures a timer with a `dueTime` of 10 seconds, a `period` of 3 seconds, and a `ttl` of 10 seconds. It also limits the number of invocations to 4. This means it will first fire after 10 seconds, then every 3 seconds after that for the duration of 10 seconds, but no more than 4 times in total.
|
||||
```json
|
||||
{
|
||||
"dueTime":"10s",
|
||||
"period":"R4/PT3S",
|
||||
"ttl":"10s"
|
||||
}
|
||||
```
|
||||
|
||||
You can remove the actor timer by calling
|
||||
|
||||
```md
|
||||
DELETE http://localhost:3500/v1.0/actors/<actorType>/<actorId>/timers/<name>
|
||||
```
|
||||
|
||||
Refer [api spec]({{< ref "actors_api.md#invoke-timer" >}}) for more details.
|
||||
|
||||
### Actor reminders
|
||||
|
||||
Reminders are a mechanism to trigger *persistent* callbacks on an actor at specified times. Their functionality is similar to timers. But unlike timers, reminders are triggered under all circumstances until the actor explicitly unregisters them or the actor is explicitly deleted or the number in invocations is exhausted. Specifically, reminders are triggered across actor deactivations and failovers because the Dapr actor runtime persists the information about the actors' reminders using Dapr actor state provider.
|
||||
|
||||
You can create a persistent reminder for an actor by calling the HTTP/gRPC request to Dapr as shown below, or via Dapr SDK.
|
||||
|
||||
```md
|
||||
POST/PUT http://localhost:3500/v1.0/actors/<actorType>/<actorId>/reminders/<name>
|
||||
```
|
||||
|
||||
The request structure for reminders is identical to those of actors. Please refer to the [actor timers examples]({{< ref "#actor-timers" >}}).
|
||||
|
||||
#### Retrieve actor reminder
|
||||
|
||||
You can retrieve the actor reminder by calling
|
||||
|
||||
```md
|
||||
GET http://localhost:3500/v1.0/actors/<actorType>/<actorId>/reminders/<name>
|
||||
```
|
||||
|
||||
#### Remove the actor reminder
|
||||
|
||||
You can remove the actor reminder by calling
|
||||
|
||||
```md
|
||||
DELETE http://localhost:3500/v1.0/actors/<actorType>/<actorId>/reminders/<name>
|
||||
```
|
||||
|
||||
Refer [api spec]({{< ref "actors_api.md#invoke-reminder" >}}) for more details.
|
||||
|
||||
## Actor runtime configuration
|
||||
|
||||
You can configure the Dapr actor runtime configuration to modify the default runtime behavior.
|
||||
|
||||
### Configuration parameters
|
||||
- `entities` - The actor types supported by this host.
|
||||
- `actorIdleTimeout` - The timeout before deactivating an idle actor. Checks for timeouts occur every `actorScanInterval` interval. **Default: 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. **Default: 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. **Default: 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. **Default: true**
|
||||
- `reentrancy` (ActorReentrancyConfig) - Configure the reentrancy behavior for an actor. If not provided, reentrancy is disabled. **Default: disabled**
|
||||
**Default: false**
|
||||
- `remindersStoragePartitions` - Configure the number of partitions for actor's reminders. If not provided, all reminders are saved as a single record in actor's state store. **Default: 0**
|
||||
- `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. **Default: None**
|
||||
|
||||
{{< tabs Java Dotnet Python Go >}}
|
||||
|
||||
{{% codetab %}}
|
||||
```java
|
||||
// import io.dapr.actors.runtime.ActorRuntime;
|
||||
// import java.time.Duration;
|
||||
|
||||
ActorRuntime.getInstance().getConfig().setActorIdleTimeout(Duration.ofMinutes(60));
|
||||
ActorRuntime.getInstance().getConfig().setActorScanInterval(Duration.ofSeconds(30));
|
||||
ActorRuntime.getInstance().getConfig().setDrainOngoingCallTimeout(Duration.ofSeconds(60));
|
||||
ActorRuntime.getInstance().getConfig().setDrainBalancedActors(true);
|
||||
ActorRuntime.getInstance().getConfig().setActorReentrancyConfig(false, null);
|
||||
ActorRuntime.getInstance().getConfig().setRemindersStoragePartitions(7);
|
||||
```
|
||||
|
||||
See [this example](https://github.com/dapr/java-sdk/blob/master/examples/src/main/java/io/dapr/examples/actors/DemoActorService.java)
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
```csharp
|
||||
// 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.RemindersStoragePartitions = 7;
|
||||
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](https://github.com/dapr/dotnet-sdk/blob/master/daprdocs/content/en/dotnet-sdk-docs/dotnet-actors/dotnet-actors-usage.md#registering-actors).
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
```python
|
||||
from datetime import timedelta
|
||||
from dapr.actor.runtime.config import ActorRuntimeConfig, ActorReentrancyConfig
|
||||
|
||||
ActorRuntime.set_actor_config(
|
||||
ActorRuntimeConfig(
|
||||
actor_idle_timeout=timedelta(hours=1),
|
||||
actor_scan_interval=timedelta(seconds=30),
|
||||
drain_ongoing_call_timeout=timedelta(minutes=1),
|
||||
drain_rebalanced_actors=True,
|
||||
reentrancy=ActorReentrancyConfig(enabled=False),
|
||||
remindersStoragePartitions=7
|
||||
)
|
||||
)
|
||||
```
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
```go
|
||||
const (
|
||||
defaultActorType = "basicType"
|
||||
reentrantActorType = "reentrantType"
|
||||
)
|
||||
|
||||
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"`
|
||||
EntitiesConfig []config.EntityConfig `json:"entitiesConfig,omitempty"`
|
||||
}
|
||||
|
||||
var daprConfigResponse = daprConfig{
|
||||
Entities: []string{defaultActorType, reentrantActorType},
|
||||
ActorIdleTimeout: actorIdleTimeout,
|
||||
ActorScanInterval: actorScanInterval,
|
||||
DrainOngoingCallTimeout: drainOngoingCallTimeout,
|
||||
DrainRebalancedActors: drainRebalancedActors,
|
||||
Reentrancy: config.ReentrancyConfig{Enabled: false},
|
||||
EntitiesConfig: []config.EntityConfig{
|
||||
{
|
||||
// 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, `reentrantActorType` has reentrancy enabled; however, 'defaultActorType' will not have reentrancy enabled.
|
||||
Entities: []string{reentrantActorType},
|
||||
Reentrancy: config.ReentrancyConfig{
|
||||
Enabled: true,
|
||||
MaxStackDepth: &maxStackDepth,
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
func configHandler(w http.ResponseWriter, r *http.Request) {
|
||||
w.Header().Set("Content-Type", "application/json")
|
||||
w.WriteHeader(http.StatusOK)
|
||||
json.NewEncoder(w).Encode(daprConfigResponse)
|
||||
}
|
||||
```
|
||||
{{% /codetab %}}
|
||||
|
||||
{{< /tabs >}}
|
||||
|
||||
Refer to the documentation and examples of the [Dapr SDKs]({{< ref "developing-applications/sdks/#sdk-languages" >}}) for more details.
|
||||
|
||||
## Partitioning reminders
|
||||
|
||||
Actor reminders are persisted and continue to be triggered after sidecar restarts. Applications with multiple reminders registered can experience the following issues:
|
||||
|
||||
- Low throughput on reminders registration and de-registration
|
||||
- Limit on the total number of reminders registered based on the single record size limit on the state store
|
||||
|
||||
Applications can enable partitioning of actor reminders while data is distributed in multiple keys in the state store.
|
||||
|
||||
1. A metadata record in `actors\|\|<actor type>\|\|metadata` is used to store persisted configuration for a given actor type.
|
||||
1. Multiple records store subsets of the reminders for the same actor type.
|
||||
|
||||
| Key | Value |
|
||||
| ----------- | ----------- |
|
||||
| `actors\|\|<actor type>\|\|metadata` | `{ "id": <actor metadata identifier>, "actorRemindersMetadata": { "partitionCount": <number of partitions for reminders> } }` |
|
||||
| `actors\|\|<actor type>\|\|<actor metadata identifier>\|\|reminders\|\|1` | `[ <reminder 1-1>, <reminder 1-2>, ... , <reminder 1-n> ]` |
|
||||
| `actors\|\|<actor type>\|\|<actor metadata identifier>\|\|reminders\|\|2` | `[ <reminder 1-1>, <reminder 1-2>, ... , <reminder 1-m> ]` |
|
||||
| ... | ... |
|
||||
|
||||
If you need to change the number of partitions, Dapr's sidecar will automatically redistribute the reminders's set.
|
||||
|
||||
### Enabling actor reminders partitioning
|
||||
|
||||
#### Actor runtime configuration for actor reminders partitioning
|
||||
|
||||
Similar to other actor configuration elements, the actor runtime provides the appropriate configuration to partition actor reminders via the actor's endpoint for `GET /dapr/config`.
|
||||
|
||||
{{< tabs Java Dotnet Python Go >}}
|
||||
|
||||
{{% codetab %}}
|
||||
|
||||
```java
|
||||
// import io.dapr.actors.runtime.ActorRuntime;
|
||||
// import java.time.Duration;
|
||||
|
||||
ActorRuntime.getInstance().getConfig().setActorIdleTimeout(Duration.ofMinutes(60));
|
||||
ActorRuntime.getInstance().getConfig().setActorScanInterval(Duration.ofSeconds(30));
|
||||
ActorRuntime.getInstance().getConfig().setRemindersStoragePartitions(7);
|
||||
```
|
||||
|
||||
For more information, see [the Java actors example](https://github.com/dapr/java-sdk/blob/master/examples/src/main/java/io/dapr/examples/actors/DemoActorService.java)
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
|
||||
```csharp
|
||||
// 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.RemindersStoragePartitions = 7;
|
||||
});
|
||||
|
||||
// Register additional services for use with actors
|
||||
services.AddSingleton<BankService>();
|
||||
}
|
||||
```
|
||||
|
||||
See the .NET SDK [documentation for registering actors](https://github.com/dapr/dotnet-sdk/blob/master/daprdocs/content/en/dotnet-sdk-docs/dotnet-actors/dotnet-actors-usage.md#registering-actors).
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
|
||||
```python
|
||||
from datetime import timedelta
|
||||
|
||||
ActorRuntime.set_actor_config(
|
||||
ActorRuntimeConfig(
|
||||
actor_idle_timeout=timedelta(hours=1),
|
||||
actor_scan_interval=timedelta(seconds=30),
|
||||
remindersStoragePartitions=7
|
||||
)
|
||||
)
|
||||
```
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{% codetab %}}
|
||||
|
||||
```go
|
||||
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"`
|
||||
RemindersStoragePartitions int `json:"remindersStoragePartitions,omitempty"`
|
||||
}
|
||||
|
||||
var daprConfigResponse = daprConfig{
|
||||
[]string{defaultActorType},
|
||||
actorIdleTimeout,
|
||||
actorScanInterval,
|
||||
drainOngoingCallTimeout,
|
||||
drainRebalancedActors,
|
||||
7,
|
||||
}
|
||||
|
||||
func configHandler(w http.ResponseWriter, r *http.Request) {
|
||||
w.Header().Set("Content-Type", "application/json")
|
||||
w.WriteHeader(http.StatusOK)
|
||||
json.NewEncoder(w).Encode(daprConfigResponse)
|
||||
}
|
||||
```
|
||||
|
||||
{{% /codetab %}}
|
||||
|
||||
{{< /tabs >}}
|
||||
|
||||
The following is an example of a valid configuration for reminder partitioning:
|
||||
|
||||
```json
|
||||
{
|
||||
"entities": [ "MyActorType", "AnotherActorType" ],
|
||||
"remindersStoragePartitions": 7
|
||||
}
|
||||
```
|
||||
|
||||
#### Handling configuration changes
|
||||
|
||||
To configure actor reminders partitioning, Dapr persists the actor type metadata in the actor's state store. This allows the configuration changes to be applied globally, not just in a single sidecar instance.
|
||||
|
||||
Also, **you can only increase the number of partitions**, not decrease. This allows Dapr to automatically redistribute the data on a rolling restart where one or more partition configurations might be active.
|
||||
|
||||
#### Demo
|
||||
|
||||
Watch [this video for a demo of actor reminder partitioning](https://youtu.be/ZwFOEUYe1WA?t=1493):
|
||||
|
||||
<div class="embed-responsive embed-responsive-16by9">
|
||||
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/ZwFOEUYe1WA?start=1495" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
|
||||
- Refer to the [Dapr SDK documentation and examples]({{< ref "developing-applications/sdks/#sdk-languages" >}}).
|
||||
- [Actors API reference]({{< ref actors_api.md >}})
|
||||
- [Actors overview]({{< ref actors-overview.md >}})
|
||||
|
|
@ -90,7 +90,7 @@ If you are Minikube user or want to disable persistent volume for development pu
|
|||
|
||||
```bash
|
||||
helm install dapr-prom prometheus-community/prometheus -n dapr-monitoring
|
||||
--set alertmanager.persistentVolume.enable=false --set pushgateway.persistentVolume.enabled=false --set server.persistentVolume.enabled=false
|
||||
--set alertmanager.persistence.enabled=false --set pushgateway.persistentVolume.enabled=false --set server.persistentVolume.enabled=false
|
||||
```
|
||||
|
||||
3. Validation
|
||||
|
|
@ -119,4 +119,4 @@ dapr-prom-prometheus-server-694fd8d7c-q5d59 2/2 Running 0
|
|||
## References
|
||||
|
||||
* [Prometheus Installation](https://github.com/prometheus-community/helm-charts)
|
||||
* [Prometheus Query Language](https://prometheus.io/docs/prometheus/latest/querying/basics/)
|
||||
* [Prometheus Query Language](https://prometheus.io/docs/prometheus/latest/querying/basics/)
|
||||
|
|
|
|||
Loading…
Reference in New Issue