Skip to content

Commit 1779848

Browse files
committed
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.
1 parent 3e797cb commit 1779848

2 files changed

Lines changed: 9 additions & 1 deletion

File tree

‎doc/api/embedding.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -145,6 +145,13 @@ pool completions of the other `node::Environment`s that become due in those
145145
loop iterations run normally, including their JavaScript; only the
146146
`node::Environment` being freed can no longer call into JavaScript.
147147

148+
Do not call `node::FreeEnvironment()` from a callback of the loop that it
149+
runs. This includes timer and I/O callbacks, and JavaScript code or addon
150+
functions that they run. A libuv loop must not run inside one of its own
151+
callbacks. If you call `node::FreeEnvironment()` from such a callback, it can
152+
wait forever. Call it after the loop stops running, for example after
153+
`node::SpinEventLoop()` returns.
154+
148155
In order to set up a `v8::Isolate`, an `v8::ArrayBuffer::Allocator` needs
149156
to be provided. One possible choice is the default Node.js allocator, which
150157
can be created through `node::ArrayBufferAllocator::Create()`. Using the Node.js

‎src/node.h‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -926,7 +926,8 @@ NODE_EXTERN v8::MaybeLocal<v8::Value> LoadEnvironment(
926926

927927
// Runs `env`'s event loop until its handles have closed, with JavaScript
928928
// execution disallowed for `env`; see doc/api/embedding.md if that loop is
929-
// shared with other Environments.
929+
// shared with other Environments. Do not call this from a callback of that
930+
// loop, because uv_run() is not reentrant.
930931
NODE_EXTERN void FreeEnvironment(Environment* env);
931932

932933
// Set a callback that is called when process.exit() is called from JS,

0 commit comments

Comments
 (0)