@@ -5119,7 +5119,9 @@ The `context` given during the call to `napi_create_threadsafe_function()` can
5119
5119
be retrieved from any thread with a call to
5120
5120
`napi_get_threadsafe_function_context()`.
5121
5121
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
5123
5125
JavaScript. `napi_call_threadsafe_function()` accepts a parameter which controls
5124
5126
whether the API behaves blockingly. If set to `napi_tsfn_nonblocking`, the API
5125
5127
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.
5151
5153
It is not necessary to call into JavaScript via `napi_make_callback()` because
5152
5154
N-API runs `call_js_cb` in a context appropriate for callbacks.
5153
5155
5156
+ ### Reference counting of thread-safe functions
5157
+
5154
5158
Threads can be added to and removed from a `napi_threadsafe_function` object
5155
5159
during its existence. Thus, in addition to specifying an initial number of
5156
5160
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
5170
5174
after receiving a return value of `napi_closing` in response to a call to
5171
5175
`napi_call_threadsafe_function`. Data associated with the
5172
5176
`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.
5174
5181
5175
5182
Once the number of threads making use of a `napi_threadsafe_function` reaches
5176
5183
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
5190
5197
further use of the thread-safe function because it is no longer guaranteed to
5191
5198
be allocated.**
5192
5199
5200
+ ### Deciding whether to keep the process running
5201
+
5193
5202
Similarly to libuv handles, thread-safe functions can be "referenced" and
5194
5203
"unreferenced". A "referenced" thread-safe function will cause the event loop on
5195
5204
the thread on which it is created to remain alive until the thread-safe function
5196
5205
is destroyed. In contrast, an "unreferenced" thread-safe function will not
5197
5206
prevent the event loop from exiting. The APIs `napi_ref_threadsafe_function` and
5198
5207
`napi_unref_threadsafe_function` exist for this purpose.
5199
5208
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
+
5200
5213
### napi_create_threadsafe_function
5201
5214
5202
5215
<!-- YAML
@@ -5234,8 +5247,9 @@ napi_create_threadsafe_function(napi_env env,
5234
5247
the kind of resource that is being provided for diagnostic information exposed
5235
5248
by the `async_hooks` API.
5236
5249
* `[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.
5239
5253
* `[in] thread_finalize_data`: Optional data to be passed to `thread_finalize_cb`.
5240
5254
* `[in] thread_finalize_cb`: Optional function to call when the
5241
5255
`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
5377
5391
should not exit until `func` has been destroyed. Similar to [`uv_ref`][] it is
5378
5392
also idempotent.
5379
5393
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
+
5380
5399
This API may only be called from the main thread.
5381
5400
5382
5401
### napi_unref_threadsafe_function
0 commit comments