Skip to content

Commit 008242a

Browse files
committed
doc: clarifying thread safe function references
1 parent 14d012e commit 008242a

File tree

1 file changed

+23
-4
lines changed

1 file changed

+23
-4
lines changed

doc/api/n-api.md

Lines changed: 23 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5119,7 +5119,9 @@ The `context` given during the call to `napi_create_threadsafe_function()` can
51195119
be retrieved from any thread with a call to
51205120
`napi_get_threadsafe_function_context()`.
51215121

5122-
`napi_call_threadsafe_function()` can then be used for initiating a call into
5122+
### Calling a thread-safe function
5123+
5124+
`napi_call_threadsafe_function()` can be used for initiating a call into
51235125
JavaScript. `napi_call_threadsafe_function()` accepts a parameter which controls
51245126
whether the API behaves blockingly. If set to `napi_tsfn_nonblocking`, the API
51255127
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.
51515153
It is not necessary to call into JavaScript via `napi_make_callback()` because
51525154
N-API runs `call_js_cb` in a context appropriate for callbacks.
51535155

5156+
### Reference counting of thread-safe functions
5157+
51545158
Threads can be added to and removed from a `napi_threadsafe_function` object
51555159
during its existence. Thus, in addition to specifying an initial number of
51565160
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
51705174
after receiving a return value of `napi_closing` in response to a call to
51715175
`napi_call_threadsafe_function`. Data associated with the
51725176
`napi_threadsafe_function` can be freed in its `napi_finalize` callback which
5173-
was passed to `napi_create_threadsafe_function()`.
5177+
was passed to `napi_create_threadsafe_function()`. The parameter
5178+
`initial_thread_count` of `napi_create_threadsafe_function` marks the initial
5179+
number of aquisitions of the thread-safe functions, instead of calling
5180+
`napi_acquire_threadsafe_function` multiple times at creation.
51745181

51755182
Once the number of threads making use of a `napi_threadsafe_function` reaches
51765183
zero, no further threads can start making use of it by calling
@@ -5190,13 +5197,19 @@ of `napi_closing` from `napi_call_threadsafe_function()` a thread must make no
51905197
further use of the thread-safe function because it is no longer guaranteed to
51915198
be allocated.**
51925199

5200+
### Deciding whether to keep the process running
5201+
51935202
Similarly to libuv handles, thread-safe functions can be "referenced" and
51945203
"unreferenced". A "referenced" thread-safe function will cause the event loop on
51955204
the thread on which it is created to remain alive until the thread-safe function
51965205
is destroyed. In contrast, an "unreferenced" thread-safe function will not
51975206
prevent the event loop from exiting. The APIs `napi_ref_threadsafe_function` and
51985207
`napi_unref_threadsafe_function` exist for this purpose.
51995208

5209+
Neither does `napi_unref_threadsafe_function` mark the thread-safe functions as
5210+
able to be destroyed nor does `napi_ref_threadsafe_function` prevent it from
5211+
being destroyed.
5212+
52005213
### napi_create_threadsafe_function
52015214

52025215
<!-- YAML
@@ -5234,8 +5247,9 @@ napi_create_threadsafe_function(napi_env env,
52345247
the kind of resource that is being provided for diagnostic information exposed
52355248
by the `async_hooks` API.
52365249
* `[in] max_queue_size`: Maximum size of the queue. `0` for no limit.
5237-
* `[in] initial_thread_count`: The initial number of threads, including the main
5238-
thread, which will be making use of this function.
5250+
* `[in] initial_thread_count`: The initial number of acquisitions, i.e. initial
5251+
number of threads, including the main thread, which will be making use of this
5252+
function.
52395253
* `[in] thread_finalize_data`: Optional data to be passed to `thread_finalize_cb`.
52405254
* `[in] thread_finalize_cb`: Optional function to call when the
52415255
`napi_threadsafe_function` is being destroyed.
@@ -5377,6 +5391,11 @@ This API is used to indicate that the event loop running on the main thread
53775391
should not exit until `func` has been destroyed. Similar to [`uv_ref`][] it is
53785392
also idempotent.
53795393

5394+
Neither does `napi_unref_threadsafe_function` mark the thread-safe functions as
5395+
able to be destroyed nor does `napi_ref_threadsafe_function` prevent it from
5396+
being destroyed. `napi_acquire_threadsafe_function` and
5397+
`napi_release_threadsafe_function` are available for that purpose.
5398+
53805399
This API may only be called from the main thread.
53815400

53825401
### napi_unref_threadsafe_function

0 commit comments

Comments
 (0)