Node-API: Proposal for new strong and weak pointers

[vmoroz]

Currently the Node-API offers two types of pointers to JS values: napi_value and napi_ref.

• The napi_value points to a temporary value that is typically kept in call stack. It can point to any JavaScript value type including null, undefined, number, bool, string, object, etc. It is used by all Node-API functions which manipulate JS values. It is very efficient and offers a virtually direct access to JS engine values. The main drawback is that it cannot be kept around as a field in a native class.
• The napi_ref is a ref-counted napi_value holder that is intended to address the napi_value transitive nature and to allow keeping it as a field in native classes. But the napi_ref tries to do too much and it causes some issues and unexpected behavior:
  • When the ref count goes to zero, the napi_ref is becoming a weak reference instead of being deleted.
  • Since any napi_ref could become a weak reference, and weak references work only with objects, the napi_ref can only wrap up napi_value of object types.
  • Developers are expected to delete the napi_ref explicitly. It can be error prone if the ref count is not zero and some other code still keeps the reference.
  • The ref count is not atomic and it prevents keeping and releasing napi_ref in another thread.
  • The weak references cannot be ref counted and thus only one weak reference is safe to keep.

The proposal is to implement new ref-counted napi_value holders that are aligned with the behavior found in the C++ standard std::shared_ptr and std::weak_ptr. These new pointers would have the following features:

• Ref count is atomic. While the ref count can be changed from any thread, the pointer deletion/finalization always happens in JS thread.
• The strong/shared pointer is deleted when the ref count goes to zero. There is no explicit deletion.
• The weak pointer will have its own weak-reference counter to support multiple safe weak references to the same napi_value. When this ref count goes to zero, we delete the internal structure pointed by the weak ptr. It mirrors the strong pointer behavior.
• The strong pointer can wrap napi_value of any type.
• The weak pointer should have semantic similar to the JS WeakRef. It means that it can only wrap objects.
• We can add callbacks to get notified when a strong or weak pointer ref count goes to zero. This can be different from the finalizers that are called when a related JS object is finalized by GC. They can be useful when the wrapping C++ class needs to do some extra clean up.

These new types could be called napi_shared_ptr and napi_weak_ptr.
As an alternative they could be called napi_strong_ref and napi_weak_ref.

I was playing with a new version of napi_ref to support Meta's JSI API implementation on top of the Node-API with the behavior described above. The reference is called napi_ext_ref: js_native_ext_api.h . The same napi_ext_ref is used for the strong and weak references. It works, but having two different types could be more explicit. Though, both types have the same set of operations: increment/decrement ref count and to get the wrapped napi_value.

[mhdawson]

Sorry the last few weeks have been busy for me, will try to comment soon.

[mhdawson]

I took a read through. Might be good to have you talk us through the APIs and the motivation in the next Node-API team meeting.

[mhdawson]

commented on the related PR

[kisg]

Hi @vmoroz,

is this JSI implementation public by any chance?

Thank you,
Gergely

[vmoroz]

@kisg , yes, the latest code is a part of the react-native-windows repo. See: NodeApiJsiRuntime.h and NodeApiJsiRuntime.cpp . It still uses Node-API extensions. I am considering to create an implementation that can work without these extensions and be in a separate repo.

Currently, we have implementation of Node-API for the V8 DLL engine based on Node.js code and for the Hermes engine DLL. They both have the extensions implemented and pass all JSI unit tests against their copy of JSI for Node-API.