Skip to content

Commit b949c28

Browse files
authored
doc: note that FreeEnvironment() runs a shared event loop
The embedder docs say each Environment has exactly one `uv_loop_t` and that an `IsolateData` can be shared between Environments, and `CreateIsolateData()` takes the loop, so several same-thread Environments naturally end up on one loop. Nothing mentions that `FreeEnvironment()` then runs that loop, with JavaScript disallowed on the isolate, until the freed Environment's handles are gone, so the other Environments' callbacks can fire inside it. Document that, and point at it from `FreeEnvironment()` in node.h. Signed-off-by: Shelley Vohr <shelley.vohr@gmail.com> PR-URL: #65691 Reviewed-By: Filip Skokan <panva.ip@gmail.com>
1 parent ad2d452 commit b949c28

2 files changed

Lines changed: 13 additions & 0 deletions

File tree

‎doc/api/embedding.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,16 @@ to as `node::Environment`. Each `node::Environment` is associated with:
9393
that `node::IsolateData` is shared only among `node::Environment`s that
9494
use the same `v8::Isolate`, Node.js does not perform this check.
9595
96+
`node::Environment`s that share a `node::IsolateData` also share its
97+
`uv_loop_t`. `node::FreeEnvironment()` runs that loop until the handles of the
98+
`node::Environment` being freed have closed, and JavaScript execution is
99+
disallowed on the whole `v8::Isolate` while it does, so pending timers, I/O
100+
callbacks and thread pool completions that belong to other `node::Environment`s
101+
on the same loop can run inside that call without being able to call into
102+
JavaScript. `node::Environment`s that are freed independently of one another
103+
should each use their own `uv_loop_t` and `node::IsolateData`, or the embedder
104+
should make sure the others have no pending work when one of them is freed.
105+
96106
In order to set up a `v8::Isolate`, an `v8::ArrayBuffer::Allocator` needs
97107
to be provided. One possible choice is the default Node.js allocator, which
98108
can be created through `node::ArrayBufferAllocator::Create()`. Using the Node.js

‎src/node.h‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -880,6 +880,9 @@ NODE_EXTERN v8::MaybeLocal<v8::Value> LoadEnvironment(
880880
const ModuleData* entry_point,
881881
EmbedderPreloadCallback preload = nullptr);
882882

883+
// Runs `env`'s event loop until its handles have closed, with JavaScript
884+
// execution disallowed on the isolate; see doc/api/embedding.md if that loop
885+
// is shared with other Environments.
883886
NODE_EXTERN void FreeEnvironment(Environment* env);
884887

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

0 commit comments

Comments
 (0)