Skip to content

Commit 1689be9

Browse files
syrusakbaryclaude
andcommitted
Merge refactor-agent-realm-phase0 into refactor-agent-realm-phase1
Brings in #121, #122 and #107 through Phase 0. Bridge: realm env states follow #107's rules. create_realm and get_realm no longer hold g_mu across the provider call; AddRealmEnvState registers the state in g_envs under the lock and adopts it on the agent's thread, like NewAgentWithPrincipalEnv. Teardown marks the agent closing first, then releases agent-wide resources through the principal env. V8 contextify: GetModuleWrapState takes g_module_wrap_mu, next to Phase 1's agent-wide module lookups, which take it themselves. Promise hooks for contextify contexts are collected under g_context_mu and applied after releasing it, each with its realm env's hooks. host-JS: buffer finalizer registration borrows the HostJsAgent behind SharedAgent once, so its fields can be used together. The design doc notes that realm env states belong to their agent's thread. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2 parents e23b3b1 + e4812bc commit 1689be9

17 files changed

Lines changed: 2155 additions & 249 deletions
Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
name: napi-native-concurrency
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
paths:
8+
- ".github/workflows/napi-native-concurrency.yml"
9+
- "Cargo.standalone.lock"
10+
- "Cargo.standalone.toml"
11+
- "build.rs"
12+
- "cargo-standalone.sh"
13+
- "include/**"
14+
- "lib/**"
15+
- "rust-toolchain.toml"
16+
- "src/**"
17+
- "tests/concurrent_*.rs"
18+
- "tests/wat_guest/**"
19+
- "v8/**"
20+
pull_request:
21+
paths:
22+
- ".github/workflows/napi-native-concurrency.yml"
23+
- "Cargo.standalone.lock"
24+
- "Cargo.standalone.toml"
25+
- "build.rs"
26+
- "cargo-standalone.sh"
27+
- "include/**"
28+
- "lib/**"
29+
- "rust-toolchain.toml"
30+
- "src/**"
31+
- "tests/concurrent_*.rs"
32+
- "tests/wat_guest/**"
33+
- "v8/**"
34+
workflow_dispatch:
35+
36+
permissions:
37+
contents: read
38+
39+
jobs:
40+
rust-native-concurrency:
41+
name: Rust native concurrency
42+
runs-on: ubuntu-24.04
43+
timeout-minutes: 45
44+
env:
45+
CC: clang
46+
CXX: clang++
47+
CARGO_TARGET_DIR: ${{ github.workspace }}/target
48+
CARGO_INCREMENTAL: "0"
49+
CARGO_PROFILE_TEST_DEBUG: "0"
50+
NAPI_WASMER_FORCE_STANDALONE: "1"
51+
RUST_BACKTRACE: "1"
52+
steps:
53+
- uses: actions/checkout@v4
54+
55+
- name: Install Rust
56+
uses: dtolnay/rust-toolchain@master
57+
with:
58+
toolchain: "1.96"
59+
60+
- name: Install native build dependencies
61+
run: |
62+
sudo apt-get update
63+
sudo apt-get install --yes clang pkg-config libssl-dev
64+
65+
- name: Cache Rust dependencies and the V8 archive
66+
uses: actions/cache@v4
67+
with:
68+
path: |
69+
~/.cargo/registry
70+
~/.cargo/git
71+
target
72+
key: ${{ runner.os }}-napi-concurrency-rust-1.96-${{ hashFiles('Cargo.standalone.toml', 'Cargo.standalone.lock', 'build.rs', 'rust-toolchain.toml') }}
73+
restore-keys: |
74+
${{ runner.os }}-napi-concurrency-rust-1.96-
75+
76+
# WAT guests, each in its own Wasmer store and thread, against the real
77+
# C++ bridge and V8. No WASIX C toolchain is needed.
78+
- name: Test concurrent environments
79+
run: ./cargo-standalone.sh test --locked --test concurrent_envs

‎docs/realm-bound-env.md‎

