Skip to content

doc: add inline comment hints on finalizer signatures #1738

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.

Sign up for GitHub

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

Open
legendecas wants to merge 2 commits into
base: main
Choose a base branch
from
+49 −16
Open

doc: add inline comment hints on finalizer signatures #1738

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1a34760
doc: add inline comment hints on finalizer signatures
legendecas Jul 13, 2026
ec82047
fixup!
legendecas Aug 8, 2026
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
11 changes: 6 additions & 5 deletions doc/basic_env.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,17 +72,18 @@ void SetInstanceData(DataType* data, HintType* hint) const;
- `[template] fini`: A function to call when the instance data is to be deleted.
Accepts a function of the form `void CleanupData(Napi::Env env, DataType* data,
HintType* hint)`. If not given, the default finalizer will be used, which simply
uses the `delete` operator to destroy `T*` when the add-on instance is unloaded.
uses the `delete` operator to destroy `DataType*` when the add-on instance is
unloaded.
- `[in] data`: A pointer to data that will be associated with the instance of
the add-on for the duration of its lifecycle.
- `[in] hint`: A pointer to data that will be associated with the instance of
the add-on for the duration of its lifecycle and will be passed as a hint to
`fini` when the add-on instance is unloaded.

Associates a data item stored at `T* data` with the current instance of the
add-on. The item will be passed to the function `fini` which gets called when an
instance of the add-on is unloaded. This overload accepts an additional hint to
be passed to `fini`.
Associates a data item stored at `DataType* data` with the current instance of
the add-on. The item will be passed to the function `fini` which gets called
when an instance of the add-on is unloaded. This overload accepts an additional
hint to be passed to `fini`.

### GetModuleFileName

Expand Down
8 changes: 4 additions & 4 deletions doc/external.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,9 +35,8 @@ Returns the created `Napi::External<T>` object.

```cpp
template <typename T>
static Napi::External Napi::External::New(napi_env env,
T* data,
Finalizer finalizeCallback);
template <typename Finalizer>
static External New(napi_env env, T* data, Finalizer finalizeCallback);
```

- `[in] env`: The `napi_env` environment in which to construct the `Napi::External` object.
Expand All @@ -52,7 +51,8 @@ Returns the created `Napi::External<T>` object.

```cpp
template <typename T>
static Napi::External Napi::External::New(napi_env env,
template <typename Finalizer, typename Hint>
static External New(napi_env env,
T* data,
Finalizer finalizeCallback,
Hint* finalizeHint);
Expand Down
6 changes: 3 additions & 3 deletions doc/threadsafe_function.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,9 +70,9 @@ New(napi_env env,
opportunity for cleaning up after the threads e.g. by calling
`uv_thread_join()`. It is important that, aside from the main loop thread,
there be no threads left using the thread-safe function after the finalize
callback completes. Must implement `void operator()(Env env, DataType* data,
ContextType* hint)`, skipping `data` or `hint` if they are not provided. Can
be retrieved via `GetContext()`.
callback completes. Must implement `void operator()(Env env,
FinalizerDataType* data, ContextType* context)`, skipping `data` or `context`
if they are not provided. Can be retrieved via `GetContext()`.
- `[optional] data`: Data to be passed to `finalizeCallback`.

Returns a non-empty `Napi::ThreadSafeFunction` instance.
Expand Down
2 changes: 1 addition & 1 deletion doc/typed_threadsafe_function.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,7 @@ New(napi_env env,
calling `uv_thread_join()`. It is important that, aside from the main loop
thread, there be no threads left using the thread-safe function after the
finalize callback completes. Must implement `void operator()(Env env,
FinalizerDataType* data, ContextType* hint)`.
FinalizerDataType* data, ContextType* context)`.
- `[optional] data`: Data to be passed to `finalizeCallback`.

