From 7d8413a96b5a1079ff7f7782a17be50de7c93acf Mon Sep 17 00:00:00 2001 From: Matt Silverlock Date: Wed, 2 Apr 2025 09:15:37 -0400 Subject: [PATCH 1/2] durable objects: FURTHER clarify blockConcurrencyWhile --- src/content/docs/durable-objects/api/state.mdx | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/src/content/docs/durable-objects/api/state.mdx b/src/content/docs/durable-objects/api/state.mdx index 89b67e72a5d0d3a..ff266c6521bff4d 100644 --- a/src/content/docs/durable-objects/api/state.mdx +++ b/src/content/docs/durable-objects/api/state.mdx @@ -73,12 +73,21 @@ The request context for a Durable Objects extends at least 60 seconds after the `blockConcurrencyWhile` executes an async callback while blocking any other events from being delivered to the Durable Object until the callback completes. This method guarantees ordering and prevents concurrent requests. All events that were not explicitly initiated as part of the callback itself will be blocked. Once the callback completes, all other events will be delivered. -`blockConcurrencyWhile` is commonly used within the constructor of the Durable Object class to enforce initialization to occur before any requests are delivered. Another use case is executing `async` operations based on the current state of the Durable Object and using `blockConcurrencyWhile` to prevent that state from changing while yielding the event loop. - -If the callback throws an exception, the object will be terminated and reset. This ensures that the object cannot be left stuck in an uninitialized state if something fails unexpectedly. To avoid this behavior, enclose the body of your callback in a `try...catch` block to ensure it cannot throw an exception. +* `blockConcurrencyWhile` is commonly used within the constructor of the Durable Object class to enforce initialization to occur before any requests are delivered. +* Another use case is executing `async` operations based on the current state of the Durable Object and using `blockConcurrencyWhile` to prevent that state from changing while yielding the event loop. +* If the callback throws an exception, the object will be terminated and reset. This ensures that the object cannot be left stuck in an uninitialized state if something fails unexpectedly. +* To avoid this behavior, enclose the body of your callback in a `try...catch` block to ensure it cannot throw an exception. To help mitigate deadlocks there is a 30 second timeout applied when executing the callback. If this timeout is exceeded, the Durable Object will be reset. It is best practice to have the callback do as little work as possible to improve overall request throughput to the Durable Object. +:::note + +You should only need `blockConcurrencyWhile` if you are making additional, asynchronous calls (such as to another API or service) and cannot tolerate those other requests changing the internal state of the Durable Object when the event loop is yielded. + +In practice, this is quite rare, and most use cases do not need `blockConcurrencyWhile`. + +::: + ```js // Durable Object export class MyDurableObject extends DurableObject { From e66d2274cc6701fc8e60c69ab58b585082088244 Mon Sep 17 00:00:00 2001 From: Matt Silverlock Date: Wed, 2 Apr 2025 17:02:45 -0400 Subject: [PATCH 2/2] Update src/content/docs/durable-objects/api/state.mdx Co-authored-by: Lambros Petrou --- src/content/docs/durable-objects/api/state.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/durable-objects/api/state.mdx b/src/content/docs/durable-objects/api/state.mdx index ff266c6521bff4d..02bdfbd15038294 100644 --- a/src/content/docs/durable-objects/api/state.mdx +++ b/src/content/docs/durable-objects/api/state.mdx @@ -82,7 +82,7 @@ To help mitigate deadlocks there is a 30 second timeout applied when executing t :::note -You should only need `blockConcurrencyWhile` if you are making additional, asynchronous calls (such as to another API or service) and cannot tolerate those other requests changing the internal state of the Durable Object when the event loop is yielded. +You should only need `blockConcurrencyWhile` if you are making additional, asynchronous calls (such as to another API or service), and cannot tolerate other requests processed by the Durable Object changing its internal while the event loop is yielded from the original request. In practice, this is quite rare, and most use cases do not need `blockConcurrencyWhile`.