Need clarity on parameters to the API napi_create_threadsafe_function

[varun-elear]

I have a C library. When say_hello() in the library is invoked, it spawns a thread t1 to compute some task T on it and immediately returns from the called function. After the task T has been completed, the callback function received as input to say_hello() is called.

I am using N-API so that the function say_hello() can be used by JS via a napi layer. Since, the thread t1 will call a function in the napi layer as callback, I have to use threadsafe function to transfer control to the main thread so I can call JS functions.

1. I understood that async_work provided by N-API cannot be used without modifying the C library that I have because threads are created in the C layer and not in the napi layer. Is that correct?

My JS code calls napi_init_app() which creates a threadsafe function. Then napi_say_hello() is called from JS which in turn calls say_hello() and returns.

A napi_ref to the JS callback function js_hello_callback() which was passed as parameter to napi_say_hello() is passed down to the C layer so that it can be retrieved back when the napi_hello_callback() is called by the thread t1.

napi_hello_callback() calls the API napi_call_threadsafe_function() and passes the napi_ref to js_hello_callback() along. call_js_cb() is then invoked which retrieves js_hello_callback() as napi_value from napi_ref and invokes it.

I do not do napi_acquire_threadsafe_function or napi_release_threadsafe_function for every call to the threadsafe function and only call napi_release_threadsafe_function when JS layer calls napi_destroy_app().

I have the following queries regarding the threadsafe APIs:

2. func (The JavaScript function to call from another thread) - This is a mandatory parameter but I cannot find a use case for this in the above scenario because napi_say_hello() can be called each time with a different callback. Am I missing something or should this be optional?
3. initial_thread_count - The number of times napi_say_hello() will be called or the number of threads which will call it is unknown to me when I am creating the threadsafe function. So, I am passing 1 as the value and neither acquiring or releasing before napi_destroy_app() is called. Why do we actually need this count?
4. context - Also, this could be of more use if we could store different context for each call. Could you please provide some example for utilising this parameter.

I have the following queries regarding my approach:

5. Is creating one threadsafe function for each function similar to say_hello(), the right approach?
6. Am I creating and releasing the threadsafe function at the right time?
7. Could I use a better approach for my use case.

[gabrielschulhof]

If the C library you use creates threads on its own, and doesn't expose the entry point function of the thread, then async_work cannot be used.

The general concept behind napi_threadsafe_function is that it converts a napi_value that holds a JavaScript function in such a way that the function can be called from any thread, but only if you use napi_call_threadsafe_function().

The initial_thread_count refers to the number of threads that will be calling napi_call_threadsafe_function() using the thread-safe function, including the JavaScript thread, already running at the time the function is created. napi_acquire_threadsafe_function() increments this thread count, and napi_release_threadsafe_function() decrements this thread count after creation. You would call these functions when you know that a new thread will start making calls to napi_call_threadsafe_function() or, conversely, when an old thread will never again make calls to napi_call_threadsafe_function(). When this count reaches zero, the thread-safe function will "shut down", meaning that it is no longer safe to use, because it may have been deallocated At that point, all threads should either have called napi_release_threadsafe_function() or should have received napi_tsfn_closing in response to napi_call_threadsafe_function().

In terms of whether to use multiple thread-safe functions, although on the surface it appears that each thread-safe function is merely a JavaScript function exposed to secondary threads, making that possible involves the use of a lot of libuv resources (an async handle, an idle handle, a mutex, and a condition variable if the queue is finite). So, if you can use a single thread-safe function and use a dispatcher on the JavaScript side, that would probably be a more sparing use of the thread-safe function.

[varun-elear]

Does that also mean that napi_async_context can't be used in the above mentioned scenario and threadsafe_function is the only option?

Once I call napi_call_threadsafe_function() from any thread, the control will pass to the main thread and either the associated JavaScript function or call_js_cb will be executed depending upon the parameters passed to napi_call_threadsafe_function(). The execution of these functions will take place on the main thread, right?

[gabrielschulhof]

IIUC napi_async_context is just a descriptive framework to identify asynchronous operations without actually giving you any primitives with which to implement or control them. So, I think napi_threadsafe_function is your only option.

When you call napi_call_threadsafe_function() it returns right away (unless you have a finite queue and you choose blocking operation), and call_js_cb will eventually be invoked on the main thread. The number of times you call napi_call_threadsafe_function() equals the number of times call_js_cb will be invoked on the main thread.

call_js_cb receives the original napi_value from which you constructed the napi_threadsafe_function (usually called js_cb), the void* which you passed to napi_call_threadsafe_function(), and the void* context which you passed to napi_create_threadsafe_function(). Inside call_js_cb you basically construct a napi_value argv[n] from the void* data and then you napi_call_function(..., js_cb, argv, argv, ...).

[gabrielschulhof]

... also, if you allocate the void* data on the secondary thread, then call_js_cb is a good place to free it, unless you need it later on somewhere.

[gabrielschulhof]

@varun-elear hopefully my explanation in the previous comments provided sufficient clarification. Please re-open this issue if you need more help with napi_threadsafe_function.

[asfernandes]

What I don't understand: an initial thread count is passed, acquire increments and release decrements. How a correct number of aquire/release will make the thread count 0?