Skip to content

doc: note that FreeEnvironment() runs a shared event loop - #65691

Open
codebytere wants to merge 1 commit into
nodejs:mainfrom
codebytere:doc-embedding-shared-loop
Open

doc: note that FreeEnvironment() runs a shared event loop#65691
codebytere wants to merge 1 commit into
nodejs:mainfrom
codebytere:doc-embedding-shared-loop

Conversation

@codebytere

Copy link
Copy Markdown
Member

embedding.md says each node::Environment has exactly one uv_loop_t and that a node::IsolateData can be shared between Environments, and CreateIsolateData() takes the loop, so several same-thread Environments end up sharing one. What it doesn't say is that FreeEnvironment() runs that loop until the freed Environment's handles have closed, with JavaScript disallowed on the whole isolate while it does, so timers, I/O callbacks and thread pool completions belonging to the other Environments can fire inside that call and can't call into JS.

This adds a paragraph to embedding.md describing that and the two ways to stay clear of it (a loop and IsolateData per independently freed Environment, or no pending work on the siblings when one is freed), plus a pointer on FreeEnvironment() in node.h. Docs only.


Disclosure: this change and description were written by Claude Code, directed and reviewed by @codebytere.

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>
@nodejs-github-bot nodejs-github-bot added c++ Issues and PRs that require attention from people who are familiar with C++. needs-ci PRs that need a full CI run. labels Sep 1, 2026
@nodejs-github-bot

Copy link
Copy Markdown
Collaborator

@codecov

codecov Bot commented Sep 1, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.05%. Comparing base (705646f) to head (497cd51).
⚠️ Report is 7 commits behind head on main.

Additional details and impacted files
@@            Coverage Diff             @@
##             main   #65691      +/-   ##
==========================================
- Coverage   90.07%   90.05%   -0.02%     
==========================================
  Files         754      754              
  Lines      256395   256395              
  Branches    48499    48507       +8     
==========================================
- Hits       230937   230898      -39     
- Misses      16569    16620      +51     
+ Partials     8889     8877      -12     
Files with missing lines Coverage Δ
src/node.h 92.45% <ø> (ø)

... and 31 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

c++ Issues and PRs that require attention from people who are familiar with C++. needs-ci PRs that need a full CI run.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants