Skip to content

Wake the host when V8 queues a task only a checkpoint runs - #139

Merged
syrusakbary merged 1 commit into
mainfrom
feat/v8-foreground-task-waker
Nov 6, 2026
Merged

syrusakbary merged 1 commit into
mainfrom
feat/v8-foreground-task-waker

Conversation

@syrusakbary

@syrusakbary syrusakbary commented Nov 6, 2026 •

Copy link
Copy Markdown
Member

Summary

When an isolate has no foreground task target bound, EdgeV8Platform puts 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 through wasmer_napi never bind a target, because the bridge's unofficial_napi_attach_env installs no native hooks. V8 posts these 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. 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, and EdgeV8Platform calls 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:

Without this change With it
A page running a nested engine, whose GPU owner it wakes with Atomics.waitAsync about 31 times a frame 19.8 fps 59.7 fps
Worker-to-page Atomics.waitAsync round trip, p90 14 ms 0.03 ms

Idle CPU did not change.

Changes

  • v8/src/edge_v8_platform.h, v8/src/edge_v8_platform.cc: EdgeV8Platform::SetForegroundTaskWaker(void (*)()) stores the function in a std::atomic. ForegroundTaskRunner::PostTaskCommon calls it right after runner->PostTask on 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 function snapi_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>>).
    • The waker lives in an RwLock. The platform gets a plain extern "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.
    • Two catch_unwind guards 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.
    • The setter swaps the slot and gives the platform the trampoline (or null) under the write lock, so concurrent calls leave the two in agreement. It drops the previous waker after unlocking.
    • The docs spell out where the waker can run: another guest's thread, a V8 worker thread, or the guest's own thread in the middle of a guest call or a GC. So it must not call into V8, run guest code, or take a lock the host holds around guest calls, and a replaced waker's captures must not call into V8 when dropped.
    • It isn't compiled for the host-JS backend (wasm32 with js), which has no V8 platform queue. This is the cfg Let an embedder set the process time zone and an isolate's locale #130 uses for set_process_time_zone.
  • tests/src/v8_foreground_task_waker_test.cc (new, a standalone process like v8_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.
    • An immediate task calls the waker once, on the posting thread. The main thread waits on a condition variable, as a guest waits on its event source, and the waker wakes it. The poster stays inside the waker until the main thread has pumped, and that pump runs the task, so the task was queued before the waker ran. The task doesn't run before the pump.
    • A delayed task (50 ms) doesn't call the waker, and runs at a pump after its delay.
    • A cleared waker isn't called, and the next pump still runs the task.
    • A task for an isolate with a bound target goes to the target and doesn't call the waker.
  • 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 a SharedArrayBuffer. The page guest starts an Atomics.waitAsync. The other guest's Atomics.notify then queues the page's resolve task from its own thread.
    • With a waker set, the waker runs on the notifying thread during the notify. The promise stays pending until the page runs a checkpoint, which resolves it.
    • After set_foreground_task_waker(None), nothing calls the waker, and a checkpoint still resolves the promise.
    • A waker that panics runs on the notifying thread, doesn't take the process down, and the promise still resolves.
    • A waker that removes itself with set_foreground_task_waker(None), then panics, holding a capture whose destructor panics: it runs, it is not called again, and the process survives.
    • The page guest is dropped only after the test has passed, so a regression that leaves the notifying guest stuck inside V8 fails the test instead of hanging it.
  • tests/CMakeLists.txt: registers napi_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_waker in the step that runs concurrent_envs and concurrent_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. main has 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's test_74_name_length_limits adds 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 fix manifest_tests under cargo-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 in src/guest/mod.rs.
  • ./cargo-standalone.sh test --locked --tests --no-fail-fast: on the branch and on the merge, every test file passes, the new foreground_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's guest_names (5/5) included, except manifest_tests_match_native_and_wasix. That one fails on both bases without this change. On 598a65a it can't build the napi_wasmer CLI binary ("No such file or directory"). On 87937f1, which lets it find the checkout, it fails to link the native hello_napi_test on macOS, because libv8.a needs CoreFoundation symbols ("Undefined symbols for architecture arm64").
  • Host-JS backend: RUSTFLAGS="-C target-feature=+atomics,+bulk-memory,+mutable-globals" ./cargo-standalone.sh +nightly check --target wasm32-unknown-unknown --features js --lib -Z build-std passes 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 --check is clean.
  • The C++ test passed 48 runs, 6 at a time. The Rust test passed 40 runs, 4 at a time.
  • How the new tests fail:
    • Without the change, neither builds: EdgeV8Platform::SetForegroundTaskWaker and wasmer_napi::set_foreground_task_waker don't exist.
    • Without the wake in PostTaskCommon, the immediate-task case fails ("the waker was not called", after its 10 s timeout), and so does foreground_task_waker ("the waker did not run on the notifying thread").
    • Waking before runner->PostTask: the immediate-task case fails ("not queued when the waker ran").
    • Waking for delayed tasks too: the delayed case fails.
    • Waking after handing a task to a bound target: the bound-target case fails.
    • Binding the target with null data, so its task falls back to the queue: the bound-target case fails cleanly ("called the waker 1 times, expected 0", "got 0 tasks, expected 1"), and the leftover task runs at the final pump without touching a dead stack slot.
    • SetForegroundTaskWaker ignoring nullptr: the cleared case fails.
    • set_foreground_task_waker not calling the bridge: foreground_task_waker fails. Ignoring None: it fails with "a removed waker ran".
    • The trampoline without any catch_unwind: the panicking waker aborts the test process (SIGABRT, "failed to initiate panic").
    • The trampoline without the inner guard around the call: the self-removing waker aborts the test process (SIGABRT, "thread caused non-unwinding panic. aborting.") when its capture's destructor panics during the unwind.
    • The trampoline holding the read lock while it calls the waker: the self-removing waker deadlocks the notifying thread, and the test fails after 10 s ("the notifying guest did not answer: Timeout").

Notes for reviewers

  • What a waker may do. It runs on whichever thread posts the task, and V8 may hold its own locks then. Atomics.notify posts the resolve task while holding V8's futex wait-list mutex, from any thread. A garbage collection posts the FinalizationRegistry cleanup 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.
  • No lock cycle on the Rust side. The trampoline holds no lock while it calls the waker, so a waker that calls set_foreground_task_waker doesn'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.
  • A replaced waker can still run once. A thread that read the old function (C++), or cloned the old Arc (Rust), just before a change may still call it after the setter returns. The Arc keeps 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.
  • Process-wide, not per isolate. The waker runs for every isolate's tasks, so a host running several guests wakes all of them for one guest's task, and a guest with nothing to run waits again. Guests running through this crate can't opt out: the bridge's unofficial_napi_attach_env gives the provider no enqueue hook, so no guest binds a target. Only a native embedder that passes its own enqueue hook to unofficial_napi_attach_env gets its tasks handed to it, with no wake.
  • Delayed tasks still wait for the host's next turn after their delay, as before. A host that cares about them must not wait without a bound.
  • Only immediate tasks on the fallback runner wake. WebkitWasm's own form of this patch also wakes in a deferred-cleanup path that another of its patches adds and that isn't on main. A path added later that keeps foreground tasks for a checkpoint would need the same wake.
  • CI. napi_v8.foreground_task_waker runs with make test-napi, and napi-native-concurrency now runs tests/foreground_task_waker.rs. Run the cargo unit tests and the WAT-guest tests in CI, and fix manifest_tests under cargo-standalone.sh #135, now on main, added a second step to that workflow (the library and WAT-guest tests) and tests/guest_*.rs to its path filters. This branch's filter line sits before tests/concurrent_*.rs, and Run the cargo unit tests and the WAT-guest tests in CI, and fix manifest_tests under cargo-standalone.sh #135's after it, so the branch merges with 87937f1 cleanly: the merged workflow runs the waker test with concurrent_envs and concurrent_stores in the first step, then Run the cargo unit tests and the WAT-guest tests in CI, and fix manifest_tests under cargo-standalone.sh #135's step, and both path filters list tests/foreground_task_waker.rs and tests/guest_*.rs.
  • Other PRs. Checked with git merge-tree --write-tree against main at 87937f1, in both merge orders:
  • Merging into next (next: realm handles and realm entry, with one env per engine instance #127). Git merges this branch into next without a conflict, and the result needs no edit. v8/src/edge_v8_platform.{h,cc} and src/lib.rs are the same on next as on main, so the wake and the Rust API land unchanged. In src/napi_bridge_init.cc and src/snapi.rs, which next rewrote, the bridge function lands right after snapi_bridge_init, as on main, and it uses no env state. On next, as on main, the bridge's unofficial_napi_attach_env passes 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 on main. tests/foreground_task_waker.rs doesn't use the tests/wat_guest helper that next renamed (eval_contextify, now run_script_in_realm), and its eval runs in the env's principal realm. tests/CMakeLists.txt and the workflow merge alongside next's realm tests. A tested resolution exists: next (f928811) merged with main (87937f1), then this branch. On it, make test-napi passes 182/182 (181/181 without this branch), --lib 62 passed (the same), and --tests passes every test file, foreground_task_waker (1/1) included, except manifest_tests_match_native_and_wasix, which fails there without this branch too, the same way as on 87937f1 (the native hello_napi_test link). The host-JS compile check passes with the same 21 warnings as without. Without the wake in PostTaskCommon, both new tests fail on that merge, with the same messages as on main. Nothing else has to change on next. (next itself conflicts with main in v8/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 in napi_create_function. That conflict isn't this PR's.)
  • Not verified: Linux and Windows (CI's napi-native-concurrency job will be the first Linux run of tests/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

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>
@syrusakbary
syrusakbary merged commit 3d8ce76 into main Nov 6, 2026
11 checks passed
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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant