Skip to content

Settle async WebAssembly on Apple JavaScriptCore and scope JSC wasm exclusions to Linux - #2068

Merged
bkaradzic-microsoft merged 6 commits into
BabylonJS:masterfrom
bkaradzic-microsoft:fix/apple-jsc-async-wasm
Nov 19, 2026
Merged

bkaradzic-microsoft merged 6 commits into
BabylonJS:masterfrom
bkaradzic-microsoft:fix/apple-jsc-async-wasm

Conversation

@bkaradzic-microsoft

@bkaradzic-microsoft bkaradzic-microsoft commented Nov 10, 2026 •

Copy link
Copy Markdown
Member

Summary

JavaScriptCore finishes async WebAssembly compilation and instantiation by posting work to the JS thread's CFRunLoop. The Apple dispatch loop blocked in dispatcher.blocking_tick and never ran the run loop. As a result, WebAssembly.instantiate and WebAssembly.compile promises never settled, and anything that uses them hung (the SPZ decoder, Manifold CSG2, and so on).

  • JsRuntimeHost: adds a per-engine AppRuntime::RunDispatchLoop hook. JavaScriptCore on Apple runs the thread's CFRunLoop, with the dispatcher driven by a CFRunLoopSource that Dispatch signals. Every other engine, and JavaScriptCore on Linux, keeps the existing blocking dispatcher loop. The async WebAssembly unit tests are enabled on Apple JSC. The blocking_tick hook test is skipped there.
  • Validation: adds an excludedPlatforms test field, matched against BABYLON_NATIVE_PLATFORM through TestUtils.getPlatformName. The 18 tests that were excluded on every JavaScriptCore build now pass on Apple JSC, so they are excluded only on Linux JSC.

Side effect: JSC timers now fire on the JS thread

Running the JS thread's CFRunLoop also lets JavaScriptCore's other run-loop timers for the VM fire, not just the wasm completion. This includes the Eden and Full GC activity callbacks and the IncrementalSweeper, which sweeps in slices of up to about 10 ms and reschedules while blocks remain. These timers could not fire on this thread before.

So in every Apple JavaScriptCore app, not only wasm users, timer-driven collection and sweeping now run between dispatched tasks, and so do the Node-API finalizers they trigger. That should be a net win, because native resources are released sooner. A sweep slice can delay the next dispatched task, though, so frame time on older iPhones (A12/A13) is worth checking. This is based on WebKit's main branch; the system JavaScriptCore on a given OS version may differ.

Verification

  • JsRuntimeHost unit tests pass on macOS, including the async WebAssembly tests.
  • Ran the Playground validation suite on macOS with Metal and JavaScriptCore, with the Metal API validation layer enabled. The full suite passes with no regressions. The 18 tests pass on Apple JSC.
  • After moving the loop into JavaScriptCore-specific code, the JsRuntimeHost (31) and BabylonNative (200) unit tests pass on Win32 with Chakra. macOS coverage for that change comes from CI.
  • Not run on D3D11, D3D12, Vulkan or Linux.
  • Not verified on iOS or visionOS devices. macOS JavaScriptCore has a JIT. On device, iOS and visionOS do not, and the async WebAssembly unit test skips silently when WebAssembly is undefined. So the iOS and visionOS entries in the allow-list are unconfirmed until someone runs the SPZ scenes on a device.

Copilot AI balanced review requested due to automatic review settings November 10, 2026 17:30
@bkaradzic-microsoft bkaradzic-microsoft added bug Something isn't working testing labels Nov 10, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Copilot review overview

4 open issues
What changed in this PR

Updates Apple JavaScriptCore AppRuntime threading so deferred engine work (notably async WebAssembly compile/instantiate) can complete, and refines validation test exclusions by introducing a platform-based exclusion field.

Changes:

  • Add an Apple-specific CFRunLoop-based dispatch loop to allow JavaScriptCore deferred work to run and wake it when dispatching tasks.
  • Enable async WebAssembly unit tests on Apple JSC and skip the blocking_tick hook-based test on Apple where the hook won’t fire.
  • Add excludedPlatforms support in the Playground validation runner/config and expose platform name via TestUtils.getPlatformName().
