From 008242af3048368d6e26aca4b0dc0f7f300593c6 Mon Sep 17 00:00:00 2001 From: legendecas Date: Sun, 14 Jun 2020 15:44:19 +0800 Subject: [PATCH 1/2] doc: clarifying thread safe function references --- doc/api/n-api.md | 27 +++++++++++++++++++++++---- 1 file changed, 23 insertions(+), 4 deletions(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 58e79c6e9933de..47e48bb93ccfa4 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -5119,7 +5119,9 @@ The `context` given during the call to `napi_create_threadsafe_function()` can be retrieved from any thread with a call to `napi_get_threadsafe_function_context()`. -`napi_call_threadsafe_function()` can then be used for initiating a call into +### Calling a thread-safe function + +`napi_call_threadsafe_function()` can be used for initiating a call into JavaScript. `napi_call_threadsafe_function()` accepts a parameter which controls whether the API behaves blockingly. If set to `napi_tsfn_nonblocking`, the API behaves non-blockingly, returning `napi_queue_full` if the queue was full, @@ -5151,6 +5153,8 @@ Node.js process exits while there is a thread-safe function still active. It is not necessary to call into JavaScript via `napi_make_callback()` because N-API runs `call_js_cb` in a context appropriate for callbacks. +### Reference counting of thread-safe functions + Threads can be added to and removed from a `napi_threadsafe_function` object during its existence. Thus, in addition to specifying an initial number of threads upon creation, `napi_acquire_threadsafe_function` can be called to @@ -5170,7 +5174,10 @@ reason, do not make use of a thread-safe function after receiving a return value of `napi_closing` in response to a call to `napi_call_threadsafe_function`. Data associated with the `napi_threadsafe_function` can be freed in its `napi_finalize` callback which -was passed to `napi_create_threadsafe_function()`. +was passed to `napi_create_threadsafe_function()`. The parameter +`initial_thread_count` of `napi_create_threadsafe_function` marks the initial +number of aquisitions of the thread-safe functions, instead of calling +`napi_acquire_threadsafe_function` multiple times at creation. Once the number of threads making use of a `napi_threadsafe_function` reaches zero, no further threads can start making use of it by calling @@ -5190,6 +5197,8 @@ of `napi_closing` from `napi_call_threadsafe_function()` a thread must make no further use of the thread-safe function because it is no longer guaranteed to be allocated.** +### Deciding whether to keep the process running + Similarly to libuv handles, thread-safe functions can be "referenced" and "unreferenced". A "referenced" thread-safe function will cause the event loop on the thread on which it is created to remain alive until the thread-safe function @@ -5197,6 +5206,10 @@ is destroyed. In contrast, an "unreferenced" thread-safe function will not prevent the event loop from exiting. The APIs `napi_ref_threadsafe_function` and `napi_unref_threadsafe_function` exist for this purpose. +Neither does `napi_unref_threadsafe_function` mark the thread-safe functions as +able to be destroyed nor does `napi_ref_threadsafe_function` prevent it from +being destroyed. + ### napi_create_threadsafe_function