Skip to content

feat: add support for requiring basic finalizers #1568

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Sep 19, 2024
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Address review comments
- Use passive voice in existing and new docs
- Revert unnecessary change
  • Loading branch information
KevinEady committed Sep 9, 2024
commit 23b57cc93946df51f30cbfada61213be14f61421
6 changes: 3 additions & 3 deletions doc/finalization.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,9 @@ provide more efficient memory management, optimizations, improved execution, or
other benefits.

In general, it is best to use basic finalizers whenever possible (eg. when
access to JavaScript is _not_ needed). To ensure that all finalizers are basic
finalizers at compile-time, define the `NODE_ADDON_API_REQUIRE_BASIC_FINALIZERS`
preprocessor directive.
access to JavaScript is _not_ needed). The
`NODE_ADDON_API_REQUIRE_BASIC_FINALIZERS` preprocessor directive can be defined
to ensure that all finalizers are basic.

## Finalizers

Expand Down
17 changes: 9 additions & 8 deletions doc/setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -81,22 +81,23 @@ To use **Node-API** in a native module:
At build time, the Node-API back-compat library code will be used only when the
targeted node version *does not* have Node-API built-in.

The preprocessor directive `NODE_ADDON_API_DISABLE_DEPRECATED` can be defined at
compile time before including `napi.h` to skip the definition of deprecated APIs.
The `NODE_ADDON_API_DISABLE_DEPRECATED` preprocessor directive can be defined at
compile time before including `napi.h` to skip the definition of deprecated
APIs.

By default, throwing an exception on a terminating environment (eg. worker
threads) will cause a fatal exception, terminating the Node process. This is to
provide feedback to the user of the runtime error, as it is impossible to pass
the error to JavaScript when the environment is terminating. In order to bypass
this behavior such that the Node process will not terminate, define the
preprocessor directive `NODE_API_SWALLOW_UNTHROWABLE_EXCEPTIONS`.
the error to JavaScript when the environment is terminating. The
`NODE_API_SWALLOW_UNTHROWABLE_EXCEPTIONS` preprocessor directive can be defined
to bypass this behavior, such that the Node process will not terminate.

Various Node-API constructs provide a mechanism to run a callback in response to
a garbage collection event of that object. These callbacks are called
[_finalizers_]. Some finalizers have restrictions on the type of Node-APIs
available within the callback. node-addon-api provides convenience helpers that
bypass this limitation, but may cause the add-on to run less efficiently. To
disable the convenience helpers, define the preprocessor directive
`NODE_ADDON_API_REQUIRE_BASIC_FINALIZERS`.
bypass this limitation, but may cause the add-on to run less efficiently. The
`NODE_ADDON_API_REQUIRE_BASIC_FINALIZERS` preprocessor directive can be defined
to disable the convenience helpers.

[_finalizers_]: ./finalization.md
4 changes: 2 additions & 2 deletions napi-inl.h
Original file line number Diff line number Diff line change
Expand Up @@ -205,7 +205,7 @@ struct FinalizeData {
});
}

#if defined(NODE_API_EXPERIMENTAL_HAS_POST_FINALIZER)
#ifdef NODE_API_EXPERIMENTAL_HAS_POST_FINALIZER
template <typename F = Finalizer,
typename = std::enable_if_t<
!std::is_invocable_v<F, node_api_nogc_env, T*>>,
Expand Down Expand Up @@ -240,7 +240,7 @@ struct FinalizeData {
});
}

#if defined(NODE_API_EXPERIMENTAL_HAS_POST_FINALIZER)
#ifdef NODE_API_EXPERIMENTAL_HAS_POST_FINALIZER
template <typename F = Finalizer,
typename = std::enable_if_t<
!std::is_invocable_v<F, node_api_nogc_env, T*, Hint*>>,
Expand Down