Repository navigation
doc: note that FreeEnvironment() must not run inside uv_run() - #67660
magurotuna wants to merge 1 commit into
Conversation
|
Welcome to Node.js, and thank you for your first contribution! Before review, please take a moment to read:
Please make sure every commit is signed off. For a first pull request, GitHub Actions require collaborator approval and Jenkins CI must be started by a collaborator or triager, so an initial wait is normal. |
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 <ytanaka@cloudflare.com>
1779848 to
ffbadc2
Compare
|
The recommendations in: advise you should tackle only one issue at a time and that you should not open any new PRs until your first PR has been approved. You already have another unapproved PR #67508 open at this time. Until the first PR has been approved and has landed in the Waiting until the first PR has landed ensures that you as a contributor have experienced the complete process from PR submission to successful landing. After this has been completed, any new PRs or new commits to an existing PR are treated to rules for regular Contributors. GitHub Actions CI workflows are then run automatically without intervention by a team member. |
FreeEnvironment()runs the event loop becauseCleanupHandles()callsuv_run(). libuv states thatuv_run()must not be called from a callback. The embedding docs do not mention this rule forFreeEnvironment(). This PR adds a warning todoc/api/embedding.mdandsrc/node.h. The new paragraph indoc/api/embedding.mdtells embedders to callFreeEnvironment()after the loop stops.Calling
FreeEnvironment()from a loop callback can hang. This repro shows the hang on Linux, macOS, and Windows with Node.js 24, 26, and the 2026-11-19 nightly (CI run). In the repro, twofs.stat()calls finish together: one in the main Environment and one in a second Environment. The libuv loop takes both finished requests at once and then runs their callbacks one by one. The first callback callsFreeEnvironment()on the second Environment.FreeEnvironment()waits for the secondfs.stat()request, but the loop already took that request. The loop can run the second callback only afterFreeEnvironment()returns, so the wait never ends.Question: freeing an Environment from an addon
The updated docs tell embedders to call
FreeEnvironment()after the loop stops. However, addon code usually runs inside a loop callback, for example when JavaScript calls it. How should an addon free an Environment?My workaround in magurotuna/vitest-pool-fastforks#14 makes
uv_run()return early withuv_stop()and frees the Environment in a platform task:SpinEventLoop()runs platform tasks (DrainTasks()) afteruv_run()returns, soFreeTaskruns outsideuv_run(). The full code isfreeLater()in the repro. Itsdeferredmode does not hang on any CI job. Can embedders rely on this order?Refs: #65691
AI disclosure: I used Claude Code to research and to help write the added doc and PR body. I reviewed all of them.