René's URL Explorer Experiment
Title: feat: V8 fast API calls through Node-API (unstable extension) by edusperoni · Pull Request #2005 · NativeScript/android · GitHub
Open Graph Title: feat: V8 fast API calls through Node-API (unstable extension) by edusperoni · Pull Request #2005 · NativeScript/android
X Title: feat: V8 fast API calls through Node-API (unstable extension) by edusperoni · Pull Request #2005 · NativeScript/android
Description: Builds on the Node-API surface from #2004 (now merged); rebased onto main, so the diff here is only the fast-call extension.
What
Lets a plugin's hot leaf functions be called from optimized JS with unboxed arguments — V8's fast API calls — without the addon writing any V8 code. A normal Node-API call crosses through FunctionCallbackInfo, a handle scope and boxed arguments; a fast call is a direct C call from TurboFan-generated code.
Design follows the brainstorm notes in ns-v8ios-runtime/NAPI_FAST_CALLS.md (deviations listed below).
This is an explicitly unstable vendor extension. Upstream Node-API declined to expose fast calls (closed not planned): Node-API's contract says a callback may call napi_*, and a fast callback may not — there is no safe general subset, so any support is an embedder extension by definition.
Gating
Three layers, answering different questions:
Layer
Mechanism
Question
Compile time
NODE_API_NS_FAST_CALLS_VERSION, always defined by the header
"does this runtime offer it?" — lets a portable addon #ifdef / __has_include and keep one source for every runtime
Compile time
NODE_API_NS_EXPERIMENTAL_FAST_CALLS required, else hard #error
"do you accept an unstable API?" — nobody lands here by accident
Run time
node_api_ns_fast_calls_available()
"can a fast call actually fire?" — false on a jitless embed; derived from the app's V8 startup flags, not hardcoded
Surface
#define NODE_API_NS_EXPERIMENTAL_FAST_CALLS
#include
static int32_t FastAdd(ns_fast_receiver recv, int32_t a, int32_t b) { return a + b; }
static napi_value SlowAdd(napi_env env, napi_callback_info info) { /* identical */ }
ns_fast_descriptor d = {0};
d.slow_cb = SlowAdd;
d.fast_fn = (const void*)FastAdd;
d.return_type.type = ns_fast_int32;
d.argc = 2;
d.arg_types = params; // {ns_fast_int32}, {ns_fast_int32}
node_api_ns_create_fast_function(env, "add", NAPI_AUTO_LENGTH, &d, &add);
The descriptor vocabulary is ours (ns_fast_type, ns_fast_param, flags). No V8 type ever reaches plugin source, so V8's churn — which has broken embedders twice already (the receiver parameter, the fallback field) — stays inside the runtime.
Receiver is the first parameter from day one, opaque, even if v1 addons ignore it — exactly the change that broke Deno (denoland/deno#15139).
fast_fn == NULL returns a plain Node-API function with zero wrapper overhead. That is the portable-addon path: one source compiles for this runtime and for the jitless iOS runtime, going fast only where the tier exists.
Fallible fast functions are supported. V8 12.6+ lets a fast callback throw; the addon takes an opaque trailing ns_fast_options and throws through node_api_ns_fast_throw_{error,type_error,range_error}, which open the handle scope internally so no isolate is ever exposed.
WebIDL conversion flags (clamp, enforce_range, is_restricted, allow_shared) are validated at registration — a flag on a type that cannot carry it is napi_invalid_arg rather than a V8 assert somewhere later.
Full contract, type table and "where it pays" in docs/node-api-fast-calls.md.
Implementation notes
Per-signature interning is mandatory, not an optimization: CFunctionInfo keeps its argument array by raw pointer, and V8 keeps the CFunctionInfo by pointer for the template's life, so both are interned per distinct signature and intentionally never freed — the shape Node gets for free from file-scope statics.
The slow path costs one extra V8 call. The vendored js_native_api_v8.cc defines CallbackBundle/FunctionCallbackWrapper inside namespace v8impl { namespace { … } } — internal linkage — so no other translation unit can invoke a napi_callback or fabricate a napi_callback_info. The forwarding callback therefore calls a real function made by napi_create_function, preserving napi's argument/receiver/exception semantics exactly, at the cost of one extra call whenever the fast path is not taken. That is the warmup path for anything hot enough to want fast calls; the real fix would be upstream, not a local ODR hack against internal classes.
Fast functions cannot be used as constructors (ConstructorBehavior::kThrow): new would have to run the slow path with a new.target the forwarding cannot reproduce.
Deviations from the brainstorm doc
Descriptor struct instead of the flat parameter list, so an explicitly unstable API can gain fields without breaking call sites — it already needed fallible and int64_as_bigint.
Handle and string returns are rejected in v1 (they would require allocation, which the fast path forbids); scalars and void only.
The iOS side should mirror the descriptor shape when it ships its slow-path-only version.
Testing
Full suite on an arm64 emulator (API 35): 895 passing / 0 failing — the feat/node-api baseline plus 16 fast-call specs.
The load-bearing ones:
The fast path actually fires: after 300k calls through a monomorphic caller, fastCallCount > 0 and fast + slow account for exactly all 300,000 calls (the addon counts each path separately).
The throw shim runs under optimized code: divide-by-zero calls are interleaved into the warm-up loop and the addon counts throws raised inside the fast function, because the observable RangeError is identical from either path. All 300 throws are caught with the right message and code, and the caller keeps running afterwards.
Semantics on both paths, WebIDL clamping, one-byte vs two-byte strings (V8 declines the fast path for two-byte, so the slow path must agree), slow-only registration, and constructor rejection.
Note for reviewers: a pre-existing worker crash
While testing I hit intermittent SIGSEGVs (2 of 4 runs) that are not from this branch or #2004. They land within ~40 ms of a Worker runtime starting, and the fast-call specs create no workers. The device carries tombstones for this test app in threads named W10: ./EvalWork dated 2026-07-30, 08-03, 08-11 and 08-12 — weeks before any Node-API work — the most recent faulting inside v8::base::OS::Abort(). Worth tracking separately (no issue filed yet); flagging here so it is not mistaken for fallout from this stack. It also explains an occasional timing failure in the Throw error in onerror worker spec.
Performance
Measured on this runtime (not borrowed figures): 2M calls of a two-int32 addition — the cheapest possible body, so essentially pure call overhead — from an optimized caller on an arm64 emulator. Absolute numbers are inflated by virtualization; the ratio is the meaningful part.
ns/call
Fast path (99.4% of calls; the rest ran before the caller tiered up)
24
Plain Node-API function
860
≈ 35× on call overhead — the ceiling, not a typical result: as soon as the body does real work, or the arguments need anything the fast path forbids, the ratio collapses toward 1. The slow path's extra forwarding call is not separately measured.
Follow-ups
Overloads (V8 resolves them by argument count), richer typed-array parameters, exposing the FastApiCallbackOptions data pointer.
Root-cause the pre-existing worker crash above.
Open Graph Description: Builds on the Node-API surface from #2004 (now merged); rebased onto main, so the diff here is only the fast-call extension.
What
Lets a plugin's hot leaf functions be called from optimized JS...
X Description: Builds on the Node-API surface from #2004 (now merged); rebased onto main, so the diff here is only the fast-call extension.
What
Lets a plugin's hot leaf functions be called from optimize...
Opengraph URL: https://github.com/NativeScript/android/pull/2005
X: @github
direct link
Domain: github.com
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /:user_id/:repository/pull/:id/files(.:format) |
| route-controller | pull_requests |
| route-action | files |
| fetch-nonce | v2:45332deb-6c7f-9803-5337-355947654bcd |
| current-catalog-service-hash | ae870bc5e265a340912cde392f23dad3671a0a881730ffdadd82f2f57d81641b |
| request-id | A94C:6365:16F1CA2:1E9812B:6B01427F |
| html-safe-nonce | 5d0ccdfacd08057211d6fcf08990b0b30c1ef2d61ab4c9a1c18fc5f28aeec5c1 |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJBOTRDOjYzNjU6MTZGMUNBMjoxRTk4MTJCOjZCMDE0MjdGIiwidmlzaXRvcl9pZCI6IjQxNjg3MjMyODgyNDk0MTgzNjciLCJyZWdpb25fZWRnZSI6ImlhZCIsInJlZ2lvbl9yZW5kZXIiOiJpYWQifQ== |
| visitor-hmac | 8ef1ac998e539502ee52b28815a82a92ab08c88710f2490ccba30334896065e3 |
| hovercard-subject-tag | pull_request:4275094718 |
| github-keyboard-shortcuts | repository,pull-request-list,pull-request-conversation,pull-request-files-changed,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | ///pull_requests/show/files |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/NativeScript/android/pull/2005/files |
| twitter:image | https://avatars.githubusercontent.com/u/4061767?s=400&v=4 |
| twitter:card | summary_large_image |
| og:image | https://avatars.githubusercontent.com/u/4061767?s=400&v=4 |
| og:image:alt | Builds on the Node-API surface from #2004 (now merged); rebased onto main, so the diff here is only the fast-call extension.
What
Lets a plugin's hot leaf functions be called from optimized JS... |
| og:site_name | GitHub |
| og:type | object |
| hostname | github.com |
| expected-hostname | github.com |
| None | cc5dfdd32f62ebd3223cab3af3aa2b268d3605218237326a48a99d1efd89495c |
| turbo-cache-control | no-preview |
| diff-view | unified |
| go-import | github.com/NativeScript/android git https://github.com/NativeScript/android.git |
| octolytics-dimension-user_id | 7392261 |
| octolytics-dimension-user_login | NativeScript |
| octolytics-dimension-repository_id | 29137950 |
| octolytics-dimension-repository_nwo | NativeScript/android |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 29137950 |
| octolytics-dimension-repository_network_root_nwo | NativeScript/android |
| turbo-body-classes | logged-out env-production page-responsive full-width |
| disable-turbo | true |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 8c77c9e8439031ad54c75a250694842892f693e1 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
Links:
| Skip to content | https://github.com/NativeScript/android/pull/2005/files#start-of-content |
| https://github.com/ |
| Sign in | https://github.com/login?return_to=https%3A%2F%2Fgithub.com%2FNativeScript%2Fandroid%2Fpull%2F2005%2Ffiles |
| GitHubRepository hosting, code review, and collaboration | https://github.com/platform |
| CopilotAI coding agent for tasks, projects, and automated work | https://github.com/features/copilot |
| ActionsCI/CD and automation | https://github.com/features/actions |
| Code QualityQuality analysis, fixes, and enforcement | https://github.com/features/code-quality |
| CodespacesCloud development environments | https://github.com/features/codespaces |
| Code SecurityVulnerability detection and remediation | https://github.com/security/advanced-security/code-security |
| Secret ProtectionSecret scanning and leak prevention | https://github.com/security/advanced-security/secret-protection |
| All Features | https://github.com/features |
| Documentation | https://docs.github.com/en |
| Training | https://learn.github.com/skills |
| Certifications | https://learn.github.com/credentials |
| Build with Copilot | https://github.com/features/ai |
| Customize Copilot | https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-copilot-overview |
| Integrations | https://github.com/marketplace |
| Trending repos | https://github.com/trending |
| GitHub Sponsors | https://github.com/open-source/sponsors |
| Developer articles | https://github.com/resources/articles |
| ChangelogYour source for the latest features, improvements, and fixes across GitHub products, all in one place. | https://github.blog/changelog/ |
| Enterprises | https://github.com/enterprise |
| Team | https://github.com/team |
| Startups | https://github.com/enterprise/startups |
| Nonprofits | https://github.com/solutions/industry/nonprofits |
| Healthcare | https://github.com/solutions/industry/healthcare |
| Financial services | https://github.com/solutions/industry/financial-services |
| Manufacturing | https://github.com/solutions/industry/manufacturing |
| Government | https://github.com/solutions/industry/government |
| See all industries | https://github.com/solutions/industry |
| Why GitHub | https://github.com/why-github |
| Customer Stories | https://github.com/customer-stories |
| Business insights | https://github.com/solutions/executive-insights |
| Trust Center | https://github.com/trust-center |
| GitHub Advanced SecurityEnterprise-grade code security | https://github.com/security/advanced-security |
| Copilot for businessEnterprise-grade AI features | https://github.com/features/copilot/copilot-business |
| Premium SupportEnterprise-grade 24/7 support | https://github.com/enterprise/premium-support |
| Documentation | https://docs.github.com/en |
| Resource center | https://github.com/resources |
| Blog | https://github.blog/ |
| Events & webinars | https://github.com/resources/events |
| Community Forum | https://github.com/orgs/community/discussions |
| Customer Stories | https://github.com/customer-stories |
| Integrations | https://github.com/marketplace |
| Customer support | https://help.github.com/ |
| Training | https://learn.github.com/skills |
| GitHub Status | https://www.githubstatus.com/ |
| About | https://github.com/about |
| Partners | https://github.com/partners |
| Changelog | https://github.blog/changelog/ |
| GitHub UniverseThe event for developers, by developers — talks, workshops, and what’s next for GitHub. | https://githubuniverse.com/ |
| Pricing | https://github.com/pricing |
| Sign in | https://github.com/login?return_to=https%3A%2F%2Fgithub.com%2FNativeScript%2Fandroid%2Fpull%2F2005%2Ffiles |
| Sign up | https://github.com/signup?ref_cta=Sign+up&ref_loc=header+logged+out&ref_page=%2F%3Cuser-name%3E%2F%3Crepo-name%3E%2Fpull_requests%2Fshow%2Ffiles&source=header-repo&source_repo=NativeScript%2Fandroid |
| Reload | https://github.com/NativeScript/android/pull/2005/files |
| Reload | https://github.com/NativeScript/android/pull/2005/files |
| Reload | https://github.com/NativeScript/android/pull/2005/files |
| NativeScript | https://github.com/NativeScript |
| android | https://github.com/NativeScript/android |
| Code | https://github.com/NativeScript/android |
| Issues106 (106) | https://github.com/NativeScript/android/issues |
| Pull requests24 (24) | https://github.com/NativeScript/android/pulls |
| Actions | https://github.com/NativeScript/android/actions |
| Projects | https://github.com/NativeScript/android/projects |
| Wiki | https://github.com/NativeScript/android/wiki |
| Security and quality | https://github.com/NativeScript/android/security |
| Insights | https://github.com/NativeScript/android/insights |
| Sign up for GitHub
| https://github.com/signup?return_to=%2FNativeScript%2Fandroid%2Fissues%2Fnew%2Fchoose |
| terms of service | https://docs.github.com/terms |
| privacy statement | https://docs.github.com/privacy |
| Sign in | https://github.com/login?return_to=%2FNativeScript%2Fandroid%2Fissues%2Fnew%2Fchoose |
| edusperoni | https://github.com/edusperoni |
| main | https://github.com/NativeScript/android/tree/main |
| feat/node-api-fast-calls | https://github.com/NativeScript/android/tree/feat/node-api-fast-calls |
|
Conversation
1
| https://github.com/NativeScript/android/pull/2005 |
|
Commits
2
| https://github.com/NativeScript/android/pull/2005/commits |
|
Checks
7
| https://github.com/NativeScript/android/pull/2005/checks |
|
Files changed
| https://github.com/NativeScript/android/pull/2005/files |
| Please reload this page | https://github.com/NativeScript/android/pull/2005/files |
|
feat: V8 fast API calls through Node-API (unstable extension)
| https://github.com/NativeScript/android/pull/2005/files#top |
|
Show all changes
2 commits
| https://github.com/NativeScript/android/pull/2005/files |
|
7d6cc57
feat: V8 fast API calls through Node-API (unstable extension)
edusperoni Aug 13, 2026
| https://github.com/NativeScript/android/pull/2005/commits/7d6cc57a9d0e55a2c47a442e4f4d5612834afbc5 |
|
e1d3018
docs: measured fast-call overhead on this runtime
edusperoni Aug 13, 2026
| https://github.com/NativeScript/android/pull/2005/commits/e1d3018d8f1b6b5f302028316d25169567be6ce1 |
|
Clear filters
| https://github.com/NativeScript/android/pull/2005/files |
| Please reload this page | https://github.com/NativeScript/android/pull/2005/files |
| Please reload this page | https://github.com/NativeScript/android/pull/2005/files |
|
README.md
| https://github.com/NativeScript/android/pull/2005/files#diff-0b5ca119d2be595aa307d34512d9679e49186307ef94201e4b3dfa079aa89938 |
|
node-api-fast-calls.md
| https://github.com/NativeScript/android/pull/2005/files#diff-975bca7999ba2db73f52bf9f4c74a90c3c12facee589d7ee80e41bb994c4cb30 |
|
node-api.md
| https://github.com/NativeScript/android/pull/2005/files#diff-ea5780440b72768dd85da61ad696f192d964e3c4271ae8bef6e1f0e4a64400c6 |
|
mainpage.js
| https://github.com/NativeScript/android/pull/2005/files#diff-b7fd6c22bfc29391e9e3ed935d6c6194b1ad595c7592690229952b5ddb99c0d5 |
|
NapiFastCallsTests.js
| https://github.com/NativeScript/android/pull/2005/files#diff-2819df5355a1375c3cdbae524133bcaf6deeadebf09a638d523b50881206df83 |
|
CMakeLists.txt
| https://github.com/NativeScript/android/pull/2005/files#diff-9aa48152a82c07a60ab6e09923a9b266e2985f78e579653848df730cd8ec5e4c |
|
build.gradle
| https://github.com/NativeScript/android/pull/2005/files#diff-45d21f088bd7aa66600d54a4a5b3053980afa3ceb6dbfcc9b3f409b1e89b42c6 |
|
NapiFastCalls.cpp
| https://github.com/NativeScript/android/pull/2005/files#diff-3868acb506a7106a85f5ab2d636ae726625c9a250fac86fa8d6852a4a1d71714 |
|
node_api_ns_fast.h
| https://github.com/NativeScript/android/pull/2005/files#diff-b849c2b505092d6e72222c40d4cedcf2d0919e14b1cd926697d731af58fd867d |
|
NapiFastCallsModule.cpp
| https://github.com/NativeScript/android/pull/2005/files#diff-dcd14f819debfbf0fd299d13f799a829f7f5a0c2e83c2193a155527ce8f57537 |
| docs/README.md | https://github.com/NativeScript/android/pull/2005/files#diff-0b5ca119d2be595aa307d34512d9679e49186307ef94201e4b3dfa079aa89938 |
|
View file
| https://github.com/NativeScript/android/blob/e1d3018d8f1b6b5f302028316d25169567be6ce1/docs/README.md |
|
Open in desktop
| https://desktop.github.com |
| https://github.co/hiddenchars |
| https://github.com/NativeScript/android/pull/2005/{{ revealButtonHref }} |
|
| https://github.com/NativeScript/android/pull/2005/files#diff-0b5ca119d2be595aa307d34512d9679e49186307ef94201e4b3dfa079aa89938 |
| docs/node-api-fast-calls.md | https://github.com/NativeScript/android/pull/2005/files#diff-975bca7999ba2db73f52bf9f4c74a90c3c12facee589d7ee80e41bb994c4cb30 |
|
View file
| https://github.com/NativeScript/android/blob/e1d3018d8f1b6b5f302028316d25169567be6ce1/docs/node-api-fast-calls.md |
|
Open in desktop
| https://desktop.github.com |
| https://github.co/hiddenchars |
| https://github.com/NativeScript/android/pull/2005/{{ revealButtonHref }} |
| docs/node-api.md | https://github.com/NativeScript/android/pull/2005/files#diff-ea5780440b72768dd85da61ad696f192d964e3c4271ae8bef6e1f0e4a64400c6 |
|
View file
| https://github.com/NativeScript/android/blob/e1d3018d8f1b6b5f302028316d25169567be6ce1/docs/node-api.md |
|
Open in desktop
| https://desktop.github.com |
| https://github.co/hiddenchars |
| https://github.com/NativeScript/android/pull/2005/{{ revealButtonHref }} |
|
| https://github.com/NativeScript/android/pull/2005/files#diff-ea5780440b72768dd85da61ad696f192d964e3c4271ae8bef6e1f0e4a64400c6 |
| test-app/app/src/main/assets/app/mainpage.js | https://github.com/NativeScript/android/pull/2005/files#diff-b7fd6c22bfc29391e9e3ed935d6c6194b1ad595c7592690229952b5ddb99c0d5 |
|
View file
| https://github.com/NativeScript/android/blob/e1d3018d8f1b6b5f302028316d25169567be6ce1/test-app/app/src/main/assets/app/mainpage.js |
|
Open in desktop
| https://desktop.github.com |
| https://github.co/hiddenchars |
| https://github.com/NativeScript/android/pull/2005/{{ revealButtonHref }} |
|
| https://github.com/NativeScript/android/pull/2005/files#diff-b7fd6c22bfc29391e9e3ed935d6c6194b1ad595c7592690229952b5ddb99c0d5 |
| Please reload this page | https://github.com/NativeScript/android/pull/2005/files |
|
| https://github.com |
| Terms | https://docs.github.com/site-policy/github-terms/github-terms-of-service |
| Privacy | https://docs.github.com/site-policy/privacy-policies/github-privacy-statement |
| Security | https://github.com/security |
| Status | https://www.githubstatus.com/ |
| Community | https://github.community/ |
| Docs | https://docs.github.com/ |
| Contact | https://support.github.com?tags=dotcom-footer |
Viewport: width=device-width
URLs of crawlers that visited me.