From ffbadc23ce07b7993b08e726130247f90f2bdf24 Mon Sep 17 00:00:00 2001 From: "Yusuke \"YT\" Tanaka" Date: Wed, 18 Nov 2026 17:08:58 +0900 Subject: [PATCH] doc: note that FreeEnvironment() must not run inside uv_run() FreeEnvironment() runs the event loop of the Environment. If an embedder calls it from a callback of that loop, uv_run() runs nested, and libuv does not allow that. It can hang: the outer uv_run() can hold thread pool completions that the inner uv_run() never sees. Signed-off-by: Yusuke "YT" Tanaka --- doc/api/embedding.md | 7 +++++++ src/node.h | 3 ++- 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/doc/api/embedding.md b/doc/api/embedding.md index 0441a1ffb4e6..83beac3e896a 100644 --- a/doc/api/embedding.md +++ b/doc/api/embedding.md @@ -145,6 +145,13 @@ pool completions of the other `node::Environment`s that become due in those loop iterations run normally, including their JavaScript; only the `node::Environment` being freed can no longer call into JavaScript. +Do not call `node::FreeEnvironment()` from a callback of the loop that it +runs. This includes timer and I/O callbacks, and JavaScript code or addon +functions that they run. A libuv loop must not run inside one of its own +callbacks. If you call `node::FreeEnvironment()` from such a callback, it can +wait forever. Call it after the loop stops running, for example after +`node::SpinEventLoop()` returns. + In order to set up a `v8::Isolate`, an `v8::ArrayBuffer::Allocator` needs to be provided. One possible choice is the default Node.js allocator, which can be created through `node::ArrayBufferAllocator::Create()`. Using the Node.js diff --git a/src/node.h b/src/node.h index 0130904b1c8f..bbc1c4178ec2 100644 --- a/src/node.h +++ b/src/node.h @@ -926,7 +926,8 @@ NODE_EXTERN v8::MaybeLocal LoadEnvironment( // Runs `env`'s event loop until its handles have closed, with JavaScript // execution disallowed for `env`; see doc/api/embedding.md if that loop is -// shared with other Environments. +// shared with other Environments. Do not call this from a callback of that +// loop, because uv_run() is not reentrant. NODE_EXTERN void FreeEnvironment(Environment* env); // Set a callback that is called when process.exit() is called from JS,