From 6c652c31686d92092bdc3fe707ca9bdbbf2a973a Mon Sep 17 00:00:00 2001 From: Ketan Gupta Date: Mon, 10 Mar 2025 12:41:25 +0000 Subject: [PATCH 1/4] Add compat flag docs for FinalizationRegistry and WeakRef --- .../compatibility-flags/js-weak-refs.md | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 src/content/compatibility-flags/js-weak-refs.md diff --git a/src/content/compatibility-flags/js-weak-refs.md b/src/content/compatibility-flags/js-weak-refs.md new file mode 100644 index 00000000000000..eef7c4cb1ab8c2 --- /dev/null +++ b/src/content/compatibility-flags/js-weak-refs.md @@ -0,0 +1,24 @@ +--- +_build: + publishResources: false + render: never + list: never + +name: "Enable `FinalizationRegistry` and `WeakRef`" +sort_date: "2025-05-05" +enable_date: "2025-05-05" +enable_flag: "enable_weak_ref" +disable_flag: "disable_weak_ref" +--- + +Enables the use of [`FinalizationRegistry`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/FinalizationRegistry) and [`WeakRef`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakRef) built-ins. +* `FinalizationRegistry` allows you to register a cleanup callback that runs after an object has been garbage-collected. +* `WeakRef` creates a weak reference to an object, allowing it to be garbage-collected if no other strong references exist. + +:::note[Behaviour] +`FinalizationRegistry` cleanup callbacks may execute at any point during your request lifecycle, even after your invoked handler has completed (similar to `ctx.waitUntil()`). These callbacks do not have an associated async context — you cannot perform any I/O within them, including emitting events to a tail Worker. +::: + +:::caution +These APIs are fundamentally non-deterministic — the timing and execution of garbage collection are unpredictable, and you **should not rely on them for essential program logic**. Additionally, cleanup callbacks registered with `FinalizationRegistry` may **never be executed**, including but not limited to cases where garbage collection is not triggered, or your Worker gets evicted. +::: \ No newline at end of file From bb5f40191a6ca9c4b953d3e46b5fbb290a15b1ec Mon Sep 17 00:00:00 2001 From: Ketan Gupta Date: Thu, 24 Apr 2025 14:19:00 +0100 Subject: [PATCH 2/4] Add changelog entry for FinalizationRegistry --- .../workers/2025-04-24-finalization-registry.mdx | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 src/content/changelog/workers/2025-04-24-finalization-registry.mdx diff --git a/src/content/changelog/workers/2025-04-24-finalization-registry.mdx b/src/content/changelog/workers/2025-04-24-finalization-registry.mdx new file mode 100644 index 00000000000000..c7b297572e117a --- /dev/null +++ b/src/content/changelog/workers/2025-04-24-finalization-registry.mdx @@ -0,0 +1,11 @@ +--- +title: Improved Memory Efficiency for WebAssembly Workers +description: With the introduction of FinalizationRegistry in Workers Runtime, toolchains like Emscripten and wasm-bindgen can automatically reclaim unused WebAssembly heap and reduce memory leaks. +products: + - workers +date: 2025-05-24T00:00:00Z +--- + +[FinalizationRegistry](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/FinalizationRegistry) is now available in Workers (opt-in with the `enable_weak_ref` compat flag), so toolchains such as Emscripten and wasm-bindgen can automatically free WebAssembly heap allocations. + +While this will reduce long-running memory growth and leaks to a certain extent, the API still depends on garbage-collector timing and other non-deterministic factors, so treat it as a helpful mitigation rather than a guaranteed fix. From ca8090576726c144c56a705769a1c5c8f1901fb5 Mon Sep 17 00:00:00 2001 From: Ketan Gupta Date: Tue, 6 May 2025 11:26:44 +0100 Subject: [PATCH 3/4] Address review comments --- .../workers/2025-04-24-finalization-registry.mdx | 11 ----------- .../workers/2025-05-08-finalization-registry.mdx | 13 +++++++++++++ 2 files changed, 13 insertions(+), 11 deletions(-) delete mode 100644 src/content/changelog/workers/2025-04-24-finalization-registry.mdx create mode 100644 src/content/changelog/workers/2025-05-08-finalization-registry.mdx diff --git a/src/content/changelog/workers/2025-04-24-finalization-registry.mdx b/src/content/changelog/workers/2025-04-24-finalization-registry.mdx deleted file mode 100644 index c7b297572e117a..00000000000000 --- a/src/content/changelog/workers/2025-04-24-finalization-registry.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Improved Memory Efficiency for WebAssembly Workers -description: With the introduction of FinalizationRegistry in Workers Runtime, toolchains like Emscripten and wasm-bindgen can automatically reclaim unused WebAssembly heap and reduce memory leaks. -products: - - workers -date: 2025-05-24T00:00:00Z ---- - -[FinalizationRegistry](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/FinalizationRegistry) is now available in Workers (opt-in with the `enable_weak_ref` compat flag), so toolchains such as Emscripten and wasm-bindgen can automatically free WebAssembly heap allocations. - -While this will reduce long-running memory growth and leaks to a certain extent, the API still depends on garbage-collector timing and other non-deterministic factors, so treat it as a helpful mitigation rather than a guaranteed fix. diff --git a/src/content/changelog/workers/2025-05-08-finalization-registry.mdx b/src/content/changelog/workers/2025-05-08-finalization-registry.mdx new file mode 100644 index 00000000000000..57b8b22978cc6e --- /dev/null +++ b/src/content/changelog/workers/2025-05-08-finalization-registry.mdx @@ -0,0 +1,13 @@ +--- +title: Improved Memory Efficiency for WebAssembly Workers +description: With the introduction of FinalizationRegistry in Workers Runtime, toolchains like Emscripten and wasm-bindgen can automatically reclaim unused WebAssembly heap and reduce memory leaks. +products: + - workers +date: 2025-05-08T00:00:00Z +--- + +[FinalizationRegistry](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/FinalizationRegistry) is now available in Workers. You can opt-in using the [`enable_weak_ref`](/workers/configuration/compatibility-flags/#enable-finalizationregistry-and-weakref) compatibility flag. + +This can reduce memory leaks when using WebAssembly-based Workers, which includes [Python Workers](/workers/languages/python/) and [Rust Workers](/workers/languages/rust/). The FinalizationRegistry works by enabling toolchains such as [Emscripten](https://emscripten.org/) and [wasm-bindgen](https://rustwasm.github.io/wasm-bindgen/) to automatically free WebAssembly heap allocations. If you are using WASM and seeing Exceeded Memory errors and cannot determine a cause using [memory profiling](/workers/observability/dev-tools/memory-usage/), you may want to enable the FinalizationRegistry. + +For more information see the [`enable_weak_ref`](/workers/configuration/compatibility-flags/#enable-finalizationregistry-and-weakref) compatibility flag documentation. \ No newline at end of file From b5276c94f5939c7b2a325150a901a188eacc80d8 Mon Sep 17 00:00:00 2001 From: Ketan Gupta Date: Thu, 8 May 2025 12:12:48 +0100 Subject: [PATCH 4/4] Address review comments --- .../workers/2025-05-08-finalization-registry.mdx | 4 ++-- src/content/compatibility-flags/js-weak-refs.md | 8 ++++---- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/src/content/changelog/workers/2025-05-08-finalization-registry.mdx b/src/content/changelog/workers/2025-05-08-finalization-registry.mdx index 57b8b22978cc6e..3563a96c542bd3 100644 --- a/src/content/changelog/workers/2025-05-08-finalization-registry.mdx +++ b/src/content/changelog/workers/2025-05-08-finalization-registry.mdx @@ -1,5 +1,5 @@ --- -title: Improved Memory Efficiency for WebAssembly Workers +title: Improved memory efficiency for WebAssembly Workers description: With the introduction of FinalizationRegistry in Workers Runtime, toolchains like Emscripten and wasm-bindgen can automatically reclaim unused WebAssembly heap and reduce memory leaks. products: - workers @@ -10,4 +10,4 @@ date: 2025-05-08T00:00:00Z This can reduce memory leaks when using WebAssembly-based Workers, which includes [Python Workers](/workers/languages/python/) and [Rust Workers](/workers/languages/rust/). The FinalizationRegistry works by enabling toolchains such as [Emscripten](https://emscripten.org/) and [wasm-bindgen](https://rustwasm.github.io/wasm-bindgen/) to automatically free WebAssembly heap allocations. If you are using WASM and seeing Exceeded Memory errors and cannot determine a cause using [memory profiling](/workers/observability/dev-tools/memory-usage/), you may want to enable the FinalizationRegistry. -For more information see the [`enable_weak_ref`](/workers/configuration/compatibility-flags/#enable-finalizationregistry-and-weakref) compatibility flag documentation. \ No newline at end of file +For more information refer to the [`enable_weak_ref`](/workers/configuration/compatibility-flags/#enable-finalizationregistry-and-weakref) compatibility flag documentation. \ No newline at end of file diff --git a/src/content/compatibility-flags/js-weak-refs.md b/src/content/compatibility-flags/js-weak-refs.md index eef7c4cb1ab8c2..718f8818a545c0 100644 --- a/src/content/compatibility-flags/js-weak-refs.md +++ b/src/content/compatibility-flags/js-weak-refs.md @@ -12,13 +12,13 @@ disable_flag: "disable_weak_ref" --- Enables the use of [`FinalizationRegistry`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/FinalizationRegistry) and [`WeakRef`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakRef) built-ins. -* `FinalizationRegistry` allows you to register a cleanup callback that runs after an object has been garbage-collected. -* `WeakRef` creates a weak reference to an object, allowing it to be garbage-collected if no other strong references exist. +- `FinalizationRegistry` allows you to register a cleanup callback that runs after an object has been garbage-collected. +- `WeakRef` creates a weak reference to an object, allowing it to be garbage-collected if no other strong references exist. :::note[Behaviour] -`FinalizationRegistry` cleanup callbacks may execute at any point during your request lifecycle, even after your invoked handler has completed (similar to `ctx.waitUntil()`). These callbacks do not have an associated async context — you cannot perform any I/O within them, including emitting events to a tail Worker. +`FinalizationRegistry` cleanup callbacks may execute at any point during your request lifecycle, even after your invoked handler has completed (similar to `ctx.waitUntil()`). These callbacks do not have an associated async context. You cannot perform any I/O within them, including emitting events to a tail Worker. ::: :::caution -These APIs are fundamentally non-deterministic — the timing and execution of garbage collection are unpredictable, and you **should not rely on them for essential program logic**. Additionally, cleanup callbacks registered with `FinalizationRegistry` may **never be executed**, including but not limited to cases where garbage collection is not triggered, or your Worker gets evicted. +These APIs are fundamentally non-deterministic. The timing and execution of garbage collection are unpredictable, and you **should not rely on them for essential program logic**. Additionally, cleanup callbacks registered with `FinalizationRegistry` may **never be executed**, including but not limited to cases where garbage collection is not triggered, or your Worker gets evicted. ::: \ No newline at end of file