Skip to content

Commit 7772336

Browse files
committed
Adding rest of the text for DO lifecycle chapter
1 parent 4fdc745 commit 7772336

File tree

1 file changed

+54
-0
lines changed

1 file changed

+54
-0
lines changed

src/content/docs/durable-objects/concepts/durable-object-lifecycle.mdx

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,3 +19,57 @@ const id = env.MY_DURABLE_OBJECT.idFromName("foo");
1919
const stub = env.MY_DURABLE_OBJECT.get(id);
2020
```
2121

22+
Once we have the Durable Object Stub, we can now invoke methods on the Durable Object. Note that the above two lines does not yet send any request to the remote Durable Object.
23+
24+
The following line invokes the `sayHello()` method of the Durable Object class bound to the `MY_DURABLE_OBJECT` binding:
25+
26+
```ts
27+
// All invoked methods need to be awaited.
28+
const rpcResponse = await stub.sayHello();
29+
```
30+
31+
At this point, the caller sends a request to the Durable Object identified by the stub. The lifecycle of the Durable Object now begins.
32+
33+
## Durable Object Lifecycle state transitions
34+
35+
A Durable Object can be in one of the following states at any moment:
36+
37+
| State | Description |
38+
|-----------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
39+
| Active in-memory | The Durable Object runs, in memory, and handles incoming requests. |
40+
| Idle in-memory non-hibernateable | The Durable Object waits for the next incoming request/event, but does not satisfy the criteria for hibernation. |
41+
| Idle in-memory hibernateable | The Durable Object waits for the next incoming request/event and satisfies the criteria for hibernation. It is up to the runtime to decide when to hibernate the Durable Object. Currently, it is after 10 seconds of inactivity while in this state. |
42+
| Hibernated | The Durable Object is removed from memory. |
43+
| Evicted | The Durable Object is completely removed from the host process. Might need a cold start. |
44+
45+
This is how a Durable Object transitions among these states (each state is in a rounded rectangle).
46+
47+
[PLACEHOLDER FOR IMAGE]
48+
49+
Assuming a Durable Object does not run, the first incoming request or event (like an Alarm) will execute the `constructor()` of the Durable Object class, then run the corresponding function invoked.
50+
51+
At this point the Durable Object is in the **Active in-memory state**.
52+
53+
If it continuously receives requests or events within 10 seconds of each other, the Durable Object will remain in this state.
54+
55+
After 10 seconds of no incoming request or events, the runtime can now hibernate the Durable Object. Hibernation will only occur if **all** of the below are true:
56+
- No `setTimeout`/`setInterval` scheduled callbacks are set.
57+
- No in-progress `fetch()` waiting for a remote request exists.
58+
- No WebSocket standard API is used.
59+
- No request/event is still being processed.
60+
61+
If all conditions are met, the Durable Object will transition into a **hibernated** state.
62+
63+
:::caution
64+
When hibernated, the in-memory state is discarded, so ensure you persist all important information in the Durable Object's storage.
65+
:::
66+
67+
If any of the above conditions are false, the Durable Object remains in-memory, in the **Idle in-memory non-hibernateable** state.
68+
69+
In case of an incoming request or event while in the hibernated state, the `constructor()` will run again, and the corresponding function invoked will run.
70+
71+
Once in hibernated state, or in the idle in-memory non-hibernateable state: after 70-140 seconds of inactivity (no incoming requests or events), the Durable Object will be evicted entirely from memory and potentially from the Cloudflare host.
72+
73+
The next incoming request or event starts the cycle again.
74+
75+
As explained in [When does a Durable Object incur duration charges?](/durable-objects/platform/pricing/#when-does-a-durable-object-incur-duration-charges), a Durable Object incurs charges only when it is **actively running in-memory**, or when it is **idle in-memory and non-hibernateable**, the two states highlighted in red in the above diagram.

0 commit comments

Comments
 (0)