diff options
author | Anna Henningsen <anna@addaleax.net> | 2020-07-31 03:10:14 +0300 |
---|---|---|
committer | Anna Henningsen <anna@addaleax.net> | 2020-08-07 01:02:02 +0300 |
commit | 22cbbcf9d9374d4b663bf1409f292212fa57623a (patch) | |
tree | 59a9e22bdae3900b961e4c58f53aa6c9b0a511bd /doc/api/n-api.md | |
parent | a4e1755df2f9bb8c712d7ca767a5944d9d71e33b (diff) |
n-api,src: provide asynchronous cleanup hooks
Sometimes addons need to perform cleanup actions, for example
closing libuv handles or waiting for requests to finish, that
cannot be performed synchronously.
Add C++ API and N-API functions that allow providing such
asynchronous cleanup hooks.
Fixes: https://github.com/nodejs/node/issues/34567
PR-URL: https://github.com/nodejs/node/pull/34572
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Gabriel Schulhof <gabriel.schulhof@intel.com>
Diffstat (limited to 'doc/api/n-api.md')
-rw-r--r-- | doc/api/n-api.md | 53 |
1 files changed, 52 insertions, 1 deletions
diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 5a90f4c81fc..958cdb6a8ae 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -1550,10 +1550,12 @@ and will lead the process to abort. The hooks will be called in reverse order, i.e. the most recently added one will be called first. -Removing this hook can be done by using `napi_remove_env_cleanup_hook`. +Removing this hook can be done by using [`napi_remove_env_cleanup_hook`][]. Typically, that happens when the resource for which this hook was added is being torn down anyway. +For asynchronous cleanup, [`napi_add_async_cleanup_hook`][] is available. + #### napi_remove_env_cleanup_hook <!-- YAML added: v10.2.0 @@ -1573,6 +1575,52 @@ need to be exact matches. The function must have originally been registered with `napi_add_env_cleanup_hook`, otherwise the process will abort. +#### napi_add_async_cleanup_hook +<!-- YAML +added: REPLACEME +--> + +> Stability: 1 - Experimental + +```c +NAPI_EXTERN napi_status napi_add_async_cleanup_hook( + napi_env env, + void (*fun)(void* arg, void(* cb)(void*), void* cbarg), + void* arg, + napi_async_cleanup_hook_handle* remove_handle); +``` + +Registers `fun` as a function to be run with the `arg` parameter once the +current Node.js environment exits. Unlike [`napi_add_env_cleanup_hook`][], +the hook is allowed to be asynchronous in this case, and must invoke the passed +`cb()` function with `cbarg` once all asynchronous activity is finished. + +Otherwise, behavior generally matches that of [`napi_add_env_cleanup_hook`][]. + +If `remove_handle` is not `NULL`, an opaque value will be stored in it +that must later be passed to [`napi_remove_async_cleanup_hook`][], +regardless of whether the hook has already been invoked. +Typically, that happens when the resource for which this hook was added +is being torn down anyway. + +#### napi_remove_async_cleanup_hook +<!-- YAML +added: REPLACEME +--> + +> Stability: 1 - Experimental + +```c +NAPI_EXTERN napi_status napi_remove_async_cleanup_hook( + napi_env env, + napi_async_cleanup_hook_handle remove_handle); +``` + +Unregisters the cleanup hook corresponding to `remove_handle`. This will prevent +the hook from being executed, unless it has already started executing. +This must be called on any `napi_async_cleanup_hook_handle` value retrieved +from [`napi_add_async_cleanup_hook`][]. + ## Module registration N-API modules are registered in a manner similar to other modules except that instead of using the `NODE_MODULE` macro the following @@ -5710,6 +5758,7 @@ This API may only be called from the main thread. [`Worker`]: worker_threads.html#worker_threads_class_worker [`global`]: globals.html#globals_global [`init` hooks]: async_hooks.html#async_hooks_init_asyncid_type_triggerasyncid_resource +[`napi_add_async_cleanup_hook`]: #n_api_napi_add_async_cleanup_hook [`napi_add_env_cleanup_hook`]: #n_api_napi_add_env_cleanup_hook [`napi_add_finalizer`]: #n_api_napi_add_finalizer [`napi_async_complete_callback`]: #n_api_napi_async_complete_callback @@ -5750,6 +5799,8 @@ This API may only be called from the main thread. [`napi_queue_async_work`]: #n_api_napi_queue_async_work [`napi_reference_ref`]: #n_api_napi_reference_ref [`napi_reference_unref`]: #n_api_napi_reference_unref +[`napi_remove_async_cleanup_hook`]: #n_api_napi_remove_async_cleanup_hook +[`napi_remove_env_cleanup_hook`]: #n_api_napi_remove_env_cleanup_hook [`napi_set_instance_data`]: #n_api_napi_set_instance_data [`napi_set_property`]: #n_api_napi_set_property [`napi_threadsafe_function_call_js`]: #n_api_napi_threadsafe_function_call_js |