N-API Threadsafe call asynchronous javascript callback

[gryor]

Version: v10.8.0
Platform: Linux 4.17.11 x86_64 GNU/Linux

By using the new threadsafe functions I am able to call javascript from another thread and return synchronously a value (e.g. a number) from javascript to another thread.

What is the proper way to call a threadsafe function -> pass arguments to javascript -> await for a result -> return the result -> pass the result back to another thread?

[mhdawson]

@gabrielschulhof do you have an existing example you can point @wilhelmmatilainen to? Might make sense to add one to the https://github.com/nodejs/abi-stable-node-addon-examples

[gryor]

I have already accomplished this by getting the returned Promise and then calling its then function with success and fail handlers. I got it working.
It would be nice if there were a function to directly handle a Promise returned from javascript.

napi_promise_then(env, promise, my_success_callback, my_fail_callback);

[gabrielschulhof]

@wilhelmmatilainen you can napi_get_named_property(env, promise, "then", &then_callback), napi_get_named_property(env, promise, "catch", &catch_callback), and napi_get_undefined(env, &undefined), then napi_call_function(env, undefined, then_callback, 1, &my_success_callback, nullptr), but it was my understanding that you wish to convey the result of the call into JavaScript back to the thread which called into JavaScript.

There's no straight-forward way of doing that, because, by definition, the thread-safe function call is asynchronous. So, to convey the result of the call into JavaScript back, your best bet is to create a std::queue<void*> guarded by a node::Mutex, and have the napi_threadsafe_function_call_js store the value in the queue. The thread could then retrieve the value at its convenience.

Of course, if you have multiple secondary threads, you need to know which value on the std::queue<void*> corresponds to the result of which call into JavaScript.

[gryor]

That is exactly how I am doing it. Except the queue has size 1 and it is managed by node.js. Depending on what is needed, the native side blocks or keeps returning EGAIN or EWOULDBLOCK until the result is ready.
If there were more threads than the native module's and node.js, then it could probably be a linked list with a thread id and the queue you mentioned. On access it would travel the short linked list and use the queue specific to exact thread.
Or another option could be loading this simple module with only one thread (+ node.js thread) multiple times. This way the module would always have only one queue.

[gabrielschulhof]

@wilhelmmatilainen can you link to the code in question (if it's open source)?

[gryor]

The project is not at least yet public and there is still problems to be solved until it could be used. However, I could probably strip unnecessary code and leave the meaningful parts if needed. It is still not hard to accomplish.

[gabrielschulhof]

@wilhelmmatilainen please, if you can, that would help a great deal 🙂

[gryor]

Here it is: https://github.com/wilhelmmatilainen/node-addon-api-async-tsf
Please notice that I only did a fast strip down of my actual project, so there might be some unnecessary code or the overall layout might be unnecessary for other projects.

[gabrielschulhof]

@wilhelmmatilainen it looks like you need round-trip asynchronous calling, not just from the secondary thread to the JS thread.

[gryor]

That is correct, as I originally asked.

[gabrielschulhof]

@wilhelmmatilainen if you wish to establish the return value after multiple trips into JS, you need to use napi_wrap() to pass an object into JS and a second binding in which you receive the object back from JS, along with the return value.

secondary thread:
  - creates a pointer to a structure and stores that pointer in
    a local array. The structure contains the data to pass into JS.
    Then it calls napi_call_threadsafe_function.
  -> napi_threadsafe_function_call_js gets called on the loop thread.
    - receives the pointer from the thread and creates a
      new, empty JS object. It uses `napi_wrap()` to place the
      pointer into the JS object, and then it calls js_callback.
    - JS receives the JS object with the native pointer in it
      as well as whatever data was supposed to be part of the
      cross-thread call, and does what it does, passing the JS
      object containing the pointer to whatever callbacks might be
      executed asynchronously.
...
loop thread: some callback that establishes the return value
gets called
  -> calls a binding in your addon, and passes the JS object
     containing the pointer to the binding, along with the
     return value that was established.
     -> the binding retrieves the native pointer and converts
        the return value from a napi_value to some native
        value and writes it into the structure at the pointer.


Meanwhile, the secondary thread occasionally checks the pointer it
created and, when a flag is set inside the structure indicating that,
on the loop thread the second part of the above has happened, it
retrieves the return value and frees the pointer to the structure.

Please let me know if this answers your question!

[gabrielschulhof]

@wilhelmmatilainen is it possible that you share some details of the project in which you are using napi_threadsafe_function? Since the API is currently still experimental, we are gathering real-world usage data on it before we remove its experimental status.

While it's still experimental, we can also tweak the API. Are there any napi_threadsafe_function-related API changes you would like to see?

[gryor]

I am using threadsafe functions for wrapping whole separate programs into node.js modules. This way I have more direct control to the program than an api or some communication layer provides if there even is such thing. The programs may be asynchronous or not and mostly some parts are while there is also synchronous calls. So, the calls from the program to javascript should always be possibly asynchronous from node.js perspective and when returning the value the program should behave correctly regardless whether it expected the call to be asynchronous or synchronous. Basically this means just blocking for synchronous operation and for asynchronous operation it means returning EAGAIN or EWOULDBLOCK until the javascript call has returned completely with the promises resolved or rejected. Maybe if there were a simple function to call javascript from separate thread "directly" with one function and the final result would be retrieved asynchronously when ready. If a promise was returned then the promise would automatically be resolved or rejected before implying the call being ready. ```c call_js(env, my_function, argc, argv, &result) while(result->ready == 0) do_something_else_or_just_wait_idle() // result is now ready and if a promise is returned, the promise is resolved or rejected. Meaning that result has the final value or error, never another promise. // OR // save non-resolved result promise for later resolution and return EGAIN or EWOULDBLOCK ```

[gabrielschulhof]

@wilhelmmatilainen I have created an example showing an asynchronous round trip:

https://github.com/gabrielschulhof/abi-stable-node-addon-examples/tree/tsfn_round_trip/thread_safe_function_round_trip/node-api

Do you think we should incorporate any of the functionality shown in the example into a new N-API?

[gabrielschulhof]

@wilhelmmatilainen the round trip example has now landed on master in nodejs/node-addon-examples:

https://github.com/nodejs/node-addon-examples/tree/master/thread_safe_function_round_trip/node-api

Does it serve your needs?

[gryor]

Yes and thank you for making the example.

[gabrielschulhof]

Excellent 🙂