ffi: prevent premature GC of DynamicLibrary

[semimikoh]

Fixes: #63010

Functions created by getFunction() do not hold a strong reference
to the owning DynamicLibrary. V8 may garbage-collect the library
while derived functions are still in use, causing spurious
ERR_FFI_LIBRARY_CLOSED errors in tight loops.

Store a Global<Object> reference to the library in
FFIFunctionInfo so the library remains alive as long as any
derived function exists. The reference is released when the
function is garbage-collected via CleanupFunctionInfo.

Verification

$ # reproduce issue #63010 with the test script from the report
$ out/Release/node --experimental-ffi test_ffi_gc.js

No errors. Script runs to completion.

[nodejs-github-bot]

Review requested:

• @nodejs/ffi

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.64%. Comparing base (8173251) to head (0d47435).
⚠️ Report is 18 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #63024      +/-   ##
==========================================
- Coverage   91.49%   89.64%   -1.85%     
==========================================
  Files         358      708     +350     
  Lines      151574   220415   +68841     
  Branches    23921    42272   +18351     
==========================================
+ Hits       138679   197596   +58917     
- Misses      12619    14675    +2056     
- Partials      276     8144    +7868     

Files with missing lines	Coverage Δ
src/node_ffi.cc	69.84% <100.00%> (ø)
src/node_ffi.h	72.72% <ø> (ø)

... and 471 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.

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/73010/

[mcollina]

lgtm

[semimikoh]

Ready from my side, thanks!

[nodejs-github-bot]

Commit Queue failed

- Loading data for nodejs/node/pull/63024
✔  Done loading data for nodejs/node/pull/63024
----------------------------------- PR info ------------------------------------
Title      ffi: prevent premature GC of DynamicLibrary (#63024)
   ⚠  Could not retrieve the email or name of the PR author's from user's GitHub profile!
Branch     semimikoh:fix/ffi-premature-library-gc -> nodejs:main
Labels     c++, author ready, needs-ci, ffi
Commits    1
 - ffi: prevent premature GC of DynamicLibrary
Committers 1
 - semimikoh <[email protected]>
PR-URL: https://github.com/nodejs/node/pull/63024
Fixes: https://github.com/nodejs/node/issues/63010
Reviewed-By: Paolo Insogna <[email protected]>
Reviewed-By: Anna Henningsen <[email protected]>
Reviewed-By: Matteo Collina <[email protected]>
Reviewed-By: Bryan English <[email protected]>
------------------------------ Generated metadata ------------------------------
PR-URL: https://github.com/nodejs/node/pull/63024
Fixes: https://github.com/nodejs/node/issues/63010
Reviewed-By: Paolo Insogna <[email protected]>
Reviewed-By: Anna Henningsen <[email protected]>
Reviewed-By: Matteo Collina <[email protected]>
Reviewed-By: Bryan English <[email protected]>
--------------------------------------------------------------------------------
   ℹ  This PR was created on Wed, 29 Apr 2026 05:51:17 GMT
   ✔  Approvals: 4
   ✔  - Paolo Insogna (@ShogunPanda) (TSC): https://github.com/nodejs/node/pull/63024#pullrequestreview-4194878077
   ✔  - Anna Henningsen (@addaleax): https://github.com/nodejs/node/pull/63024#pullrequestreview-4197628494
   ✔  - Matteo Collina (@mcollina) (TSC): https://github.com/nodejs/node/pull/63024#pullrequestreview-4197975170
   ✔  - Bryan English (@bengl): https://github.com/nodejs/node/pull/63024#pullrequestreview-4199352943
   ✔  Last GitHub CI successful
   ℹ  Last Full PR CI on 2026-04-29T07:30:26Z: https://ci.nodejs.org/job/node-test-pull-request/73010/
   ⚠  Commits were pushed after the last Full PR CI run:
   ⚠  - ffi: prevent premature GC of DynamicLibrary
- Querying data for job/node-test-pull-request/73010/
✔  Build data downloaded
   ✔  Last Jenkins CI successful
--------------------------------------------------------------------------------
   ✔  Aborted `git node land` session in /home/runner/work/node/node/.ncu

https://github.com/nodejs/node/actions/runs/25205417009

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/73054/

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/73055/

[nodejs-github-bot]

Landed in 9c01018