You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Workflow:
- Adds docs on retention policy
- Move concurrency docs to a new page.
- Clear up refs to actor state store
CLI:
- Update docs to remove need for --connection-string
- Adds note about purge `--force`.
Reminder:
- Adds reference to overwrite & failure policy
Signed-off-by: joshvanl <me@joshvanl.dev>
Copy file name to clipboardExpand all lines: daprdocs/content/en/concepts/building-blocks-concept.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -31,4 +31,4 @@ Dapr provides the following building blocks:
31
31
| [**Distributed lock**]({{% ref "distributed-lock-api-overview" %}}) | `/v1.0-alpha1/lock` | The distributed lock API enables you to take a lock on a resource so that multiple instances of an application can access the resource without conflicts and provide consistency guarantees.
32
32
| [**Cryptography**]({{% ref "cryptography-overview" %}}) | `/v1.0-alpha1/crypto` | The Cryptography API enables you to perform cryptographic operations, such as encrypting and decrypting messages, without exposing keys to your application.
33
33
| [**Jobs**]({{% ref "jobs-overview" %}}) | `/v1.0-alpha1/jobs` | The Jobs API enables you to schedule and orchestrate jobs. Example scenarios include: <ul><li>Schedule batch processing jobs to run every business day</li><li>Schedule various maintenance scripts to perform clean-ups</li><li>Schedule ETL jobs to run at specific times (hourly, daily) to fetch new data, process it, and update the data warehouse with the latest information.</li></ul>
34
-
| [**Conversation**]({{% ref "conversation-overview" %}}) | `/v1.0-alpha2/conversation` | The Conversation API enables you to supply prompts to converse with different large language models (LLMs) and includes features such as prompt caching and personally identifiable information (PII) obfuscation.
34
+
| [**Conversation**]({{% ref "conversation-overview" %}}) | `/v1.0-alpha2/conversation` | The Conversation API enables you to supply prompts to converse with different large language models (LLMs) and includes features such as prompt caching and personally identifiable information (PII) obfuscation.
Now that you've learned about the [actor building block]({{% ref "actors-overview" %}}) at a high level, let's deep dive into the features and concepts included with actors in Dapr.
11
+
Now that you've learned about the [actor building block]({{% ref "actors-overview" %}}) at a high level, let's deep dive into the features and concepts included with actors in Dapr.
12
12
13
13
## Actor lifetime
14
14
@@ -28,7 +28,7 @@ An actor is automatically activated (causing an actor object to be constructed)
28
28
29
29
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.
30
30
31
-
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.
31
+
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.
Copy file name to clipboardExpand all lines: daprdocs/content/en/developing-applications/building-blocks/actors/actors-timers-reminders.md
+47-13Lines changed: 47 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -14,7 +14,10 @@ The functionality of timers and reminders is very similar. The main difference i
14
14
15
15
This distinction allows users to trade off between light-weight but stateless timers vs. more resource-demanding but stateful reminders.
16
16
17
-
The scheduling configuration of timers and reminders is identical, as summarized below:
17
+
The scheduling configuration of timers and reminders is summarized below:
18
+
19
+
---
20
+
`data` is an optional parameter that contains the data passed to the reminder callback method when invoked
18
21
19
22
---
20
23
`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.
@@ -32,7 +35,6 @@ Supported formats:
32
35
- time.Duration format (Sub-second precision is supported when using duration values), e.g. `2h30m`, `500ms`
33
36
-[ISO 8601 duration](https://en.wikipedia.org/wiki/ISO_8601#Durations) format, e.g. `PT2H30M`, `R5/PT1M30S`
34
37
35
-
Note: Actual trigger resolution may vary by runtime and environment.
36
38
---
37
39
`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.
`overwrite` is an optional boolean parameter that indicates whether to overwrite an existing reminder with the same name.
50
+
If `overwrite` is set to `true`, any existing reminder with the same name will be replaced by the new configuration.
51
+
If `overwrite` is set to `false` or omitted, and a reminder with the same name already exists, the operation will fail with a already exists error.
52
+
Note that overwriting an existing reminder will reset its an error.state, including the number of invocations and the next trigger time, just like creating a new reminder.
53
+
54
+
---
55
+
Only available on **reminders**.
56
+
57
+
`failurePolicy` is an optional parameter that defines the behavior when a reminder invocation fails.
58
+
The supported failure policies are:
59
+
-`drop`: The failed invocation is dropped, and the reminder continues with the next scheduled invocation, as if the failure did not occur.
60
+
-`constant`: The reminder will retry the failed invocation a specified number of times with a fixed interval between each attempt.
61
+
*`interval`: The time interval between each retry attempt. If not specified, the interval becomes "0s", meaning retries is attempted immediately.
62
+
*`maxRetries`: The maximum number of retry attempts. If not specified, the invocation will be retried indefinitely at the specified interval until it succeeds.
63
+
64
+
If no failure policy is specified, the default failure policy of 3 retries with an interval of 1 second will be applied.
65
+
66
+
---
67
+
45
68
The actor runtime validates correctness of the scheduling configuration and returns error on invalid input.
46
69
47
-
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.
70
+
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, whichever occurs first.
48
71
49
72
## Actor timers
50
73
51
-
You can register a callback on actor to be executed based on a timer.
74
+
You can register a callback on the actor to be executed based on a timer.
52
75
53
76
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.
54
77
@@ -108,15 +131,15 @@ Refer [api spec]({{% ref "actors_api#invoke-timer" %}}) for more details.
108
131
109
132
## Actor reminders
110
133
111
-
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.
134
+
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 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 the Dapr [Scheduler service]({{% ref scheduler.md %}}).
112
135
113
136
You can create a persistent reminder for an actor by calling the HTTP/gRPC request to Dapr as shown below, or via Dapr SDK.
The request structure for reminders is identical to those of actors. Please refer to the [actor timers examples]({{% ref "#actor-timers" %}}).
142
+
Unlike timers, reminders support an `overwrite` option that allows you to replace an existing reminder with the same name, as well as a `failurePolicy` option that defines the behavior when a reminder invocation fails.
120
143
121
144
### Retrieve actor reminder
122
145
@@ -134,20 +157,18 @@ You can remove the actor reminder by calling
If an actor reminder is triggered and the app does not return a 2** code to the runtime (for example, because of a connection issue),
138
-
actor reminders will be retried up to three times with a backoff interval of one second between each attempt. There may be
139
-
additional retries attempted in accordance with any optionally applied [actor resiliency policy]({{% ref "override-default-retries" %}}).
160
+
If an actor reminder is triggered and the app does not return a 2** code to the runtime (for example, because of a connection issue), actor reminders will be retried according to its failure policy, which by default is three times with a backoff interval of one second between each attempt.
161
+
There may be additional retries attempted in accordance with any optionally applied [actor resiliency policy]({{% ref "override-default-retries" %}}).
140
162
141
163
Refer [api spec]({{% ref "actors_api#invoke-reminder" %}}) for more details.
142
164
143
165
## Error handling
144
166
145
-
When an actor's method completes successfully, the runtime will continue 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.
146
-
147
-
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.
167
+
When an actor's method completes successfully, the runtime will continue to invoke the method at the specified timer or reminder schedule.
168
+
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.
148
169
149
170
If an invocation of the method fails, the timer is not removed. Timers are only removed when:
150
-
- The sidecar crashes
171
+
- The sidecar terminates
151
172
- The executions run out
152
173
- You delete it explicitly
153
174
@@ -191,6 +212,19 @@ Delete all reminders for a specific actor instance:
Copy file name to clipboardExpand all lines: daprdocs/content/en/developing-applications/building-blocks/actors/howto-actors.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -28,7 +28,7 @@ Alternatively, you can use [Dapr SDKs to use actors]({{% ref "developing-applica
28
28
29
29
You can interact with Dapr via HTTP/gRPC endpoints to save state reliably using the Dapr actor state management capabaility.
30
30
31
-
To use actors, your state store must support multi-item transactions. This means your state store component must implement the `TransactionalStore` interface.
31
+
To use actors, your state store must support multi-item transactions. This means your state store component must implement the `TransactionalStore` interface.
32
32
33
33
[See the list of components that support transactions/actors]({{% ref supported-state-stores %}}). Only a single state store component can be used as the state store for all actors.
34
34
@@ -40,4 +40,4 @@ To use actors, your state store must support multi-item transactions. This means
40
40
41
41
- Refer to the [Dapr SDK documentation and examples]({{% ref "developing-applications/sdks/_index.md#sdk-languages" %}}).
0 commit comments