Returns a non-empty `Napi::TypedThreadSafeFunction` instance.
Expand Down
38 changes: 35 additions & 3 deletions napi.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -422,12 +422,16 @@ class BasicEnv {
#endif // NAPI_VERSION > 8

#ifdef NODE_API_EXPERIMENTAL_HAS_POST_FINALIZER
// FinalizerType must implement `void operator()(Env env)`.

@alexweej alexweej Jul 14, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Have we considered using C++ Concepts for this instead of these human-only annotations?

@alexweej alexweej Jul 14, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(Though clearly this doesn't need to block the PR...)

@legendecas legendecas Jul 14, 2026 •
edited
Loading

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it will be a semver-major to bump minimum c++ version to c++20. Right now node-addon-api still supports c++17 as in node v18/v20

node-addon-api/package.json

Line 478 in 13c28f6

"node": "^18 || ^20 || >= 21"

@KevinEady KevinEady Jul 31, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should the Markdown documentation files also be updated to reflect the implementation signature for the callbacks? 🤔

@legendecas legendecas Aug 8, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@KevinEady updated md docs

template <typename FinalizerType>
inline void PostFinalizer(FinalizerType finalizeCallback) const;

// FinalizerType must implement `void operator()(Env env, T* data)`.
template <typename FinalizerType, typename T>
inline void PostFinalizer(FinalizerType finalizeCallback, T* data) const;

// FinalizerType must implement `void operator()(Env env, T* data,
// Hint* hint)`.
template <typename FinalizerType, typename T, typename Hint>
inline void PostFinalizer(FinalizerType finalizeCallback,
T* data,
Expand Down Expand Up @@ -1107,9 +1111,12 @@ class Object : public TypeTaggable {
const Function& constructor ///< Constructor function
) const;

// Finalizer must implement `void operator()(Env env, T* data)`.
template <typename Finalizer, typename T>
inline void AddFinalizer(Finalizer finalizeCallback, T* data) const;

// Finalizer must implement `void operator()(Env env, T* data,
// Hint* hint)`.
template <typename Finalizer, typename T, typename Hint>
inline void AddFinalizer(Finalizer finalizeCallback,
T* data,
Expand Down Expand Up @@ -1157,7 +1164,8 @@ class External : public TypeTaggable {
// Finalizer must implement `void operator()(Env env, T* data)`.
template <typename Finalizer>
static External New(napi_env env, T* data, Finalizer finalizeCallback);
// Finalizer must implement `void operator()(Env env, T* data, Hint* hint)`.
// Finalizer must implement `void operator()(Env env, T* data,
// Hint* hint)`.
template <typename Finalizer, typename Hint>
static External New(napi_env env,
T* data,
Expand Down Expand Up @@ -1712,7 +1720,8 @@ class Buffer : public Uint8Array {
T* data,
size_t length,
Finalizer finalizeCallback);
// Finalizer must implement `void operator()(Env env, T* data, Hint* hint)`.
// Finalizer must implement `void operator()(Env env, T* data,
// Hint* hint)`.
template <typename Finalizer, typename Hint>
static Buffer<T> New(napi_env env,
T* data,
Expand All @@ -1728,7 +1737,8 @@ class Buffer : public Uint8Array {
T* data,
size_t length,
Finalizer finalizeCallback);
// Finalizer must implement `void operator()(Env env, T* data, Hint* hint)`.
// Finalizer must implement `void operator()(Env env, T* data,
// Hint* hint)`.
template <typename Finalizer, typename Hint>
static Buffer<T> NewOrCopy(napi_env env,
T* data,
Expand Down Expand Up @@ -2825,6 +2835,7 @@ class ThreadSafeFunction {
ContextType* context);

// This API may only be called from the main thread.
// Finalizer must implement `void operator()(Env env)`.
template <typename ResourceString, typename Finalizer>
static ThreadSafeFunction New(napi_env env,
const Function& callback,
Expand All @@ -2834,6 +2845,8 @@ class ThreadSafeFunction {
Finalizer finalizeCallback);

// This API may only be called from the main thread.
// Finalizer must implement
// `void operator()(Env env, FinalizerDataType* data)`.
template <typename ResourceString,
typename Finalizer,
typename FinalizerDataType>
Expand All @@ -2846,6 +2859,8 @@ class ThreadSafeFunction {
FinalizerDataType* data);

// This API may only be called from the main thread.
// Finalizer must implement
// `void operator()(Env env, ContextType* context)`.
template <typename ResourceString, typename ContextType, typename Finalizer>
static ThreadSafeFunction New(napi_env env,
const Function& callback,
Expand All @@ -2856,6 +2871,8 @@ class ThreadSafeFunction {
Finalizer finalizeCallback);

// This API may only be called from the main thread.
// Finalizer must implement `void operator()(Env env,
// FinalizerDataType* data, ContextType* context)`.
template <typename ResourceString,
typename ContextType,
typename Finalizer,
Expand Down Expand Up @@ -2889,6 +2906,7 @@ class ThreadSafeFunction {
ContextType* context);

// This API may only be called from the main thread.
// Finalizer must implement `void operator()(Env env)`.
template <typename ResourceString, typename Finalizer>
static ThreadSafeFunction New(napi_env env,
const Function& callback,
Expand All @@ -2899,6 +2917,8 @@ class ThreadSafeFunction {
Finalizer finalizeCallback);

// This API may only be called from the main thread.
// Finalizer must implement
// `void operator()(Env env, FinalizerDataType* data)`.
template <typename ResourceString,
typename Finalizer,
typename FinalizerDataType>
Expand All @@ -2912,6 +2932,8 @@ class ThreadSafeFunction {
FinalizerDataType* data);

// This API may only be called from the main thread.
// Finalizer must implement
// `void operator()(Env env, ContextType* context)`.
template <typename ResourceString, typename ContextType, typename Finalizer>
static ThreadSafeFunction New(napi_env env,
const Function& callback,
Expand All @@ -2923,6 +2945,8 @@ class ThreadSafeFunction {
Finalizer finalizeCallback);

// This API may only be called from the main thread.
// Finalizer must implement `void operator()(Env env,
// FinalizerDataType* data, ContextType* context)`.
template <typename ResourceString,
typename ContextType,
typename Finalizer,
Expand Down Expand Up @@ -3067,6 +3091,8 @@ class TypedThreadSafeFunction {
// This API may only be called from the main thread.
// Creates a new threadsafe function with:
// Callback [missing] Resource [missing] Finalizer [passed]
// Finalizer must implement `void operator()(Env env,
// FinalizerDataType* data, ContextType* context)`.
template <typename ResourceString,
typename Finalizer,
typename FinalizerDataType = void>
Expand All @@ -3082,6 +3108,8 @@ class TypedThreadSafeFunction {
// This API may only be called from the main thread.
// Creates a new threadsafe function with:
// Callback [missing] Resource [passed] Finalizer [passed]
// Finalizer must implement `void operator()(Env env,
// FinalizerDataType* data, ContextType* context)`.
template <typename ResourceString,
typename Finalizer,
typename FinalizerDataType = void>
Expand Down Expand Up @@ -3124,6 +3152,8 @@ class TypedThreadSafeFunction {
// This API may only be called from the main thread.
// Creates a new threadsafe function with:
// Callback [passed] Resource [missing] Finalizer [passed]
// Finalizer must implement `void operator()(Env env,
// FinalizerDataType* data, ContextType* context)`.
template <typename ResourceString,
typename Finalizer,
typename FinalizerDataType = void>
Expand All @@ -3140,6 +3170,8 @@ class TypedThreadSafeFunction {
// This API may only be called from the main thread.
// Creates a new threadsafe function with:
// Callback [passed] Resource [passed] Finalizer [passed]
// Finalizer must implement `void operator()(Env env,
// FinalizerDataType* data, ContextType* context)`.
template <typename CallbackType,
typename ResourceString,
typename Finalizer,
Expand Down
Loading