Implementation of threadsafe functions #220

paradowstack · 2025-08-14T11:18:10Z

This pull request introduces a complete implementation of Node-API's thread-safe function support for the host runtime, including its registration, lifecycle management, and queueing semantics.

Thread-safe function implementation:

Implemented all core threadsafe related Node-API functions (napi_create_threadsafe_function, napi_call_threadsafe_function, napi_acquire_threadsafe_function, napi_release_threadsafe_function, napi_unref_threadsafe_function, napi_ref_threadsafe_function, napi_get_threadsafe_function_context) in RuntimeNodeApiAsync.cpp
Added a new ThreadSafeFunction class , providing a full implementation of Node-API's thread-safe function, including queueing, reference management, context retrieval, and finalization logic. This includes a global registry for safe handle management.

Testing and examples:

Adopted node.js test

Note

Implements Node-API thread-safe functions with a new ThreadSafeFunction core, wires them into the runtime/injector, and adds test coverage with example integration.

Host Runtime (C++): Node-API thread-safe functions
- Adds ThreadSafeFunction implementation (packages/host/cpp/ThreadsafeFunction.{hpp,cpp}) with queueing, ref/release, finalize, and context retrieval.
- Exposes napi_* TSFN APIs in RuntimeNodeApiAsync.{hpp,cpp}: napi_create_threadsafe_function, napi_get_threadsafe_function_context, napi_call_threadsafe_function, napi_acquire_threadsafe_function, napi_release_threadsafe_function, napi_unref_threadsafe_function, napi_ref_threadsafe_function.
- Registers new sources in Android build (packages/host/android/CMakeLists.txt).
- Updates injector generator to export TSFN APIs (packages/host/scripts/generate-weak-node-api-injector.ts).
Tests/Examples
- Adds TSFN test addon (packages/node-addon-examples/tests/threadsafe_function/*) and wires into examples index.
- Increases test timeout for example cases (apps/test-app/App.tsx).
Release
- Changeset: minor bump for react-native-node-api.

^{Written by Cursor Bugbot for commit 87a78f2. This will update automatically on new commits. Configure here.}

Copilot

Pull Request Overview

This pull request implements complete thread-safe function support for Node-API, enabling cross-thread communication between native code and JavaScript. The implementation provides all core Node-API threadsafe functions with proper lifecycle management, queueing semantics, and reference counting.

Key changes:

Added ThreadSafeFunction class with full Node-API compatibility including creation, calling, acquire/release, and ref/unref operations
Implemented all seven Node-API threadsafe functions in RuntimeNodeApiAsync.cpp with proper error handling and state management
Added comprehensive test suite based on Node.js official tests to validate functionality across different threading scenarios

Reviewed Changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
packages/host/cpp/ThreadsafeFunction.hpp	Header defining the ThreadSafeFunction class with thread-safe queue management and lifecycle controls
packages/host/cpp/ThreadsafeFunction.cpp	Complete implementation of thread-safe function with global registry, queueing, and finalization logic
packages/host/cpp/RuntimeNodeApiAsync.cpp	Node-API function implementations delegating to ThreadSafeFunction class methods
packages/host/scripts/generate-weak-node-api-injector.ts	Added threadsafe function names to implemented functions list
packages/node-addon-examples/tests/threadsafe_function/*	Test suite files including C++ addon and JavaScript test harness
packages/host/android/CMakeLists.txt	Build configuration updates to include new ThreadsafeFunction source files

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

packages/host/cpp/RuntimeNodeApiAsync.cpp

Copilot · 2025-08-14T11:19:29Z

packages/host/cpp/ThreadsafeFunction.cpp

+// Global registry to map unique IDs to ThreadSafeFunction instances.
+// We use IDs instead of raw pointers to avoid any use-after-free issues.
+static std::unordered_map<std::uintptr_t,
+    std::shared_ptr<callstack::nodeapihost::ThreadSafeFunction>>


The static global registry introduces potential memory management complexity. Consider using a singleton pattern or RAII wrapper to ensure proper cleanup on module unload.

Cleanup is ensured programatically.

Could / should this map be owned by the napi_env?

My understanding is that it would change anything:

Functions are called and referenced using handle napi_threadsafe_function, not using napi_env. Threadsafe function will always use the correct env, the one the function was created for.

I am not aware of any way to detect and cleanup the map when napi_env is destroyed - no change in this aspect.

There will be no memory leaks since smart pointers are used anyway.

I just cannot see benefits from adding this "ownership" layer, but I may be missing something. Could you see any?

that it would change anything

That it would or that it would not?

Should be would not

packages/node-addon-examples/tests/threadsafe_function/CMakeLists.txt

packages/host/cpp/ThreadsafeFunction.cpp

kraenhansen · 2025-08-18T09:11:25Z

packages/host/cpp/RuntimeNodeApiAsync.cpp

  job->state = AsyncJob::State::Cancelled;
  return napi_ok;
 }
+


I wonder if the name of this file needs an update now that it's not "just async work related"? Or of this should go into as separate file? 🤔

I was also thinking about that, finally I decided to put it there since the threadsafe functions in Node-API are called asynchronously and other implementation often group them together. But I am open to change that I move it to the separate file.

I don't have a strong preference either way 👍
If it's a conscious choice, I'm all for that. Just didn't seem that related to me.

shirakaba

Just did a pair-programming session with Kræn and came up with one important change for thread-hopping!

shirakaba · 2025-09-26T14:34:43Z

packages/host/cpp/ThreadsafeFunction.cpp

+  // Hop to JS thread; we drain one item per hop to keep latency predictable
+  // and avoid long monopolization of the JS queue.
+  invoker->invokeAsync([self = shared_from_this()] { self->processQueue(); });


This one-line change was enough to get thread-hopping in NativeScript Node-API working (where before, it was crashing):

Suggested change

// Hop to JS thread; we drain one item per hop to keep latency predictable

// and avoid long monopolization of the JS queue.

invoker->invokeAsync([self = shared_from_this()] { self->processQueue(); });

// Invoke from the current thread. Libraries like NativeScript can wrap a

// JS function in an Objective-C block to be dispatched onto another thread

// (e.g. the main thread, with the intention of accessing the UI), and so we

// should run the JS function on the same thread the Objective-C block was

// dispatched to.

invoker->invokeSync([self = shared_from_this()] { self->processQueue(); });

I was able to do intricate moves back and forth between the JS and main threads, and use JS timers (see screenshot below). It all worked perfectly.

Just came back from the long vacation and saw that, sweet!
I tried that with my reproduction of the problem but it didn't help - looks like my repro conditions were not correct.
I have applied the changes 😊

Unfortunately this change introduced problems to the solution, such as deadlocks, some of them are already fixed, but I will have to revisit the entire PR in the future.

… (temporary)

paradowstack requested review from kraenhansen and Copilot August 14, 2025 11:18

paradowstack added Apple 🍎 Anything related to the Apple platform (iOS, macOS, Cocoapods, Xcode, XCFrameworks, etc.) Android 🤖 Anything related to the Android platform (Gradle, NDK, Android SDK) labels Aug 14, 2025

Copilot AI reviewed Aug 14, 2025

View reviewed changes

kraenhansen reviewed Aug 18, 2025

View reviewed changes

shirakaba requested changes Sep 26, 2025

View reviewed changes

paradowstack added 12 commits September 30, 2025 08:13

feat: Added ThreadsafeFunction class and runtime methods

9d5bde4

feat: Adopted threadsafe functions tests

0678cc9

chore: improved release/abort behaviour

02522c9

chore: changed name + added nodiscard

e17af17

chore: no need to drain queue in callback

18f0b09

chore: minor improvements, improved memory layout

4930fe0

chore: remove debug lines

2879b75

chore: improved comments + cleanup

53b498d

chore: add changeset

2dc446a

chore: deleting not needed cmake file

1150852

chore: add error location

9c04aff

fix: dispatching call to current thread

b9ebf1f

paradowstack force-pushed the kp/threadsafe-functions branch from 3239f2b to b9ebf1f Compare September 30, 2025 06:18

paradowstack marked this pull request as ready for review September 30, 2025 06:18

This comment was marked as outdated.

Sign in to view

paradowstack requested review from shirakaba and kraenhansen September 30, 2025 06:21

paradowstack added 3 commits September 30, 2025 08:25

chore: cleanup of addon.js

185a9c2

fix: add missing include

4055aea

fix: increase timeout for async test examples only for debug purposes…

9de74e6

… (temporary)

This comment was marked as outdated.

Sign in to view

fix: add deadlock prevention mechanism

87a78f2

paradowstack marked this pull request as draft October 2, 2025 06:37

-  // Hop to JS thread; we drain one item per hop to keep latency predictable
-  // and avoid long monopolization of the JS queue.
-  invoker->invokeAsync([self = shared_from_this()] { self->processQueue(); });
+  // Invoke from the current thread. Libraries like NativeScript can wrap a
+  // JS function in an Objective-C block to be dispatched onto another thread
+  // (e.g. the main thread, with the intention of accessing the UI), and so we
+  // should run the JS function on the same thread the Objective-C block was
+  // dispatched to.
+  invoker->invokeSync([self = shared_from_this()] { self->processQueue(); });

Implementation of threadsafe functions #220

Are you sure you want to change the base?

Implementation of threadsafe functions #220

Uh oh!

Conversation

paradowstack commented Aug 14, 2025 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Copilot AI Aug 14, 2025

Choose a reason for hiding this comment

Uh oh!

paradowstack Aug 14, 2025

Choose a reason for hiding this comment

Uh oh!

kraenhansen Aug 18, 2025

Choose a reason for hiding this comment

Uh oh!

paradowstack Aug 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kraenhansen Oct 1, 2025

Choose a reason for hiding this comment

Uh oh!

paradowstack Oct 2, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

kraenhansen Aug 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

paradowstack Aug 18, 2025

Choose a reason for hiding this comment

Uh oh!

kraenhansen Aug 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shirakaba left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shirakaba Sep 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

paradowstack Sep 30, 2025

Choose a reason for hiding this comment

Uh oh!

paradowstack Oct 2, 2025

Choose a reason for hiding this comment

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

Uh oh!

paradowstack commented Aug 14, 2025 •

edited by cursor bot

Loading

paradowstack Aug 18, 2025 •

edited

Loading

kraenhansen Aug 18, 2025 •

edited

Loading

kraenhansen Aug 18, 2025 •

edited

Loading

shirakaba left a comment •

edited

Loading

shirakaba Sep 26, 2025 •

edited

Loading