Skip to content

fix(ffi/objc): enter a Node callback scope for native callbacks from a host-owned run loop - #102

Open
NathanWalker wants to merge 2 commits into
mainfrom
feat/napi-host-runloop-callbacks
Open

NathanWalker wants to merge 2 commits into
mainfrom
feat/napi-host-runloop-callbacks

Conversation

@NathanWalker

@NathanWalker NathanWalker commented Oct 30, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Hosts that own the native run loop (Electron's main process, for one) crash the Node-API runtime on the first Objective-C → JS callback. Under Node, JS pumps the Cocoa run loop, so a V8 context and HandleScope are always on the stack. Under Electron, Cocoa re-enters JS with neither, and V8 aborts:

Fatal error in V8: v8::HandleScope::CreateHandle() Cannot create a handle without a HandleScope

Same-thread callbacks now enter JS through NativeCallbackScope::run, the Node-API branch of the existing callback scope in CallbackThreading.h:

 JSMethodCallback / JSFunctionCallback / JSBlockCallback (same thread)
-  invoke JS directly                     # assumes JS is already on the stack
+  NativeCallbackScope::run(env, fn, data)
+    JS→native call in progress on this thread (depth > 0)
+      napi_open_handle_scope; fn()      # unchanged timing, no extra cost
+    no JS on the stack
+      napi_make_callback(trampoline)    # enters env context + Node callback scope
+        fn(); report a pending JS error  # through the closure uncaught-error handling
+      rethrow any NSException           # outside V8 frames
+      # closing the scope drains nextTicks/microtasks
+    trampoline didn't run → zero the native return value
  • NativeCallRuntimeUnlockScope, which already wraps JS→native calls, keeps a thread-local depth counter in Node-API builds. A call site that doesn't use it only takes the slower path, which is still correct.
  • The trampoline function, receiver and napi_async_context are created in nativescript_init while JS is on the stack, and released with an env cleanup hook.
  • napi_async_init, napi_make_callback, etc. are declared locally because this tree vendors js_native_api.h but not node_api.h.
  • Off-thread callbacks keep their existing threadsafe-function path.
  • ENABLE_JS_RUNTIME builds compile exactly as before. Every change is under #ifndef ENABLE_JS_RUNTIME.
  • Known limit: all callbacks share one async context created at init, so AsyncLocalStorage inside a delegate callback sees init-time values.

Evidence

All on macOS 26.6.2 (arm64), --macos --no-engine build. Each check exercises one native→JS path:

performSelector:withObject:afterDelay: → JS method override (target/action shape)
NSTimer block resolving a promise the caller awaits
-[NSArray enumerateObjectsUsingBlock:] called from JS (synchronous, nested)
sortedArrayUsingComparator: / predicateWithBlock: (BOOL and NSComparisonResult return values)
JS error thrown inside a synchronous block reaches the JS caller
queueMicrotask inside a run-loop callback runs
  • Before (base of this PR): Electron 45: Fatal error in V8: v8::HandleScope::CreateHandle() Cannot create a handle without a HandleScope
  • After: all six pass on each host, three runs each:
    Electron 45.1.0 (Node 24.22.1)   6/6
    Node v26.10.0                    6/6
    Deno 2.9.1                       6/6
    Bun 1.4.2                        6/6
    
  • Node, Deno and Bun pump the run loop from JS, so they take the depth > 0 path. To exercise napi_make_callback / napi_async_init on Deno and Bun, the same checks were also run on a throwaway build with the depth check disabled: 6/6 on all four hosts.
  • MACOS_TEST_FFI_BACKEND=napi npm run test:macos (engine build with this bridge, ENABLE_JS_RUNTIME): 714 tests, 0 failures, 17 skipped. npm run test:macos (V8 bridge): 714 tests, 0 failures, 10 skipped.

A larger proof of concept also ran on this build: Electron + NativeScript on macOS, with NSToolbar delegates, NSGlassEffectView mouse overrides, MKMapViewDelegate, MKLocalSearch completion blocks, NSColorPanel target/action, NSPopover/NSDatePicker and AVSpeechSynthesizer, all inside a BrowserWindow.

Merge Danger

Door: two-way

Isolated to ffi/objc/napi; a revert restores the previous behavior exactly.

Blast Radius: Node-API builds

  • Nested callbacks (JS→native→JS) run as before, in a plain handle scope.
  • Callbacks with no JS on the stack go through napi_make_callback: they drain microtasks when they return, instead of on the next tick.
  • Test coverage: iOS Node-API hosts weren't run here.

Not in this PR, but found along the way:

  • build_nativescript.sh hashes ./metadata-generator/src … while build_metadata_generator.sh writes the hash from src …, so the generator rebuilds on every build.
  • npm run metagen macos targets macOS 11, which drops declarations introduced later (e.g. NSGlassEffectView).

@coderabbitai

coderabbitai Bot commented Oct 30, 2026 •

Copy link
Copy Markdown

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 66786d56-562a-4ed7-801e-75bf6984a933

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • Trigger review
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@ammarahm-ed

Copy link
Copy Markdown
Collaborator

The approach is right. In Node/Electron builds we can't reach the isolate or context like NapiScope does in our own runtimes, and napi_make_callback is the only Node-API call that enters the context. A few things to fix before merge:

1. The return value can be left uninitialized.
If napi_make_callback fails before calling the trampoline (env or worker teardown, or an exception already pending), the callback body never runs and ret is never written. Objective-C then reads garbage as the BOOL or id result. Track whether the trampoline actually ran, and zero ret if it didn't.

2. Don't silently drop the exception.
On napi_pending_exception, the error is cleared and thrown away. It's rare because the callbacks already handle their own JS errors, but when it happens it hides a bug. Send it through the same uncaught-error handling the callbacks use.

3. Skip the new path when JS is already on the stack.
Right now every same-thread callback goes through std::function + napi_make_callback, including hot synchronous ones like enumerateObjectsUsingBlock: or sort comparators called from JS. Those already have a context entered and never needed this.

  • Add a thread-local depth counter in NativeCallRuntimeUnlockScope, which already wraps JS→native calls but does nothing in these builds.
  • If the depth is above 0, run the callback directly in a plain handle scope.
  • A call site that doesn't use that scope just takes the slow path, which is still correct.

This also keeps microtask timing and async context unchanged for nested callbacks, so the behavior change only applies to callbacks that arrive from a bare run loop, where it's actually needed.

4. Keep it next to the existing callback scope code.
Move the helper into CallbackThreading.h as the Node-API branch of NativeCallbackScope, which is currently empty for these builds. Then all native→JS entry stays in one place instead of a second mechanism in Closure.mm.

5. Fix the description.
React Native isn't on this code path. The RN pod builds ffi/objc/hermes, not ffi/objc/napi. Please drop it from the untested list.

6. Run it once on Deno and Bun.
They take this path, and their napi_make_callback / napi_async_init aren't Node's.

Smaller, not blocking:

  • The [&] lambda captures four references, which is more than std::function stores without allocating, so each callback allocates. A function pointer plus void* avoids that. Port modules like CommonJS module system, Workers from original runtime to Node-API #3 removes most of the cost anyway.
  • All callbacks share one async context created at init, so AsyncLocalStorage inside a delegate callback sees init-time values. Fine to leave, but worth noting as a known limit.

@NathanWalker

Copy link
Copy Markdown
Contributor Author

Thanks for the review. All points are addressed in c6a2fbc (amended and force-pushed):

  1. Return value when the trampoline doesn't run: NativeCallbackScope::run returns whether the callback ran. If it didn't and the return type isn't void, the native return buffer is zeroed.
  2. Exceptions: a JS exception left pending by the callback goes through reportNativeCallbackError. That's the same capture/OnUncaughtError handling JSCallbackInner uses, and it runs inside the trampoline so the context is still entered. An NSException thrown inside is caught and rethrown once napi_make_callback returns.
  3. JS already on the stack: NativeCallRuntimeUnlockScope keeps a thread_local depth counter. While it's above zero, the callback is called directly in a plain handle scope. Only callbacks with no JS on the stack go through napi_make_callback.
  4. Location: the helper is now the Node-API branch of NativeCallbackScope in CallbackThreading.h (initialize(env) and run(env, fn, data)). It takes a function pointer plus void* instead of std::function, so nothing is allocated per callback.
  5. Description: React Native is out of the untested list. The shared async context is now a known limit (AsyncLocalStorage sees values from init time).
  6. Deno and Bun: six callback checks (delegate, block, method override, returned value, thrown error, nested JS→native→JS) pass on Electron 45.1, Node 26.10, Deno 2.9.1 and Bun 1.4.2, three runs each. Node, Deno and Bun normally take the fast path. To exercise napi_make_callback itself, I ran the checks on a throwaway build that always takes the slow path, and they passed on all four hosts. The base build still aborts in Electron with the HandleScope error.

MACOS_TEST_FFI_BACKEND=napi npm run test:macos: 714 tests, 0 failures. The default test:macos uses the V8 bridge, which doesn't compile ffi/objc/napi, so I ran the napi backend as well. That run caught a compile error in the engine build (CallbackThreading.h included unguarded in ObjCBridge.mm), which is fixed.

@ammarahm-ed
ammarahm-ed force-pushed the android-react-native branch 2 times, most recently from 4f87f05 to 9633aba Compare November 8, 2026 12:59
…a host-owned run loop

In the Node-API build, Objective-C → JS callbacks (method overrides,
target/action, delegates, blocks, C function pointers) assumed JS was
already on the stack. That holds under Node, where the app pumps the Cocoa
run loop from JS, but not in hosts that own the native run loop, such as
Electron's main process: Cocoa re-enters JS with no V8 context entered and
no HandleScope open, and the process aborts with
"Cannot create a handle without a HandleScope".

Route same-thread callbacks through a native trampoline invoked with
napi_make_callback, which enters the env's context and opens a Node
callback scope (draining nextTicks and microtasks when the outermost scope
closes). The trampoline and async context are created at init, while JS is
on the stack. Objective-C exceptions raised inside the callback are caught
and rethrown after napi_make_callback returns, so they never unwind through
V8 frames. ENABLE_JS_RUNTIME builds are unchanged.
…cope

- Same-thread callbacks call JS directly in a handle scope while a
  JS→native call is in progress on the thread (tracked by
  NativeCallRuntimeUnlockScope); only callbacks with no JS on the stack go
  through napi_make_callback.
- Zero the native return value when the trampoline does not run.
- Report a JS error left pending by a callback through the closure
  uncaught-error handling, inside the callback scope.
- The helper is the Node-API branch of NativeCallbackScope and takes a
  function pointer plus data instead of a std::function.
@NathanWalker
NathanWalker force-pushed the feat/napi-host-runloop-callbacks branch from c6a2fbc to e6ea813 Compare November 20, 2026 21:24
@NathanWalker
NathanWalker changed the base branch from android-react-native to main November 20, 2026 21:24

This branch has not been deployed

No deployments
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.

2 participants