[syrusakbary]

Problem

The bridge's process-wide recursive mutex g_mu was held across most unofficial_* calls, including the ones that run JavaScript: contextify run_script, module evaluation, microtask checkpoints, structured clone, message serialization (property getters run), GC. While one environment was inside such a call, every other environment blocked at its next bridge call, because LookupEnvState takes the same lock. A host NapiRuntimeControl::terminate_all() blocked on it too, so it could not stop a long script started through one of those entry points. Even without contention, every N-API call paid for that lock.

Change

Bridge (src/napi_bridge_init.cc)

• Thread ownership. An environment belongs to the thread that created it: the V8 provider enters the isolate and keeps persistent scopes on that thread (no v8::Locker). Each thread keeps the set of environments it owns.
  • Ordinary calls check that set without any lock.
  • Calls from other threads, including callback registration and release_env, get napi_invalid_arg instead of touching V8 there.
  • Other threads may only terminate or request an interrupt.
• The global lock. g_mu is a plain std::mutex that guards only the env registry and the process-wide message table. The bridge never enters V8 or calls guest code while holding it. The one exception is a terminate or interrupt request from another thread: it keeps the target registered for the duration of TerminateExecution / RequestInterrupt, which V8 allows from any thread and which run no JavaScript.
• Teardown.
  • A closing flag, set under g_mu when release starts, refuses foreign interrupts.
  • Release runs guest finalizers, and those can run JavaScript, so terminate stays possible. While guest code runs from teardown, a terminate reaches it. After a terminate, no more guest code starts.
  • Callback bindings are freed after the release, not before it. JavaScript run by a finalizer could otherwise call a freed binding; this was already possible on main.
  • Interrupts the engine queued but never ran are freed with the env.
• Pointer reuse. snapi_bridge_unofficial_retain_env / unretain_env keep an env's bridge state allocated while the Rust registry holds its pointer. A stale pointer can then never name a newer env.
• snapi_bridge_dispose() releases only the calling thread's environments. It no longer drops queued messages: a message belongs to its queue and may outlive its source environment.

Rust (src/env.rs, src/ctx.rs)

• An env stays in the application registry, retained, until its release returns. terminate_all() can therefore stop JavaScript its finalizers run.
• An env's heap charge and near-heap-limit tracker are returned only after a release the bridge accepted.
  • NapiEnv's Drop used to free the tracker and return the budget first, although finalizers can run JavaScript that reaches the tracker.
  • A store dropped on another OS thread now gets its release refused and stays charged, with a log line. Before, its isolate leaked uncounted.
• NapiRuntimeHooks documents the thread affinity. A store that created environments must stay on one OS thread for its whole life, which also rules out resuming it on another thread after WASIX deep sleep.

V8 provider (v8/src/)

g_mu also used to serialize provider state that all environments share. Without it:

• Module-wrap maps are now always accessed under g_module_wrap_mu. Some lookups and the cleanup-hook set were not locked. Before this fix, the module churn test below crashed in EnsureModuleWrapCleanupHook (1 of 5 runs).
• Isolate construction and V8 disposal are serialized. EdgeV8Platform keys per-isolate state by address and relies on an address not being reused between Dispose() and unregistration. I did not reproduce a failure from this one alone.
• Lock order. Applying promise hooks to contextify contexts held g_context_mu while taking g_runtime_mu; the prepare-stack-trace path takes them in the opposite order. It now copies the contexts out first. This path only compiles with V8_ENABLE_JAVASCRIPT_PROMISE_HOOKS, which neither build defines, so no test reaches it.
• pkeys. unofficial_napi_create_env calls v8::ThreadIsolatedAllocator::SetDefaultPermissionsForSignalHandler() before building the isolate, the same call fix(napi): isolate bridge environments and contain guest callback exits #93 makes. A thread that predates V8's JIT protection key (Linux x64 pkeys) otherwise lacks read access to that memory. I could not exercise this locally (Apple silicon has no pkeys).

Performance

bridge_call_throughput is an ignored test in tests/concurrent_envs.rs. It calls napi_get_value_int32 through the bridge with one env per thread, all threads calling at once. This crate was built at opt-level 3.

ns per call	1 thread	2 threads	4 threads
main	13.9	57.7	165.7
this PR	6.0	6.1	7.4

Tests

tests/concurrent_envs.rs runs a small WAT guest (tests/wat_guest/mod.rs): one Wasmer store per guest, one OS thread per environment. It goes through the real import dispatch, the C++ bridge and V8, and needs no WASIX C toolchain.

