Skip to content

Run deferred V8 Node-API finalizers on a dispatched task - #2056

Open
bghgary wants to merge 4 commits into
BabylonJS:masterfrom
bghgary:v8-napi-finalizer-scheduling
Open

bghgary wants to merge 4 commits into
BabylonJS:masterfrom
bghgary:v8-napi-finalizer-scheduling

Conversation

@bghgary

@bghgary bghgary commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

[Created by Copilot on behalf of @bghgary]

Supersedes #2004.

In V8 builds, garbage collection queues Node-API finalizers, but they do not run until Napi::Detach. Native objects behind collected Napi::ObjectWrap and Napi::External values therefore stay alive until the runtime shuts down.

Like Node.js, finalizers are scheduled on demand rather than checked after every dispatcher turn as in #2004.

Garbage collection only queues Node-API finalizers in the V8 environment, and the base napi_env__ runs that queue at Detach, so native memory owned by collected objects is not released until shutdown. Node.js avoids this in node_napi_env__ by scheduling one drain with SetImmediate when a finalizer is queued and no drain is pending. Do the same here: Napi::Attach takes an optional postTask, and AppRuntime passes one that dispatches the drain onto the JavaScript thread.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot AI balanced review requested due to automatic review settings November 9, 2026 23:34

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues are recorded for the change enabling deferred V8 finalizers to run before shutdown.

No open issues 🎉

What changed in this PR

This PR runs deferred V8 Node-API finalizers during normal runtime operation, allowing collected native objects to be released before shutdown. It replaces the per-dispatch polling approach from #2004 with an on-demand drain task.

Changes:

  • Adds an optional task scheduler to Napi::Attach, preserving shutdown-only finalization for callers without one.
  • Connects finalizer draining to AppRuntime::Dispatch.
  • Adds a V8 regression test verifying that collected externals finalize before shutdown.
File Description
Dependencies/​JsRuntimeHost/​Tests/​UnitTests/​Source/​Tests.NodeApi.V8.cpp Tests finalization of 32 collected externals before shutdown.
Dependencies/​JsRuntimeHost/​Tests/​UnitTests/​CMakeLists.txt Includes the new test in V8 builds.
Dependencies/​JsRuntimeHost/​Core/​Node-API/​Source/​env_v8.cc Schedules queue draining and drains remaining finalizers during teardown.
Dependencies/​JsRuntimeHost/​Core/​Node-API/​Include/​Engine/​V8/​napi/​env.h Declares the optional scheduler and documents its execution contract.
Dependencies/​JsRuntimeHost/​Core/​AppRuntime/​Source/​AppRuntime_V8.cpp Routes finalizer tasks through the runtime dispatcher.

Review effort: Balanced

bghgary and others added 2 commits November 10, 2026 08:35
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Schedule AppRuntime finalizers through a private V8 environment so standalone
callers retain the original Attach signature and shutdown behavior.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants