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) inRuntimeNodeApiAsync.cpp
Added a newThreadSafeFunction 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:

Adoptednode.js test

Note

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

Host Runtime (C++): Node-API thread-safe functions
- AddsThreadSafeFunction implementation (packages/host/cpp/ThreadsafeFunction.{hpp,cpp}) with queueing, ref/release, finalize, and context retrieval.
- Exposesnapi_* TSFN APIs inRuntimeNodeApiAsync.{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 forreact-native-node-api.

^{Written byCursor Bugbot for commit87a78f2. This will update automatically on new commits. Configurehere.}

paradowstack requested review fromCopilot andkraenhansen

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

CopilotAI reviewed

Aug 14, 2025

View reviewed changes

Copy link

Contributor

CopilotAI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

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 orlearn how to get started.}

packages/host/cpp/RuntimeNodeApiAsync.cppShow resolvedHide resolved

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>>

Copy link

CopilotAIAug 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

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

Copilot uses AI. Check for mistakes.

Copy link

ContributorAuthor

paradowstackAug 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Cleanup is ensured programatically.

Copy link

Collaborator

kraenhansenAug 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Could / should this map be owned by thenapi_env?

Copy link

ContributorAuthor

paradowstackAug 18, 2025•
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

My understanding is that it would change anything:

Functions are called and referenced using handlenapi_threadsafe_function, not usingnapi_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 whennapi_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?

Copy link

Collaborator

kraenhansenOct 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

that it would change anything

That it would or that it wouldnot?

Copy link

ContributorAuthor

paradowstackOct 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Should bewould not

packages/node-addon-examples/tests/threadsafe_function/CMakeLists.txt OutdatedShow resolvedHide resolved

packages/host/cpp/ThreadsafeFunction.cpp OutdatedShow resolvedHide resolved

kraenhansen reviewed

Aug 18, 2025

View reviewed changes

packages/host/cpp/RuntimeNodeApiAsync.cpp

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

Copy link

Collaborator

kraenhansenAug 18, 2025•
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

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? 🤔

Copy link

ContributorAuthor

paradowstackAug 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

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.

Copy link

Collaborator

kraenhansenAug 18, 2025•
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

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 requested changes

Sep 26, 2025

View reviewed changes

Copy link

Collaborator

shirakaba left a comment•
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

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

packages/host/cpp/ThreadsafeFunction.cpp Outdated

Comment on lines 142 to 144

		// 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(); });

Copy link

Collaborator

shirakabaSep 26, 2025•
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

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.

Copy link

ContributorAuthor

paradowstackSep 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

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 😊

Copy link

ContributorAuthor

paradowstackOct 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

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.

paradowstack added12 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 thekp/threadsafe-functions branch from3239f2b tob9ebf1fCompare

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.

paradowstack requested review fromkraenhansen andshirakaba

September 30, 2025 06:21

paradowstack added3 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.

fix: add deadlock prevention mechanism

87a78f2

paradowstack marked this pull request as draft

October 2, 2025 06:37

fix: solved deadlock problem in finalization

c79bcd8

Labels

Android 🤖

Anything related to the Android platform (Gradle, NDK, Android SDK)

Apple 🍎

Anything related to the Apple platform (iOS, macOS, Cocoapods, Xcode, XCFrameworks, etc.)

Movatterモバイル変換

Implementation of threadsafe functions#220

Are you sure you want to change the base?

Implementation of threadsafe functions#220

Uh oh!

Conversation

paradowstack commentedAug 14, 2025• edited by cursorbotLoading Uh oh!There was an error while loading.Please reload this page.

Uh oh!

Uh oh!

CopilotAI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

CopilotAIAug 14, 2025

Choose a reason for hiding this comment

Uh oh!

paradowstackAug 14, 2025

Choose a reason for hiding this comment

Uh oh!

kraenhansenAug 18, 2025

Choose a reason for hiding this comment

Uh oh!

paradowstackAug 18, 2025• editedLoading Uh oh!There was an error while loading.Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kraenhansenOct 1, 2025

Choose a reason for hiding this comment

Uh oh!

paradowstackOct 2, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

kraenhansenAug 18, 2025• editedLoading Uh oh!There was an error while loading.Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

paradowstackAug 18, 2025

Choose a reason for hiding this comment

Uh oh!

kraenhansenAug 18, 2025• editedLoading 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• editedLoading Uh oh!There was an error while loading.Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shirakabaSep 26, 2025• editedLoading Uh oh!There was an error while loading.Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

paradowstackSep 30, 2025

Choose a reason for hiding this comment

Uh oh!

paradowstackOct 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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

paradowstack commentedAug 14, 2025•
edited by cursorbot
Loading

paradowstackAug 18, 2025•
edited
Loading

kraenhansenAug 18, 2025•
edited
Loading

kraenhansenAug 18, 2025•
edited
Loading

shirakaba left a comment•
edited
Loading

shirakabaSep 26, 2025•
edited
Loading