File Description
Plugins/​TestUtils/​Source/​TestUtils.h Exposes getPlatformName() to JS via N-API.
Plugins/​TestUtils/​Source/​TestUtils.cpp Implements GetPlatformName() from BABYLON_NATIVE_PLATFORM.
Plugins/​TestUtils/​CMakeLists.txt Defines BABYLON_NATIVE_PLATFORM for TestUtils compilation.
Dependencies/​JsRuntimeHost/​Core/​AppRuntime/​Source/​AppRuntime.cpp Runs dispatcher via CFRunLoopSource on Apple and wakes the run loop on dispatch.
Dependencies/​JsRuntimeHost/​Tests/​UnitTests/​Source/​Tests.AppRuntime.cpp Skips the queue hook portion on Apple where the hook won’t execute.
Dependencies/​JsRuntimeHost/​Tests/​UnitTests/​Source/​Scripts/​tests.webAssembly.ts Enables async Wasm tests on Apple JSC (macOS/iOS) in addition to V8.
Apps/​Playground/​Shared/​CommandLine.cpp Updates --include-excluded help text to include excludedPlatforms.
Apps/​Playground/​Scripts/​validation_native.js Adds excludedPlatforms filtering based on platform name.
Apps/​Playground/​Scripts/​config.json Changes prior JSC-wide exclusions to platform-based exclusions (Unix).
.github/​instructions/​babylon-native-debugging.instructions.md Documents the new excludedPlatforms config field.

Review effort: Lite

Comment thread Apps/Playground/Scripts/config.json Resolved

@matthargett matthargett left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The run-loop source design looks sound to me: event-driven, no polling, and I could not find a lost wake-up on shutdown. We carry a cruder version of this in a fork (a zero-timeout run-loop poll after each task) and will drop it in favour of this one, since a completion no longer has to wait for an unrelated dispatch.

One note on verification. It was done on macOS, where JavaScriptCore has a JIT. On device iOS and visionOS it does not, and the unit test skips silently when WebAssembly is undefined, so the iOS entry in the allow-list would pass even if wasm were unavailable there. If anyone has an iOS device result for the SPZ scenes, it would be worth adding to the description.

@bkaradzic-microsoft

Copy link
Copy Markdown
Member Author

Good point. The PR description now says that iOS and visionOS were not verified on device and that the async WebAssembly test skips silently there without a JIT.

@bghgary bghgary left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Reviewed by Copilot on behalf of @bghgary]

Concerns inline.

Comment thread Apps/Playground/Scripts/config.json Resolved

@bghgary bghgary left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Reviewed by Copilot on behalf of @bghgary]

One requested change inline.

Branimir Karadzic and others added 6 commits November 18, 2026 14:26
…bAssembly settles

JavaScriptCore completes async WebAssembly compilation/instantiation by
posting to the JS thread's CFRunLoop. The dispatch loop blocked in
dispatcher.blocking_tick and never ran the run loop, so
WebAssembly.instantiate/compile promises never settled (SPZ decoder,
Manifold CSG2, etc. hung). On Apple, run the dispatcher from a
CFRunLoopSource and wake the run loop when work is appended.

Enable the async WebAssembly unit tests on Apple JSC and skip the
blocking_tick hook test there.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 5a2ca4f4-15a2-4ad1-8a64-9dad061e773d
Add an excludedPlatforms test config field (matched against
BABYLON_NATIVE_PLATFORM via TestUtils.getPlatformName) and use it for the
18 tests previously excluded on all JavaScriptCore builds; they pass on
Apple JSC now that async WebAssembly settles, and remain excluded on
Linux JSC.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 5a2ca4f4-15a2-4ad1-8a64-9dad061e773d
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 7b64bf64-2ec3-499d-bf8a-c8cc0b066e4f
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 7b64bf64-2ec3-499d-bf8a-c8cc0b066e4f
jsc-android is built without WebAssembly, so the SPZ loader falls back to
ReadableStream (not provided by Babylon Native) and CSG2 cannot load
Manifold. Android V8 passes all 18 tests, so allow excludedPlatforms
entries of the form "Platform/Engine" and exclude "Android/JavaScriptCore"
instead of all of Android.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 8bd57bfd-bbb3-4e86-8a17-9a44fb995d0f
Add a per-engine AppRuntime::RunDispatchLoop hook. Every engine except
JavaScriptCore keeps the blocking dispatcher loop; JavaScriptCore on Apple
runs the thread's CFRunLoop, woken through a run loop source registered as
the dispatch waker.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 8bd57bfd-bbb3-4e86-8a17-9a44fb995d0f

@bghgary bghgary left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Reviewed by Copilot on behalf of @bghgary]

One comment inline.

@bkaradzic-microsoft
bkaradzic-microsoft merged commit 1d562e7 into BabylonJS:master Nov 19, 2026
32 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working testing

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants