Fix SIGSEGV when a worker_threads Worker that loaded node-api-dotnet …

[GalaxiasKyklos]

Summary

Fixes a SIGSEGV (process crash, exit 139) that occurs on Linux when a worker_threads Worker loads node-api-dotnet and the worker is then terminated.

Issue: #486

Repro

Load the module inside a Worker, then terminate the worker:

// worker.cjs
const { parentPort } = require('node:worker_threads');
require('node-api-dotnet/net10.0');
parentPort.postMessage('ready');

// main.cjs
const { Worker } = require('node:worker_threads');
const w = new Worker('./worker.cjs');
w.once('message', async () => {
  await w.terminate();
  console.log('terminated ok');
});

On Linux the process crashes with SIGSEGV instead of printing terminated ok.

Root cause

The native host (Microsoft.JavaScript.NodeApi.node) is compiled with NativeAOT, so the .node embeds its own .NET runtime. That runtime registers per-thread cleanup with the OS via a pthread_key destructor whose function pointer points into this module's own code.

When a Worker environment is torn down, Node.js unloads the addon (dlclose) while the worker's OS thread is still alive. The pthread_key destructor is still registered, but now points at unmapped memory. When the worker thread subsequently exits, glibc's __nptl_deallocate_tsd invokes that dangling destructor → SIGSEGV.

This was confirmed with gdb: at crash time the faulting destructor belonged to the .node, which had 0 memory mappings (already dlclosed). No-op'ing dlclose via LD_PRELOAD produced a clean exit, confirming the unmap-while-thread-alive diagnosis.

Fix

Pin the native host module for the lifetime of the process on Linux. Resolve the module's own path via dladdr on one of its functions, then re-open it with dlopen(RTLD_NOLOAD | RTLD_NODELETE):

• RTLD_NOLOAD resolves the already-loaded module without loading a second copy.
• RTLD_NODELETE keeps it mapped for the process lifetime, and the extra (never-released) reference prevents Node's dlclose from unmapping it.

This keeps the pthread_key destructor address valid for the life of the process. The change is:

• Scoped to Linux/glibc — Windows module/thread teardown does not hit this path.
• Best-effort — any failure is traced and non-fatal, so it never blocks module init.

Testing

Reproduced and validated in Docker (mcr.microsoft.com/dotnet/sdk:10.0 + Node 24.13.0, which crashes deterministically):

	Before	After
Node 24.13.0	exit 139 (SIGSEGV)	exit 0 (terminated ok), 5/5 runs

NodeApi builds clean on net8.0, net9.0, net10.0, and netstandard2.0.

Note: This addresses only the crash. A separate hang on Node.js >= 24.14 (TSFN release deadlock during env teardown) is fixed independently.

[jasongin]

You mentioned above that Windows does not hit this problem; do you know whether this issue affects Mac OS?

[GalaxiasKyklos]

I've extended the pin to macOS in the latest commit, I could only validate on Linux (Docker repro); the macOS path is best-effort and unvalidated on real hardware. Happy to gate it Linux-only if you'd prefer until it's validated on a Mac.

[jasongin]

PR builds run on macOS, so at least they will validate it's not broken (once the package issues are resolved). But I'd prefer to confirm whether or not this fix is actually needed on that platform. Is there a simple repro? I use macOS as my main dev environment now, so I could easily try it out.

[GalaxiasKyklos]

Thank you! I put together this gist with instructions on how to repro it on macOS

https://gist.github.com/GalaxiasKyklos/8bb730adcd486af5e0067eb2f1c69055

[vmoroz]

Please fix the formatter issues - it says to use the LibraryImportAttribute instead of DllImportAttribute.

[GalaxiasKyklos]

Done, converted the  dladdr / dlopen  imports to source-generated [LibraryImport]  in the latest commit