Repository navigation
Wake the host when V8 queues a task only a checkpoint runs - #139
Merged
Merged
Conversation
With no foreground task target bound, EdgeV8Platform puts V8's foreground tasks in the default platform's queue, which only the guest's next event-loop checkpoint runs (PumpPendingForegroundTasks). Guests running through wasmer_napi never bind a target. V8 posts such tasks from any thread: to resolve an Atomics.waitAsync that another thread's Atomics.notify woke, to finish a WebAssembly.compile, to run FinalizationRegistry callbacks. Nothing told a guest waiting for host events that one was due, so the task ran only once something unrelated woke the guest. A host can now install a process-wide waker with wasmer_napi::set_foreground_task_waker (bridge: snapi_bridge_set_foreground_task_waker; platform: EdgeV8Platform::SetForegroundTaskWaker). The platform calls it on the posting thread right after it queues an immediate task there, so the guest's wait ends and its next turn takes the checkpoint that runs the task. Delayed tasks, and tasks handed to a bound target, don't call it. The Rust side keeps the waker in an RwLock and calls it outside the lock, so a waker may replace or remove itself. A panic in the waker, or in dropping it, is caught before it can unwind into V8. The call has a guard of its own, so the waker's last reference is never dropped while its panic unwinds. Without a waker the platform calls nothing, and posting a task costs one more atomic load. Measured in WebkitWasm, whose browser binds no target and sleeps until its next GUI event between turns: a page running a nested engine, whose GPU owner it wakes with Atomics.waitAsync about 31 times a frame, went from 19.8 to 59.7 fps, and a Worker-to-page waitAsync round trip from 14 ms to 0.03 ms at p90. Idle CPU did not change. tests/src/v8_foreground_task_waker_test.cc checks the platform: an immediate task posted from another thread calls the waker once, on that thread, after the task is queued, and the next pump runs it; a delayed task, a cleared waker and a bound target don't call it. tests/foreground_task_waker.rs checks the Rust API through Wasmer dispatch: a guest's Atomics.notify on another thread calls the waker for the waiting guest's task, which resolves at that guest's next checkpoint; a removed waker isn't called; neither a waker that panics nor one that removes itself, panics, and holds a capture that panics when dropped takes the process down. The napi-native-concurrency workflow now runs it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This was referenced Nov 6, 2026
syrusakbary
added a commit
that referenced
this pull request
Nov 6, 2026
Brings in #139 (a process-wide waker the host installs for V8 foreground tasks only a checkpoint runs: wasmer_napi::set_foreground_task_waker, snapi_bridge_set_foreground_task_waker, EdgeV8Platform::SetForegroundTaskWaker), #138 (host-JS napi_is_detached_arraybuffer) and #136 (a V8 CPU profile per env when NAPI_V8_CPU_PROFILE_DIR is set). Conflicts: - v8/src/unofficial_napi.cc, UnofficialEnvScope: next added `releasing` (a release called again from a hook is refused), main added `cpu_profile`. Both are kept. - v8/src/unofficial_napi.cc, before NearHeapLimitCallback: main adds StartEnvCPUProfile and FinishEnvCPUProfile next to its NearHeapLimitCallback(void* raw_env, ...), which next changed to take the agent. next's callback is kept, and main's two functions are moved onto next's agent. main keeps the CPU profiler and the profile sessions in g_profiler_states (EnsureProfilerState), under g_runtime_mu; next replaced that map with napi_agent__'s cpu_profiler and active_profiles, which only the isolate's thread touches. So the two functions read env->agent and take no lock. Both check the thread first (IsEnvThreadEntered, and in FinishEnvCPUProfile the session's owner thread), as unofficial_napi_profile_start and _stop do. The session is still listed with the agent's other sessions, so napi_agent__::Shutdown (DisposeProfilers) stops and frees it when FinishEnvCPUProfile can't. Merged without a conflict, and fixed: - src/snapi_js.rs, snapi_bridge_is_detached_arraybuffer and its test (#138): main looks the value up with state.get(id) and stores the test's values with state.insert. next moved the value table from HostJsEnv to its HostJsAgent, so these are state.agent.get and state.agent.insert, as everywhere else on next. HostJsEnv has neither method, so the wasm32 `js` build did not compile without this. Merged without a conflict, and checked: - ReleaseEnvScope: FinishEnvCPUProfile runs after next's refusal of a release called again, so such a call leaves the session alone, and before DestroyEnvInstance. - #136 against next's release contract: the profile is stopped and written at the start of unofficial_napi_release_env. Then napi_agent__::Shutdown disposes the agent's profiler, and only then does the env's teardown run the cleanup hooks, the finalizers and the instance-data finalizer. So the JS they run, which next's release contract allows, is not in the profile, as v8/README.md says (the profile ends at the start of the release) and as on main, whose DestroyEnvInstance also disposed the profiler before them. - #136 against realms: V8's CPU profiler samples the isolate, so JS that runs in any realm of the env is in the profile. - #136 against the sticky termination: FinishEnvCPUProfile runs no JS (it reads the profile through the public getters), so after an uncancelled termination the profile is still written, complete and valid. - #139 against the sticky termination: the waker is called when a task is posted, on the posting thread, and never by a checkpoint. A checkpoint the termination refuses (napi_pending_exception) runs no task and posts none, so a host that sleeps until it is woken takes one turn and sleeps again; it does not spin. The task stays queued and runs at the first checkpoint after the cancel, and the cancel does not call the waker for it. - #139 against the release: the waker takes no env. Hook JS that posts a task during the release (the target is cleared first) calls it on the env's thread. Once the isolate's shutdown begins, ForegroundTaskRunner drops a post without calling it. Drains of next's finalizer queues, which hold the env's drain token, go only to the embedder's enqueue hook and never call the waker. - #138 against next's host-JS realms: realms share the host's intrinsics and their values live in the agent's table, so the answer is the same for a buffer from any realm, asked in any realm, also after realm code replaced the ArrayBuffer getters, Function.prototype.call or Uint8Array, which the helper captured at load. - tests/CMakeLists.txt: main registers test_76_env_cpu_profile (V8, Linux and macOS) and napi_v8.foreground_task_waker. next's test_76_termination_until_cancelled was renumbered to test_78 before this merge, so no runner shares a number. - include/unofficial_napi.h, src/napi_bridge_init.cc, src/snapi.rs and tests/host-js/README.md take main's hunks; next's changes to them are elsewhere in those files. - QuickJS keeps next's pin: none of the three changes touches it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
syrusakbary
added a commit
that referenced
this pull request
Nov 6, 2026
The foreground task waker from "Wake the host when V8 queues a task only a checkpoint runs" (#139) is called when V8 posts an immediate task to the default platform's queue, which only unofficial_napi_event_loop_checkpoint runs, so that a host that sleeps until it is woken takes that checkpoint. Since "V8: keep a termination until it is cancelled", the checkpoint of an env that terminates refuses at once (napi_pending_exception) and runs no task. So a task posted just before or during a termination woke the host once, the host's turn was refused, and the cancel woke nothing: the task waited for an unrelated wake, as it did before #139. unofficial_napi_cancel_terminate_execution now calls the new EdgeV8Platform::WakeForQueuedForegroundTasks, which calls the waker on the env's thread when the isolate has used that queue, is not shutting down, and has tasks pending (the count the platform keeps for the isolate's shutdown is not 0). The count also holds delayed tasks and tasks handed to a bound target, so a cancel may wake a host that then finds nothing due and waits again, which the waker's contract already allows. A bound target is no reason to skip: tasks posted to the queue before it was bound stay there (found by a Codex review). A refused checkpoint still calls no waker, so a host does not spin while the env terminates. include/unofficial_napi.h, src/lib.rs and v8/src/edge_v8_platform.h say so. Test: test_78's CancelWakesTheHostForTheTasksLeftQueued (V8) posts a task with Atomics.notify on a same-thread Atomics.waitAsync, terminates, takes 100 refused checkpoints, cancels, and runs the task at a checkpoint. It counts the waker's calls on the env's thread: one for the post, none for the refused checkpoints, one for the cancel. Before this commit it failed at the cancel ("the cancel did not wake the host for the task left queued": 1 call, expected 2). It passed 50 runs in a row, and V8 342/342 and QuickJS 291/291 pass. QuickJS has no platform queue and no waker. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
When an isolate has no foreground task target bound,
EdgeV8Platformputs V8's foreground tasks in the default platform's queue. Only the guest's next event-loop checkpoint runs them (PumpPendingForegroundTasks, one task per checkpoint). Guests running throughwasmer_napinever bind a target, because the bridge'sunofficial_napi_attach_envinstalls no native hooks. V8 posts these tasks from any thread: to resolve anAtomics.waitAsyncthat another thread'sAtomics.notifywoke, to finish aWebAssembly.compile, to runFinalizationRegistrycallbacks. A guest that sleeps until its next host event was never told that one was due, so the task waited until something unrelated woke the guest.This adds a process-wide waker. A host installs it with
wasmer_napi::set_foreground_task_waker, andEdgeV8Platformcalls it on the posting thread right after it queues an immediate task in that queue. The waker ends the guest's wait, and the guest's next turn takes the checkpoint that runs the task. Delayed tasks, and tasks handed to a bound target, don't call it.WebkitWasm (WebKit compiled to Wasm, running on this provider) binds no target, and its browser sleeps until the next GUI event between turns. Measured there, with the GUI context's event waker installed:
Atomics.waitAsyncabout 31 times a frameAtomics.waitAsyncround trip, p90Idle CPU did not change.
Changes
v8/src/edge_v8_platform.h,v8/src/edge_v8_platform.cc:EdgeV8Platform::SetForegroundTaskWaker(void (*)())stores the function in astd::atomic.ForegroundTaskRunner::PostTaskCommoncalls it right afterrunner->PostTaskon the fallback runner, for immediate tasks only. The platform holds none of its own locks then. Posting an immediate task now costs one more atomic load, with or without a function set. The function takes no data pointer, so that one atomic store publishes it.src/napi_bridge_init.cc,src/snapi.rs: the host-only bridge functionsnapi_bridge_set_foreground_task_waker. It is not a guest import.src/lib.rs:wasmer_napi::set_foreground_task_waker(Option<Arc<dyn Fn() + Send + Sync>>).RwLock. The platform gets a plainextern "C"trampoline, which clones the waker under the read lock and calls it once the lock is released, so a waker may replace or remove itself.catch_unwindguards keep a panic from unwinding into V8, where it would abort the process. The outer one covers the clone and its drop. The inner one covers the call, so a panic in the waker has ended before the clone is dropped. The clone can be the last reference, and if it were dropped while the waker's panic unwound, a capture whose destructor panics would abort the process. Panic payloads are leaked rather than dropped.wasm32withjs), which has no V8 platform queue. This is thecfgLet an embedder set the process time zone and an isolate's locale #130 uses forset_process_time_zone.tests/src/v8_foreground_task_waker_test.cc(new, a standalone process likev8_foreground_checkpoint_test.cc): a real isolate with no target bound, and tasks posted from a thread of the test's own. Every wait has a 10 s timeout, and each task's run count is shared with the task, so a task that a failing case leaves queued still runs safely at the final pump.tests/foreground_task_waker.rs(new, a test binary of its own because the waker is process-wide): two WAT guests (tests/wat_guest) on two threads share aSharedArrayBuffer. The page guest starts anAtomics.waitAsync. The other guest'sAtomics.notifythen queues the page's resolve task from its own thread.set_foreground_task_waker(None), nothing calls the waker, and a checkpoint still resolves the promise.set_foreground_task_waker(None), then panics, holding a capture whose destructor panics: it runs, it is not called again, and the process survives.tests/CMakeLists.txt: registersnapi_v8.foreground_task_waker, with a 120 s ctest timeout, in a new V8-only block at the end..github/workflows/napi-native-concurrency.yml: runs--test foreground_task_wakerin the step that runsconcurrent_envsandconcurrent_stores(it needs no WASIX C toolchain either), and adds the file to the path filters.Testing
On macOS arm64 with the repo's V8 prebuilt (V8 13.6.233). The branch is based on 598a65a.
mainhas since moved to 87937f1 (#134 and #135), which this branch merges with cleanly, so the V8, library, test-file and host-JS runs were repeated on that merge:make test-napi CMAKE_BUILD_TYPE=Release: 117/117 pass on the branch, against 116 on 598a65a. Merged with 87937f1: 120/120, against the 119 that 87937f1 registers (Pass guest names to the engine with their exact bytes, and refuse lengths above INT_MAX #134'stest_74_name_length_limitsadds three). The new test makes up the difference both times.make test-napi-quickjs CMAKE_BUILD_TYPE=Release: 109/109 on the branch, same as 598a65a. (Run before the review fixes, which touch nothing QuickJS builds. Pass guest names to the engine with their exact bytes, and refuse lengths above INT_MAX #134 and Run the cargo unit tests and the WAT-guest tests in CI, and fixmanifest_testsundercargo-standalone.sh#135 add no QuickJS test.)./cargo-standalone.sh test --locked --lib: 60 passed on the branch, same as 598a65a. Merged with 87937f1: 62, the two more being Pass guest names to the engine with their exact bytes, and refuse lengths above INT_MAX #134's unit tests insrc/guest/mod.rs../cargo-standalone.sh test --locked --tests --no-fail-fast: on the branch and on the merge, every test file passes, the newforeground_task_waker(1/1) and, on the merge, Pass guest names to the engine with their exact bytes, and refuse lengths above INT_MAX #134'sguest_names(5/5) included, exceptmanifest_tests_match_native_and_wasix. That one fails on both bases without this change. On 598a65a it can't build thenapi_wasmerCLI binary ("No such file or directory"). On 87937f1, which lets it find the checkout, it fails to link the nativehello_napi_teston macOS, becauselibv8.aneeds CoreFoundation symbols ("Undefined symbols for architecture arm64").RUSTFLAGS="-C target-feature=+atomics,+bulk-memory,+mutable-globals" ./cargo-standalone.sh +nightly check --target wasm32-unknown-unknown --features js --lib -Z build-stdpasses on the branch and on the merge, with the same 21 warnings as 598a65a and 87937f1../cargo-standalone.sh clippy --locked --lib --test foreground_task_waker: no warnings.rustfmt --checkis clean.EdgeV8Platform::SetForegroundTaskWakerandwasmer_napi::set_foreground_task_wakerdon't exist.PostTaskCommon, the immediate-task case fails ("the waker was not called", after its 10 s timeout), and so doesforeground_task_waker("the waker did not run on the notifying thread").runner->PostTask: the immediate-task case fails ("not queued when the waker ran").SetForegroundTaskWakerignoringnullptr: the cleared case fails.set_foreground_task_wakernot calling the bridge:foreground_task_wakerfails. IgnoringNone: it fails with "a removed waker ran".catch_unwind: the panicking waker aborts the test process (SIGABRT, "failed to initiate panic").Notes for reviewers
Atomics.notifyposts the resolve task while holding V8's futex wait-list mutex, from any thread. A garbage collection posts theFinalizationRegistrycleanup task from the isolate's own thread, during the pause. So a waker must be quick, must not call into V8 or run guest code, and must not take a lock the host holds around guest calls. Both the C++ and the Rust docs say so. Waking an event loop or signaling a condition variable is what it's for.set_foreground_task_wakerdoesn't deadlock (the test covers this). The setter holds the write lock only to swap the slot and store the platform's pointer, and neither takes a V8 or platform lock. A posting thread that finds the write lock taken waits only for that.Arc(Rust), just before a change may still call it after the setter returns. TheArckeeps a replaced Rust waker alive until then. If that clone is the last reference, the waker is dropped on the posting thread, possibly under V8's locks; the Rust docs say so.unofficial_napi_attach_envgives the provider no enqueue hook, so no guest binds a target. Only a native embedder that passes its own enqueue hook tounofficial_napi_attach_envgets its tasks handed to it, with no wake.main. A path added later that keeps foreground tasks for a checkpoint would need the same wake.napi_v8.foreground_task_wakerruns withmake test-napi, andnapi-native-concurrencynow runstests/foreground_task_waker.rs. Run the cargo unit tests and the WAT-guest tests in CI, and fixmanifest_testsundercargo-standalone.sh#135, now onmain, added a second step to that workflow (the library and WAT-guest tests) andtests/guest_*.rsto its path filters. This branch's filter line sits beforetests/concurrent_*.rs, and Run the cargo unit tests and the WAT-guest tests in CI, and fixmanifest_testsundercargo-standalone.sh#135's after it, so the branch merges with 87937f1 cleanly: the merged workflow runs the waker test withconcurrent_envsandconcurrent_storesin the first step, then Run the cargo unit tests and the WAT-guest tests in CI, and fixmanifest_testsundercargo-standalone.sh#135's step, and both path filters listtests/foreground_task_waker.rsandtests/guest_*.rs.git merge-tree --write-treeagainstmainat 87937f1, in both merge orders:snapi_bridge_set_process_time_zoneright aftersnapi_bridge_set_v8_worker_thread_countin the bridge and insrc/snapi.rs, andset_process_time_zoneafterset_v8_worker_threadsinsrc/lib.rs. This branch's additions sit apart from those: aftersnapi_bridge_initin the bridge, beforesnapi_bridge_set_v8_worker_thread_countinsrc/snapi.rs, and afterWorkerThreadsAlreadyFixedinsrc/lib.rs. The two merge cleanly in either order.src/snapi.rsandtests/CMakeLists.txt.mainalready conflicts with Add realm-aware trusted scripts and native execution-state queries #106 in the same two hunks, and this branch's lines sit outside them.mainalready does. feat(napi): consolidate managed Edge V8 and metered WebAssembly #84 already conflicts withmainin 16 files, and rewritesedge_v8_platform.cc. This branch adds two conflict hunks there (the waker slot andSetForegroundTaskWaker).maintogether, this branch first or last.next(next: realm handles and realm entry, with one env per engine instance #127). Git merges this branch intonextwithout a conflict, and the result needs no edit.v8/src/edge_v8_platform.{h,cc}andsrc/lib.rsare the same onnextas onmain, so the wake and the Rust API land unchanged. Insrc/napi_bridge_init.ccandsrc/snapi.rs, whichnextrewrote, the bridge function lands right aftersnapi_bridge_init, as onmain, and it uses no env state. Onnext, as onmain, the bridge'sunofficial_napi_attach_envpasses the provider empty hooks. No realm or contextify path binds or clears a foreground task target, so guests' tasks still go to the default platform's queue and wake the host. The waker doesn't change which microtask queue a checkpoint drains: that is still the env's main context's. A promise that a woken task settles in a realm with its own microtask queue still runs its reactions when that realm's queue is drained, as for a contextify context onmain.tests/foreground_task_waker.rsdoesn't use thetests/wat_guesthelper thatnextrenamed (eval_contextify, nowrun_script_in_realm), and itsevalruns in the env's principal realm.tests/CMakeLists.txtand the workflow merge alongsidenext's realm tests. A tested resolution exists:next(f928811) merged withmain(87937f1), then this branch. On it,make test-napipasses 182/182 (181/181 without this branch),--lib62 passed (the same), and--testspasses every test file,foreground_task_waker(1/1) included, exceptmanifest_tests_match_native_and_wasix, which fails there without this branch too, the same way as on87937f1(the nativehello_napi_testlink). The host-JS compile check passes with the same 21 warnings as without. Without the wake inPostTaskCommon, both new tests fail on that merge, with the same messages as onmain. Nothing else has to change onnext. (nextitself conflicts withmaininv8/src/js_native_api_v8.cc, over Pass guest names to the engine with their exact bytes, and refuse lengths above INT_MAX #134's length checks innapi_create_function. That conflict isn't this PR's.)napi-native-concurrencyjob will be the first Linux run oftests/foreground_task_waker.rs). The waker under ThreadSanitizer. EdgeJS's native and WASIX suites against this branch. The measurements were taken in WebkitWasm with its own form of this patch, whose wake for immediate tasks is the same as this one.🤖 Generated with Claude Code