@@ -5122,7 +5122,9 @@ The `context` given during the call to `napi_create_threadsafe_function()` can
51225122be retrieved from any thread with a call to
51235123`napi_get_threadsafe_function_context()`.
51245124
5125- `napi_call_threadsafe_function()` can then be used for initiating a call into
5125+ ### Calling a thread-safe function
5126+
5127+ `napi_call_threadsafe_function()` can be used for initiating a call into
51265128JavaScript. `napi_call_threadsafe_function()` accepts a parameter which controls
51275129whether the API behaves blockingly. If set to `napi_tsfn_nonblocking`, the API
51285130behaves non-blockingly, returning `napi_queue_full` if the queue was full,
@@ -5154,6 +5156,8 @@ Node.js process exits while there is a thread-safe function still active.
51545156It is not necessary to call into JavaScript via `napi_make_callback()` because
51555157N-API runs `call_js_cb` in a context appropriate for callbacks.
51565158
5159+ ### Reference counting of thread-safe functions
5160+
51575161Threads can be added to and removed from a `napi_threadsafe_function` object
51585162during its existence. Thus, in addition to specifying an initial number of
51595163threads upon creation, `napi_acquire_threadsafe_function` can be called to
@@ -5173,7 +5177,10 @@ reason, do not make use of a thread-safe function
51735177after receiving a return value of `napi_closing` in response to a call to
51745178`napi_call_threadsafe_function`. Data associated with the
51755179`napi_threadsafe_function` can be freed in its `napi_finalize` callback which
5176- was passed to `napi_create_threadsafe_function()`.
5180+ was passed to `napi_create_threadsafe_function()`. The parameter
5181+ `initial_thread_count` of `napi_create_threadsafe_function` marks the initial
5182+ number of aquisitions of the thread-safe functions, instead of calling
5183+ `napi_acquire_threadsafe_function` multiple times at creation.
51775184
51785185Once the number of threads making use of a `napi_threadsafe_function` reaches
51795186zero, no further threads can start making use of it by calling
@@ -5193,13 +5200,19 @@ of `napi_closing` from `napi_call_threadsafe_function()` a thread must make no
51935200further use of the thread-safe function because it is no longer guaranteed to
51945201be allocated.**
51955202
5203+ ### Deciding whether to keep the process running
5204+
51965205Similarly to libuv handles, thread-safe functions can be "referenced" and
51975206"unreferenced". A "referenced" thread-safe function will cause the event loop on
51985207the thread on which it is created to remain alive until the thread-safe function
51995208is destroyed. In contrast, an "unreferenced" thread-safe function will not
52005209prevent the event loop from exiting. The APIs `napi_ref_threadsafe_function` and
52015210`napi_unref_threadsafe_function` exist for this purpose.
52025211
5212+ Neither does `napi_unref_threadsafe_function` mark the thread-safe functions as
5213+ able to be destroyed nor does `napi_ref_threadsafe_function` prevent it from
5214+ being destroyed.
5215+
52035216### napi_create_threadsafe_function
52045217
52055218<!-- YAML
@@ -5237,8 +5250,9 @@ napi_create_threadsafe_function(napi_env env,
52375250 the kind of resource that is being provided for diagnostic information exposed
52385251 by the `async_hooks` API.
52395252* `[in] max_queue_size`: Maximum size of the queue. `0` for no limit.
5240- * `[in] initial_thread_count`: The initial number of threads, including the main
5241- thread, which will be making use of this function.
5253+ * `[in] initial_thread_count`: The initial number of acquisitions, i.e. the
5254+ initial number of threads, including the main thread, which will be making use
5255+ of this function.
52425256* `[in] thread_finalize_data`: Optional data to be passed to `thread_finalize_cb`.
52435257* `[in] thread_finalize_cb`: Optional function to call when the
52445258 `napi_threadsafe_function` is being destroyed.
@@ -5380,6 +5394,11 @@ This API is used to indicate that the event loop running on the main thread
53805394should not exit until `func` has been destroyed. Similar to [`uv_ref`][] it is
53815395also idempotent.
53825396
5397+ Neither does `napi_unref_threadsafe_function` mark the thread-safe functions as
5398+ able to be destroyed nor does `napi_ref_threadsafe_function` prevent it from
5399+ being destroyed. `napi_acquire_threadsafe_function` and
5400+ `napi_release_threadsafe_function` are available for that purpose.
5401+
53835402This API may only be called from the main thread.
53845403
53855404### napi_unref_threadsafe_function
0 commit comments