Skip to content
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

Fix misleading documentation concerning finalize callbacks #384

Closed
wants to merge 1 commit into from
Closed

Fix misleading documentation concerning finalize callbacks #384

Show file tree
Hide file tree
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
10 changes: 5 additions & 5 deletions doc/array_buffer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,8 +59,8 @@ static Napi::ArrayBuffer Napi::ArrayBuffer::New(napi_env env,
- `[in] externalData`: The pointer to the external data to wrap.
- `[in] byteLength`: The length of the `externalData`, in bytes.
- `[in] finalizeCallback`: A function to be called when the `Napi::ArrayBuffer` is
destroyed. It must implement `operator()`, accept a `void*` (which is the
`externalData` pointer), and return `void`.
destroyed. It must implement `operator()` with parameters `(Napi::Env, void*)`,
and return `void`.
Copy link
Member

Choose a reason for hiding this comment

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

Looks like we missed a couple of parameters I think the signature is

static void FinalizeCallback(napi_env env, void* data, void* hint);

@computerquip any chance you can update to include the last parameter as well

Copy link
Contributor

Choose a reason for hiding this comment

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

@mhdawson:
From N-API napi_finalizer function pointer type always has 3 parameter, but in node-addon-api it's different.

  • for ArrayBuffer::New(..., finalizeCallback, finalizeHint) we have Finalizer (Env, void* data, Hint* hint), like napi_finalizer
  • for ArrayBuffer::New(..., finalizeCallback) we have Finalizer (Env, void* data)
template <typename T, typename Finalizer, typename Hint = void>
struct FinalizeData {
  static inline
  void Wrapper(napi_env env, void* data, void* finalizeHint) {
    FinalizeData* finalizeData = static_cast<FinalizeData*>(finalizeHint);
    finalizeData->callback(Env(env), static_cast<T*>(data));
    delete finalizeData;
  }

  static inline
  void WrapperWithHint(napi_env env, void* data, void* finalizeHint) {
    FinalizeData* finalizeData = static_cast<FinalizeData*>(finalizeHint);
    finalizeData->callback(Env(env), static_cast<T*>(data), finalizeData->hint);
    delete finalizeData;
  }

  Finalizer callback;
  Hint* hint;
};


Returns a new `Napi::ArrayBuffer` instance.

Expand All @@ -85,9 +85,9 @@ static Napi::ArrayBuffer Napi::ArrayBuffer::New(napi_env env,
- `[in] env`: The environment in which to create the `Napi::ArrayBuffer` instance.
- `[in] externalData`: The pointer to the external data to wrap.
- `[in] byteLength`: The length of the `externalData`, in bytes.
- `[in] finalizeCallback`: The function to be called when the `Napi::ArrayBuffer` is
destroyed. It must implement `operator()`, accept a `void*` (which is the
`externalData` pointer) and `Hint*`, and return `void`.
- `[in] finalizeCallback`: A function to be called when the `Napi::ArrayBuffer` is
destroyed. It must implement `operator()` with parameters `(Napi::Env, void*, Hint*)`,
and return `void`.
- `[in] finalizeHint`: The hint to be passed as the second parameter of the
finalize callback.

Expand Down
12 changes: 6 additions & 6 deletions doc/buffer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,9 +56,9 @@ static Napi::Buffer<T> Napi::Buffer::New(napi_env env,
- `[in] env`: The environment in which to create the `Napi::Buffer` object.
- `[in] data`: The pointer to the external data to expose.
- `[in] length`: The number of `T` elements in the external data.
- `[in] finalizeCallback`: The function to be called when the `Napi::Buffer` is
destroyed. It must implement `operator()`, accept a `T*` (which is the
external data pointer), and return `void`.
- `[in] finalizeCallback`: A function to be called when the `Napi::ArrayBuffer` is
destroyed. It must implement `operator()` with parameters `(Napi::Env, T*)`,
and return `void`.

Returns a new `Napi::Buffer` object.

Expand All @@ -82,9 +82,9 @@ static Napi::Buffer<T> Napi::Buffer::New(napi_env env,
- `[in] env`: The environment in which to create the `Napi::Buffer` object.
- `[in] data`: The pointer to the external data to expose.
- `[in] length`: The number of `T` elements in the external data.
- `[in] finalizeCallback`: The function to be called when the `Napi::Buffer` is
destroyed. It must implement `operator()`, accept a `T*` (which is the
external data pointer) and `Hint*`, and return `void`.
- `[in] finalizeCallback`: A function to be called when the `Napi::ArrayBuffer` is
destroyed. It must implement `operator()` with parameters `(Napi::Env, T*, Hint*)`,
and return `void`.
- `[in] finalizeHint`: The hint to be passed as the second parameter of the
finalize callback.

Expand Down
8 changes: 6 additions & 2 deletions doc/external.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,9 @@ static Napi::External Napi::External::New(napi_env env,

- `[in] env`: The `napi_env` environment in which to construct the `Napi::External` object.
- `[in] data`: The arbitrary C++ data to be held by the `Napi::External` object.
- `[in] finalizeCallback`: A function called when the `Napi::External` object is released by the garbage collector accepting a T* and returning void.
- `[in] finalizeCallback`: A function to be called when the `Napi::ArrayBuffer` is
destroyed. It must implement `operator()` with parameters `(Napi::Env, T*)`,
and return `void`.

Returns the created `Napi::External<T>` object.

Expand All @@ -45,7 +47,9 @@ static Napi::External Napi::External::New(napi_env env,

- `[in] env`: The `napi_env` environment in which to construct the `Napi::External` object.
- `[in] data`: The arbitrary C++ data to be held by the `Napi::External` object.
- `[in] finalizeCallback`: A function called when the `Napi::External` object is released by the garbage collector accepting T* and Hint* parameters and returning void.
- `[in] finalizeCallback`: A function to be called when the `Napi::ArrayBuffer` is
destroyed. It must implement `operator()` with parameters `(Napi::Env, T*, Hint*)`,
and return `void`.
- `[in] finalizeHint`: A hint value passed to the `finalizeCallback` function.

Returns the created `Napi::External<T>` object.
Expand Down