[NathanWalker]

Stacked on #103 (feat/napi-desktop-callbacks). Part 2 of the #103 split.

Summary

A void callback from a thread other than the JS thread is queued to the JS thread, and its native caller returns at once. Waiting deadlocks whenever the JS thread is itself blocked on that caller, e.g. a synchronous native call whose completion handler fires on a worker thread (VideoToolbox's output handler, dispatch_group_wait on a group whose block calls into JS).

 native callback on a thread other than the JS thread (Node-API builds)
-  method / function / block -> caller waits for JS
+  void, every argument on the capture allowlist -> queued, caller returns at once
+  anything else                                  -> caller waits for JS (as before)

Argument allowlist. Only listed types are captured; everything else waits:

Captured	How
integers, floats, BOOL, unichar, vectors, complex, Class, SEL	copied
structs by value with no pointer fields (e.g. CGRect, CMTime)	copied
objects (id, typed objects, NSString)	retained until the call runs
blocks	Block_copy'd until the call runs

Raw pointers, C strings, C arrays, function pointers and structs containing pointers wait. Non-void callbacks and property setters also wait.

Errors. A JS error in a queued callback goes through the same closure uncaught-error handling as one on the JS thread (__onUncaughtError, then the logged message). That handling ends by raising an Objective-C exception. With no native caller left to receive it, the exception is logged instead of becoming a fatal process exception.

Known limits (also documented in Closure.mm):

• No backpressure. The queue is unbounded and every pending call keeps its object arguments retained. When JS falls behind a producer such as a capture stream, retained sample buffers pile up and the producer's buffer pool can stall. There's no way yet for a caller to drop work; open to suggestions for an API shape (e.g. a per-callback max-pending count).
• Objects are retained, not copied. JS sees an object's state when the call runs, not when it was queued, so native code that recycles or mutates an object after the callback returns shows JS the later contents. Pointer-typed buffers (e.g. audio tap AudioBufferList *) are not affected because pointer arguments always wait.
• Getting the VideoToolbox case to queue also needs the block-parameter metadata fix (fix(metagen): keep typedef'd CF types for block parameters #116). With current metadata, CMSampleBufferRef parameters are raw pointers, so that callback still waits.

Evidence

macOS 26.6.2 (arm64), --macos --no-engine build, on Node v26.10.0, Deno 2.9.1 and Bun 1.4.2:

Check	#103	This PR
JS thread in dispatch_group_wait on a group whose void JS block runs on a worker	deadlocks until the wait times out	the wait returns, block runs after
dispatch_group_async_f (raw void * context argument)	waits for JS	waits for JS (not queued)
NSMutableString argument to a JS method via performSelectorInBackground:	delivered	delivered, retained across the queue
JS error in a queued block	process terminates with NativeScriptException	__onUncaughtError called once, later callbacks still run

• The fix(ffi/objc): enter a Node callback scope for native callbacks from a host-owned run loop #102/fix(ffi/objc): forward off-thread method and function callbacks to the JS thread #103 callback checks (run loop, synchronous blocks, off-thread methods/blocks/functions) still pass on Node, Deno, Bun and Electron 45.
• MACOS_TEST_FFI_BACKEND=napi npm run test:macos: tests=714, failures=0, errors=0, skipped=17 (the napi bridge in engine builds; the changed code is Node-API-only, so this checks engine builds are unaffected)

Merge Danger

Door: two-way

Blast Radius: Node-API builds, void off-thread callbacks

Native code that relied on a void callback from another thread finishing before the caller continued now sees JS run later, after the caller returns. Callbacks that pass raw pointers (e.g. BOOL *stop), return a value, or set a property still wait.

[coderabbitai]

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: db382b19-88fb-46d0-8a1f-2c3d6a2dc9bb

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

• X
• Mastodon
• Reddit
• LinkedIn