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 1 commit into
base: main
Choose a base branch
from
Open

doc: add inline comment hints on finalizer signatures #1738

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
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? 🤔

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