Skip to content

fix(ffi/objc): map metadata classes from frameworks loaded after init - #114

Open
NathanWalker wants to merge 1 commit into
mainfrom
fix/objc-lazy-framework-class-lookup
Open

NathanWalker wants to merge 1 commit into
mainfrom
fix/objc-lazy-framework-class-lookup

Conversation

@NathanWalker

Copy link
Copy Markdown
Contributor

Split out of #103 (part 5), reworked to keep lookups off the hot path as requested in review.

Summary

When class globals are registered, objc_getClass returns nil for classes in frameworks that aren't loaded yet (e.g. ScreenCaptureKit's SCWindow in a plain Node process). Those classes never entered mdClassesByPointer, so an SCWindow instance wrapped as NSObject with every property undefined.

 class not found by objc_getClass at registration
-  never mapped -> instances wrap as the nearest mapped superclass
+  kept in a pending list (name points into metadata, no copy)
+  objc_addLoadImageFunc bumps a process-wide generation counter
+  on a map miss, pending names are re-resolved once per new generation
  • Hits stay one mdClassesByPointer.find(cls).
  • Misses (e.g. __NSCFString at each superclass level) cost an empty check plus one atomic load and compare. No string allocation and no name lookup, unlike fix(ffi/objc): forward off-thread method and function callbacks to the JS thread #103's version.
  • Re-resolving runs once per burst of image loads, on the next miss. In a plain Node process, 2088 classes map at startup and 3115 stay pending. Importing ScreenCaptureKit (54 images) triggered one pass that mapped 59 classes in about 1.1 ms. No further passes ran while wrapping 255 SCWindows.
  • Threading: the image callback runs on the loading thread under the ObjC runtime lock and only bumps the atomic. All map and pending-list work happens on the bridge state's JS thread, so no lock is needed. The callback holds no per-state pointer, so teardown needs nothing, which matters because image callbacks can't be unregistered.
  • objc_addLoadImageFunc is available from macOS 10.15 / iOS 13, at or below the deployment targets.

Evidence

Node v26.10.0, plain Node-API build, macOS 26.6.2 (arm64):

Check Base This PR
SCShareableContent windows, SCWindow touched only via windows.objectAtIndex(0) NSObject, windowID/title/owningApplication all undefined SCWindow, real windowID and owningApplication
ScreenCaptureKit loaded with objc.import after init; valueForKey("defaultConfiguration") on the shared picker (untyped id) NSObject, properties undefined SCContentSharingPickerConfiguration, real property values
  • MACOS_TEST_FFI_BACKEND=napi npm run test:macos: tests=716, failures=0, errors=0, skipped=17
  • npm run test:macos: tests=716, failures=0, errors=0, skipped=10

Merge Danger

Door: two-way

Blast Radius: object wrapping in the Objective-C napi bridge. Instances of classes from frameworks loaded after init now wrap as their real class instead of a superclass.

@coderabbitai

coderabbitai Bot commented Nov 7, 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: fd54664a-f0b3-44ed-b782-161f83f89b56

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

Metadata classes whose image is not loaded when the class globals are registered (e.g. ScreenCaptureKit's SCWindow in a plain Node process) never entered mdClassesByPointer, so their instances were wrapped as NSObject.

Keep those classes in a pending list and bump a process-wide generation counter from an objc_addLoadImageFunc callback. On a mdClassesByPointer miss, the pending list is re-resolved on the JS thread only if an image has loaded since the last pass, so hits stay a single map lookup and misses add one atomic load.
@NathanWalker
NathanWalker force-pushed the fix/objc-lazy-framework-class-lookup branch from e4167f7 to 7649802 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.

1 participant