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
Copy file name to clipboardExpand all lines: src/content/docs/durable-objects/api/alarms.mdx
+46-61Lines changed: 46 additions & 61 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,8 +2,7 @@
2
2
title: Alarms
3
3
pcx_content_type: concept
4
4
sidebar:
5
-
order: 1
6
-
5
+
order: 6
7
6
---
8
7
9
8
import { Type } from"~/components";
@@ -14,18 +13,16 @@ Durable Objects alarms allow you to schedule the Durable Object to be woken up a
14
13
15
14
Notably:
16
15
17
-
* Each Durable Object instance is able to schedule a single alarm at a time by calling `setAlarm()`.
18
-
* Alarms have guaranteed at-least-once execution and are retried automatically when the `alarm()` handler throws.
19
-
* Retries are performed using exponential backoff starting at a two second delay from the first failure with up to six retries allowed.
16
+
- Each Durable Object instance is able to schedule a single alarm at a time by calling `setAlarm()`.
17
+
- Alarms have guaranteed at-least-once execution and are retried automatically when the `alarm()` handler throws.
18
+
- Retries are performed using exponential backoff starting at a 2 second delay from the first failure with up to 6 retries allowed.
20
19
21
20
:::note[How are alarms different from Cron Triggers?]
22
21
23
-
24
22
Alarms are more fine grained than [Cron Triggers](/workers/configuration/cron-triggers/#cron-triggers). A Worker can have up to three Cron Triggers configured at once, but it can have an unlimited amount of Durable Objects, each of which can have an alarm set.
25
23
26
24
Alarms are directly scheduled from within your Durable Object. Cron Triggers, on the other hand, are not programmatic. [Cron Triggers](/workers/configuration/cron-triggers/#cron-triggers) execute based on their schedules, which have to be configured through the Cloudflare dashboard or API.
27
25
28
-
29
26
:::
30
27
31
28
Alarms can be used to build distributed primitives, like queues or batching of work atop Durable Objects. Alarms also provide a mechanism to guarantee that operations within a Durable Object will complete without relying on incoming requests to keep the Durable Object alive. For a complete example, refer to [Use the Alarms API](/durable-objects/examples/alarms-api/).
@@ -34,94 +31,82 @@ Alarms can be used to build distributed primitives, like queues or batching of w
* If there is an alarm set, then return the currently set alarm time in number of milliseconds elapsed since the UNIX epoch. Otherwise, return `null`.
42
-
43
-
36
+
- If there is an alarm set, then return the currently set alarm time as the number of milliseconds elapsed since the UNIX epoch. Otherwise, return `null`.
* Set the time for the alarm to run at in number of milliseconds elapsed since the UNIX epoch.
52
-
53
-
46
+
- Set the time for the alarm to run. Specify the time as the number of milliseconds elapsed since the UNIX epoch.
54
47
55
48
### deleteAlarm
56
49
50
+
-`deleteAlarm()`: <Typetext='void' />
57
51
52
+
- Unset the alarm if there is a currently set alarm.
58
53
59
-
*`deleteAlarm()`: <Typetext='void' />
60
-
61
-
* Unset the alarm if there is a currently set alarm.
62
-
63
-
* Calling `deleteAlarm()` inside the `alarm()` handler may prevent retries on a best-effort basis, but is not guaranteed.
64
-
65
-
54
+
- Calling `deleteAlarm()` inside the `alarm()` handler may prevent retries on a best-effort basis, but is not guaranteed.
66
55
67
56
## Handler methods
68
57
69
58
### alarm
70
59
60
+
-`alarm()`: <Typetext='void' />
71
61
62
+
- Called by the system when a scheduled alarm time is reached.
72
63
73
-
*`alarm()`: <Typetext='void' />
74
-
75
-
* Called by the system when a scheduled alarm time is reached.
76
-
77
-
* The `alarm()` handler has guaranteed at-least-once execution and will be retried upon failure using exponential backoff, starting at two second delays for up to six retries. Retries will be performed if the method fails with an uncaught exception.
78
-
79
-
* This method can be `async`.
80
-
64
+
- The `alarm()` handler has guaranteed at-least-once execution and will be retried upon failure using exponential backoff, starting at 2 second delays for up to 6 retries. Retries will be performed if the method fails with an uncaught exception.
81
65
66
+
- This method can be `async`.
82
67
83
68
## Example
84
69
85
70
This example shows how to both set alarms with the `setAlarm(timestamp)` method and handle alarms with the `alarm()` handler within your Durable Object.
86
71
87
-
* The `alarm()` handler will be called once every time an alarm fires.
88
-
* If an unexpected error terminates the Durable Object, the `alarm()` handler will be re-instantiated on another machine.
89
-
* Following a short delay, the `alarm()` handler will run from the beginning on the other machine.
72
+
- The `alarm()` handler will be called once every time an alarm fires.
73
+
- If an unexpected error terminates the Durable Object, the `alarm()` handler may be re-instantiated on another machine.
74
+
- Following a short delay, the `alarm()` handler will run from the beginning on the other machine.
The `DurableObjectId` interface refers to a new or existing Durable Object instance. This interface is most frequently used by [`DurableObjectNamespace::get`](/durable-objects/api/namespace/#get) to obtain a stub for submitting requests to a Durable Object instance.
13
+
14
+
Note that creating an ID for a Durable Object instance does not create the Durable Object. The Durable Object is created lazily after calling [`DurableObjectNamespace::get`](/durable-objects/api/namespace/#get) to create a [`DurableObjectStub`](/durable-objects/api/stub) from a `DurableObjectId`. This ensures that objects are not constructed until they are actually accessed.
15
+
16
+
:::note[`DurableObjectId`]
17
+
18
+
If you are experiencing an issue with a particular Durable Object instance, you may wish to log the `DurableObjectId` from your Worker and include it in your Cloudflare support request.
19
+
20
+
:::
21
+
22
+
## Methods
23
+
24
+
### `toString`
25
+
26
+
`toString` converts a `DurableObjectId` to a 64 digit hex string. This string is useful for logging purposes or storing the `DurableObjectId` elsewhere, for example, in a session cookie. This string can be used to reconstruct a `DurableObjectId` via `DurableObjectNamespace::idFromString`.
27
+
28
+
```js
29
+
// Create a new unique ID
30
+
constid=env.MY_DURABLE_OBJECT.newUniqueId();
31
+
// Convert the ID to a string to be saved elsewhere, e.g. a session cookie
`equals` is used to compare equality between two instances of `DurableObjectId`.
50
+
51
+
```js
52
+
constid1=env.MY_DURABLE_OBJECT.newUniqueId();
53
+
constid2=env.MY_DURABLE_OBJECT.newUniqueId();
54
+
console.assert(!id1.equals(id2), "Different unique ids should never be equal.");
55
+
```
56
+
57
+
#### Parameters
58
+
59
+
- A required `DurableObjectId` to compare against.
60
+
61
+
#### Return values
62
+
63
+
- A boolean. True if equal and false otherwise.
64
+
65
+
## Properties
66
+
67
+
### `name`
68
+
69
+
`name` is an optional property of a `DurableObjectId`, which returns the name that was used to create the `DurableObjectId` via [`DurableObjectNamespace::idFromName`](/durable-objects/api/namespace/#idfromname). This value is undefined if the `DurableObjectId` was constructed using [`DurableObjectNamespace::newUniqueId`](/durable-objects/api/namespace/#newuniqueid).
![hyperlint-ai[bot]](https://avatars.githubusercontent.com/in/718456?v=4&size=40){kind=avatar}
0 commit comments