Lines changed: 13 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -437,9 +437,10 @@ realm can still be reachable.
437437
- **Guest value ids become agent-scoped**, so they stay valid across that
438438
agent's realms.
439439
- **`g_envs` validation** maps env → agent.
440-
- **Lock scope (side benefit).** With an agent object it is natural to replace
441-
the process-global `g_mu`, taken on every `unofficial_*` call, with a
442-
per-agent lock.
440+
- **Lock scope.** #107 already narrowed the process-global `g_mu`: it guards
441+
only the env registry, teardown and interrupt bookkeeping, and the message
442+
table. No call into the engine or guest holds it, except a terminate or
443+
interrupt from another thread.
443444
444445
### Rust (`src/env.rs`, `src/guest/napi.rs`)
445446
@@ -523,7 +524,8 @@ Every phase leaves the tests passing on V8, QuickJS and host-JS.
523524
| Branch | Recommendation |
524525
|---|---|
525526
| `feat/contextify-enter-leave` | Superseded: "one realm per document or frame" becomes `create_realm` plus that env. Its commits are a list of the costs of a selectable context, which this design avoids: root vs selected context, the microtask queue split, finalizers and interrupts running in the wrong realm, the handle leak, and callback cost going from 5.9 to 11 ns. |
526-
| `feat/concurrent-stores`, `perf/concurrent-envs` | Land first. "Ids never reused" and "scope id = env id" become "agent id = principal env id". Terminate and interrupt then target the agent. |
527+
| `perf/concurrent-envs` | Landed as #107 and merged into this branch. Its teardown and interrupt state is per agent (§11). |
528+
| `feat/concurrent-stores` | Land first. "Ids never reused" and "scope id = env id" become "agent id = principal env id". Terminate and interrupt then target the agent. |
527529
| `fix/contextify-weak-records`, `fix/quickjs-contextify-collect` | Land first. Their lifetime model is the realm-env lifetime in §4.5. |
528530
| `feat/trusted-script` | No conflict. Its hook is installed once per isolate, which is agent-level. |
529531
@@ -603,7 +605,10 @@ is the QuickJS trampoline.
603605
callback registry and bindings.
604606
- **Scope frames remember the env that opened them.**
605607
- **The value cap counts across the agent's envs.**
606-
- **Unchanged:** `g_mu` and `g_envs`.
608+
- **Threads and teardown (from #107):** `g_envs`, each thread's set of owned
609+
envs and the `holders` count stay per env. The teardown state is per agent,
610+
because releasing an env tears down its agent: `closing`, `stop_requested`,
611+
`teardown_guest_calls` and pending interrupt requests.
607612
608613
### host-JS (`src/snapi_js.rs`)
609614
@@ -702,7 +707,9 @@ The old context arguments still work: they resolve to the realm env.
702707
703708
**Bridge and Rust**
704709
- **Bridge:** each realm env gets a `SnapiEnvState` on its agent. Realms made
705-
by `make_context` are adopted the first time `get_realm` returns them.
710+
by `make_context` are adopted the first time `get_realm` returns them. Like
711+
the principal env, a realm env state belongs to the agent's thread and is
712+
registered without holding `g_mu` across the provider call (#107).
706713
- **Rust:** realm envs get guest ids with no owner scope, budget charge or
707714
registry entry. Their ids stop resolving when their principal env is
708715
released.

‎src/ctx.rs‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,17 @@ pub struct NapiInstantiationState {
6161
}
6262

6363
/// Runtime hooks that provide N-API imports for WASIX guests.
64+
///
65+
/// An N-API environment belongs to the OS thread that created it. Guests on
66+
/// different threads run concurrently, but other threads can only terminate
67+
/// an environment or request an interrupt; any other call from them, including
68+
/// release, is refused.
69+
///
70+
/// A store that created environments must therefore stay on one OS thread for
71+
/// its whole life, and be dropped there. That rules out resuming it on another
72+
/// thread, for example a WASIX thread woken from deep sleep on a different
73+
/// worker. An environment whose store is dropped on another thread is not
74+
/// released: its isolate leaks and stays charged to the budget.
6475
// The import phase creates a per-instantiation session holding the function
6576
// env backing the imported host functions, and hands it to the caller as
6677
// opaque state. The hooks themselves are stateless, so concurrent

‎src/env.rs‎

Lines changed: 67 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,13 @@ use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
66
#[cfg(all(target_arch = "wasm32", feature = "js"))]
77
use std::sync::atomic::{AtomicU32, Ordering as AtomicOrdering};
88

9+
#[cfg(not(all(target_arch = "wasm32", feature = "js")))]
10+
use crate::guest::callback_cache::CachedGuestCallback;
11+
#[cfg(all(target_arch = "wasm32", feature = "js"))]
12+
use wasmer::Function;
913
#[cfg(all(target_arch = "wasm32", feature = "js"))]
1014
use wasmer::TypedFunction;
11-
use wasmer::{Function, Memory, Table};
15+
use wasmer::{Memory, Table};
1216

1317
use crate::budget::{
1418
EnvHeapCharge, EnvRejected, HeapReservation, Pool, RequestedHeap, ResourceBudget,
@@ -20,6 +24,11 @@ use crate::snapi::{
2024
snapi_bridge_unofficial_set_value_limit,
2125
};
2226

27+
/// The status the bridge returns when it refuses to release an env: a call
28+
/// from a thread other than the env's owner, or a release already under way.
29+
/// Any other status means the env was torn down.
30+
pub(crate) const RELEASE_REFUSED: i32 = 1;
31+
2332
#[cfg(all(target_arch = "wasm32", feature = "js"))]
2433
use crate::{guest::callback::CallbackInvocationCtx, snapi::snapi_bridge_swap_active_callback_ctx};
2534

@@ -128,7 +137,10 @@ pub(crate) struct NapiEnv {
128137
/// memory unboundedly. `Function` clones are cheap (a store handle), so
129138
/// caching by table index and cloning on repeat hits avoids the
130139
/// unconditional store growth. See `guest::callback::call_guest_callback`.
140+
#[cfg(all(target_arch = "wasm32", feature = "js"))]
131141
pub(crate) func_cache: HashMap<u32, Function>,
142+
#[cfg(not(all(target_arch = "wasm32", feature = "js")))]
143+
pub(crate) func_cache: HashMap<u32, CachedGuestCallback>,
132144
pub(crate) default_napi_env_id: Option<u32>,
133145
pub(crate) next_napi_env_id: u32,
134146
pub(crate) next_napi_scope_id: u32,
@@ -285,6 +297,13 @@ impl NapiEnv {
285297
.lock()
286298
.expect("poisoned N-API env registry");
287299
registry.insert(env as usize);
300+
// The registry hands this pointer to other threads; keep it from
301+
// being reused for another env until it leaves the registry.
302+
#[cfg(not(all(target_arch = "wasm32", feature = "js")))]
303+
// SAFETY: `env` is the isolate just created and is still live.
304+
unsafe {
305+
crate::snapi::snapi_bridge_unofficial_retain_env(env);
306+
}
288307

289308
// If the host already stopped this app's JS, an isolate created
290309
// afterwards must not start running either. Checking under the
@@ -496,13 +515,9 @@ impl NapiEnv {
496515
self.default_napi_env_id = None;
497516
}
498517
let env = *self.napi_envs.get(&env_id)?;
499-
// Remove from the shared registry before any env- or isolate-owned
500-
// state is reclaimed. This synchronizes against terminate_all, which
501-
// holds the same mutex while calling into V8.
502-
self.env_registry
503-
.lock()
504-
.expect("poisoned N-API env registry")
505-
.remove(&env);
518+
// The env stays in the shared registry until its release returns, so
519+
// `NapiRuntimeControl::terminate_all` can still stop JavaScript that
520+
// its finalizers run during the release.
506521

507522
// Leases are environment-owned resources. Explicit release publishes
508523
// writes; environment teardown only discards snapshots and returns any
@@ -515,16 +530,41 @@ impl NapiEnv {
515530
Some((env_id, env as SnapiEnv))
516531
}
517532

518-
pub(crate) fn finish_unregister_napi_env(&mut self, env_id: u32, env: SnapiEnv) {
533+
/// Completes unregistration once the bridge release returned `status`.
534+
///
535+
/// If the bridge refused the release ([`RELEASE_REFUSED`]: the caller is
536+
/// not the env's owner thread, or a release is already under way), the
537+
/// isolate still exists. Its heap charge, isolate slot and near-heap-limit
538+
/// tracker are then kept, so the budget stays honest and the callback never
539+
/// sees freed memory; an outer release in progress finishes the job.
540+
pub(crate) fn finish_unregister_napi_env(&mut self, env_id: u32, env: SnapiEnv, status: i32) {
541+
if status == RELEASE_REFUSED {
542+
eprintln!(
543+
"[napi] N-API environment {env_id} was not released (wrong thread or \
544+
already releasing); its isolate and budget charge are kept"
545+
);
546+
return;
547+
}
548+
let registered = self
549+
.env_registry
550+
.lock()
551+
.expect("poisoned N-API env registry")
552+
.remove(&(env as usize));
553+
#[cfg(not(all(target_arch = "wasm32", feature = "js")))]
554+
if registered {
555+
// SAFETY: retained in `commit_isolate`; no longer reachable through
556+
// the registry.
557+
unsafe { crate::snapi::snapi_bridge_unofficial_unretain_env(env) };
558+
}
559+
#[cfg(all(target_arch = "wasm32", feature = "js"))]
560+
let _ = registered;
519561
// Release the heap ceiling + any callback-granted growth + isolate slot
520562
// this env reserved.
521563
if let Some(handle) = self.env_heap_charges.remove(&env_id) {
522564
let granted = if handle.tracker != 0 {
523-
// SAFETY: reclaim the box created in `commit_isolate`. The
524-
// near-heap-limit callback holding this pointer only runs during
525-
// JS execution, and no JS runs between here and the paired env
526-
// release that removes the callback and disposes the isolate, so
527-
// freeing it now is safe.
565+
// SAFETY: reclaim the box created in `commit_isolate`. The env's
566+
// release has returned: its isolate, and with it the
567+
// near-heap-limit callback holding this pointer, are gone.
528568
let boxed = unsafe { Box::from_raw(handle.tracker as *mut EnvHeapCharge) };
529569
boxed.granted.load(Ordering::Acquire)
530570
} else {
@@ -551,9 +591,12 @@ impl NapiEnv {
551591
}
552592
}
553593

594+
/// Unregisters an env whose release does not depend on this bookkeeping
595+
/// (the host-JS backend releases it right after).
596+
#[cfg(all(target_arch = "wasm32", feature = "js"))]
554597
pub(crate) fn unregister_napi_scope(&mut self, scope_id: u32) -> Option<SnapiEnv> {
555598
let (env_id, env) = self.begin_unregister_napi_scope(scope_id)?;
556-
self.finish_unregister_napi_env(env_id, env);
599+
self.finish_unregister_napi_env(env_id, env, 0);
557600
Some(env)
558601
}
559602

@@ -594,11 +637,15 @@ impl Drop for NapiEnv {
594637
fn drop(&mut self) {
595638
let scope_ids: Vec<u32> = self.napi_scopes.keys().copied().collect();
596639
for scope_id in scope_ids {
597-
if let Some(env) = self.unregister_napi_scope(scope_id) {
598-
unsafe {
599-
let _ = snapi_bridge_unofficial_release_env(env);
600-
}
601-
}
640+
let Some((env_id, env)) = self.begin_unregister_napi_scope(scope_id) else {
641+
continue;
642+
};
643+
// Release before returning the env's budget: finalizers can run
644+
// JavaScript, which may still reach its near-heap-limit tracker. A
645+
// store dropped on a thread other than the env's owner gets the
646+
// release refused, and the env stays charged.
647+
let status = unsafe { snapi_bridge_unofficial_release_env(env) };
648+
self.finish_unregister_napi_env(env_id, env, status);
602649
}
603650
// Release any external memory the guest declared but did not take back.
604651
if self.external_declared > 0 {

‎src/guest/callback.rs‎

Lines changed: 11 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ use wasmer::{AsStoreMut, FunctionEnv, FunctionEnvMut, Store, StoreMut, Table, Va
44
use wasmer_wasix::WasiError;
55
use wasmer_wasix::wasmer_wasix_types::wasi::ExitCode;
66

7+
use super::callback_cache::CachedGuestCallback;
78
use crate::{NapiEnv, snapi::SnapiEnv};
89

910
thread_local! {
@@ -78,25 +79,16 @@ fn call_guest_callback(
7879
Value::FuncRef(None) => return 0,
7980
_ => return 0,
8081
};
82+
let callback = CachedGuestCallback::new(func, store);
8183
func_env
8284
.as_mut(store)
8385
.func_cache
84-
.insert(wasm_fn_ptr, func.clone());
85-
func
86+
.insert(wasm_fn_ptr, callback.clone());
87+
callback
8688
}
8789
};
88-
match func.call(
89-
store,
90-
&[
91-
Value::I32(guest_env as i32),
92-
Value::I32(callback_arg as i32),
93-
],
94-
) {
95-
Ok(ret_vals) => match ret_vals.first() {
96-
Some(Value::I32(v)) => *v as u32,
97-
Some(Value::I64(v)) => *v as u32,
98-
_ => 0,
99-
},
90+
match func.call(store, guest_env, callback_arg) {
91+
Ok(result) => result,
10092
Err(err) => {
10193
if stash_guest_exit(&err) {
10294
return 0;
@@ -130,26 +122,16 @@ fn call_guest_callback2(
130122
Value::FuncRef(None) => return 0,
131123
_ => return 0,
132124
};
125+
let callback = CachedGuestCallback::new(func, store);
133126
func_env
134127
.as_mut(store)
135128
.func_cache
136-
.insert(wasm_fn_ptr, func.clone());
137-
func
129+
.insert(wasm_fn_ptr, callback.clone());
130+
callback
138131
}
139132
};
140-
match func.call(
141-
store,
142-
&[
143-
Value::I32(guest_env as i32),
144-
Value::I32(arg0 as i32),
145-
Value::I32(arg1 as i32),
146-
],
147-
) {
148-
Ok(ret_vals) => match ret_vals.first() {
149-
Some(Value::I32(v)) => *v as u32,
150-
Some(Value::I64(v)) => *v as u32,
151-
_ => 0,
152-
},
133+
match func.call_finalizer(store, guest_env, arg0, arg1) {
134+
Ok(result) => result,
153135
Err(err) => {
154136
if stash_guest_exit(&err) {
155137
return 0;

0 commit comments

Comments
 (0)