Test	Without this PR
a_contextified_script_does_not_block_other_envs: one env waits in Atomics.wait inside contextify_run_script; another env, on another thread, runs scripts and wakes it	fails on main: the second env cannot run until the wait times out
a_module_evaluation_does_not_block_other_envs: the same, inside module_wrap_evaluate	fails on main
a_microtask_checkpoint_does_not_block_other_envs: the same, inside a microtask that event_loop_checkpoint drains	fails on main
a_serializer_getter_does_not_block_other_envs: the same, inside a getter that message_create runs	fails on main
host_terminate_reaches_an_env_inside_a_contextified_script	fails on main: terminate_all() blocks
foreign_threads_may_only_terminate_an_env: through the bridge's C ABI	fails on main: the foreign get_global succeeds
host_terminate_reaches_javascript_a_finalizer_runs_during_release	fails without the teardown commit
an_env_whose_store_is_dropped_on_another_thread_stays_charged	fails without the teardown commit
a_message_has_exactly_one_consumer	passes (guards the narrower lock)
envs_on_several_threads_come_and_go_while_loading_modules: 4 threads × 25 envs, bounded	passes on main, where everything is serialized; crashed without the module-wrap fix

A new workflow, napi-native-concurrency.yml, runs the suite on ubuntu-24.04 when relevant paths change. It follows the native job in #93. I could not run it; drop it or fold it into another job if you prefer.

Local results (macOS arm64, Rust 1.96.1, V8 11.9.9 prebuilt):

• concurrent_envs: 10/10, plus 20/20 repeated runs of the whole binary.
• v8_host_control: 3/3.
• Lib tests: 46/46.
• Native V8 gtest runners (make test-napi): 97/97.
• Manifest programs: all 36, natively and as WASIX.
• Host-JS node test: 14/14.
• snapi_js wasm-bindgen tests: 6/6.
• cargo fmt is clean. Native clippy shows only the existing CLI test-module warning, and host-JS wasm32 clippy output is unchanged.

Behavior changes

• Calls from a thread other than an environment's creator now fail, apart from terminate and interrupt.
• A store dropped on another thread no longer releases its environments: they leak and stay charged to the budget, and the refusal is logged. With the CLI runner, a temporary probe across v8_host_control saw no refused release.
• Isolate construction and V8 disposal are serialized in the provider. Execution, GC and env teardown are not.
• snapi_bridge_dispose() no longer drops queued messages. Nothing in this crate calls it.

Known follow-up (not changed here)

Message ids (g_message_handles) are process-wide, sequential and carry no owner check. Any guest that guesses an id can take or drop another application's message. This is already the case on main.

Relation to #93

#93 also removes the process-wide lock from JavaScript execution, as part of a larger change. Both approaches are valid; which fits better is the maintainers' call.

• Locking model. fix(napi): isolate bridge environments and contain guest callback exits #93 keeps g_mu (recursive) for the registry and isolate construction, and adds a per-environment recursive mutex that every bridge call takes.

  • In fix(napi): isolate bridge environments and contain guest callback exits #93, any thread may enter any environment, one at a time. Terminate has a separate lock-free path, but request_interrupt takes the per-environment lock, so an interrupt from another thread waits for the target's current call to return.
  • This PR binds each environment to its creating thread, so ordinary calls take no lock at all.

• What fix(napi): isolate bridge environments and contain guest callback exits #93 adds beyond concurrency. It converts guest napi_fatal_error to a WASIX exit, propagates guest exits from callback-capable Node-API calls, adds an external-buffer ownership observer in the V8 provider to avoid a double free, and rejects release_env from inside the environment's own callback. This PR does none of that; those fixes are independent of the locking change.

• Shared provider state. fix(napi): isolate bridge environments and contain guest callback exits #93 changes neither the module-wrap locking, nor isolate disposal, nor the lock order. Those fixes apply to it as well.

• Size. fix(napi): isolate bridge environments and contain guest callback exits #93 is 19 files, +3901/−2118 against eac0a13. Of that, src/napi_bridge_init.cc is +2717/−1826, much of it reformatting, and fix(napi): isolate bridge environments and contain guest callback exits #93 is the first of a nine-PR stack. This PR is 10 files, +1303/−176 against 8deda28:

  Area	Lines
  bridge	+216/−129
  provider	+70/−27
  Rust	+77/−20
  tests	+861
  CI	+79

• Not in fix(napi): isolate bridge environments and contain guest callback exits #93. Cross-store terminate is in Allocate env ids per application and let stores terminate each other's envs #108, stacked on this one.

The branch is based on 8deda28. main has since gained #103 and #104; git merge-tree shows both branches merge cleanly.

🤖 Generated with Claude Code