From ddd1ea47b0d23303e8f3280f0a34119f769633bc Mon Sep 17 00:00:00 2001 From: Kevin Eady <8634912+KevinEady@users.noreply.github.com> Date: Thu, 25 Jul 2024 15:27:35 +0200 Subject: [PATCH] finish docs --- doc/README.md | 2 + doc/array_buffer.md | 30 +++---- doc/basic_env.md | 201 ++++++++++++++++++++++++++++++++++++++++++++ doc/buffer.md | 50 ++++++----- doc/env.md | 138 ++---------------------------- doc/external.md | 17 +++- doc/object_wrap.md | 22 ++++- 7 files changed, 281 insertions(+), 179 deletions(-) create mode 100644 doc/basic_env.md diff --git a/doc/README.md b/doc/README.md index d6abb7107..bad1a5c5a 100644 --- a/doc/README.md +++ b/doc/README.md @@ -37,6 +37,7 @@ The following is the documentation for node-addon-api. - [Full Class Hierarchy](hierarchy.md) - [Addon Structure](addon.md) - Data Types: + - [BasicEnv](basic_env.md) - [Env](env.md) - [CallbackInfo](callbackinfo.md) - [Reference](reference.md) @@ -70,6 +71,7 @@ The following is the documentation for node-addon-api. - [Object Lifetime Management](object_lifetime_management.md) - [HandleScope](handle_scope.md) - [EscapableHandleScope](escapable_handle_scope.md) + - [Finalization](finalization.md) - [Memory Management](memory_management.md) - [Async Operations](async_operations.md) - [AsyncWorker](async_worker.md) diff --git a/doc/array_buffer.md b/doc/array_buffer.md index 3be6b42a2..9bb925129 100644 --- a/doc/array_buffer.md +++ b/doc/array_buffer.md @@ -31,13 +31,13 @@ Wraps the provided external data into a new `Napi::ArrayBuffer` instance. The `Napi::ArrayBuffer` instance does not assume ownership for the data and expects it to be valid for the lifetime of the instance. Since the `Napi::ArrayBuffer` is subject to garbage collection this overload is only -suitable for data which is static and never needs to be freed. -This factory method will not provide the caller with an opportunity to free the -data when the `Napi::ArrayBuffer` gets garbage-collected. If you need to free -the data retained by the `Napi::ArrayBuffer` object please use other -variants of the `Napi::ArrayBuffer::New` factory method that accept -`Napi::Finalizer`, which is a function that will be invoked when the -`Napi::ArrayBuffer` object has been destroyed. +suitable for data which is static and never needs to be freed. This factory +method will not provide the caller with an opportunity to free the data when the +`Napi::ArrayBuffer` gets garbage-collected. If you need to free the data +retained by the `Napi::ArrayBuffer` object please use other variants of the +`Napi::ArrayBuffer::New` factory method that accept `Napi::Finalizer`, which is +a function that will be invoked when the `Napi::ArrayBuffer` object has been +destroyed. See [Finalization]() for more details. ```cpp static Napi::ArrayBuffer Napi::ArrayBuffer::New(napi_env env, void* externalData, size_t byteLength); @@ -72,9 +72,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`: A function to be called when the `Napi::ArrayBuffer` is - destroyed. It must implement `operator()`, accept an Napi::Env, a `void*` (which is the - `externalData` pointer), and return `void`. +- `[in] finalizeCallback`: A function called when the engine destroys the + `Napi::ArrayBuffer` object, implementing `operator()(Napi::BasicEnv, void*)`. + See [Finalization]() for more details. Returns a new `Napi::ArrayBuffer` instance. @@ -102,11 +102,10 @@ 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 an Napi::Env, a `void*` (which is the - `externalData` pointer) and `Hint*`, and return `void`. -- `[in] finalizeHint`: The hint to be passed as the second parameter of the - finalize callback. +- `[in] finalizeCallback`: A function called when the engine destroys the + `Napi::ArrayBuffer` object, implementing `operator()(Napi::BasicEnv, void*, + Hint*)`. See [Finalization]() for more details. +- `[in] finalizeHint`: The hint value passed to the `finalizeCallback` function. Returns a new `Napi::ArrayBuffer` instance. @@ -163,3 +162,4 @@ Returns `true` if this `ArrayBuffer` has been detached. [`Napi::Object`]: ./object.md [External Buffer]: ./external_buffer.md +[Finalization]: ./finalization.md diff --git a/doc/basic_env.md b/doc/basic_env.md new file mode 100644 index 000000000..25668ce33 --- /dev/null +++ b/doc/basic_env.md @@ -0,0 +1,201 @@ +# BasicEnv + +The opaque data structure containing the environment in which the request is +being run. + +The `Napi::BasicEnv` object is usually created and passed by the Node.js runtime +or node-addon-api infrastructure. + +The `Napi::BasicEnv` object represents an environment that has a limited subset +of APIs when compared to `Napi::Env` and can be used in basic finalizers. See +[Finalization]() for more details. + +## Methods + +### Constructor + +```cpp +Napi::BasicEnv::BasicEnv(node_api_nogc_env env); +``` + +- `[in] env`: The `node_api_nogc_env` environment from which to construct the + `Napi::BasicEnv` object. + +### node_api_nogc_env + +```cpp +operator node_api_nogc_env() const; +``` + +Returns the `node_api_nogc_env` opaque data structure representing the +environment. + +### GetInstanceData +```cpp +template T* GetInstanceData() const; +``` + +Returns the instance data that was previously associated with the environment, +or `nullptr` if none was associated. + +### SetInstanceData + + +```cpp +template using Finalizer = void (*)(Env, T*); +template fini = Env::DefaultFini> +void SetInstanceData(T* data) 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, T* data)`. If +not given, the default finalizer will be used, which simply uses the `delete` +operator to destroy `T*` when the addon instance is unloaded. +- `[in] data`: A pointer to data that will be associated with the instance of +the addon for the duration of its lifecycle. + +Associates a data item stored at `T* data` with the current instance of the +addon. The item will be passed to the function `fini` which gets called when an +instance of the addon is unloaded. + +### SetInstanceData + +```cpp +template +using FinalizerWithHint = void (*)(Env, DataType*, HintType*); +template fini = + Env::DefaultFiniWithHint> +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 addon instance is unloaded. +- `[in] data`: A pointer to data that will be associated with the instance of +the addon for the duration of its lifecycle. +- `[in] hint`: A pointer to data that will be associated with the instance of +the addon for the duration of its lifecycle and will be passed as a hint to +`fini` when the addon instance is unloaded. + +Associates a data item stored at `T* data` with the current instance of the +addon. The item will be passed to the function `fini` which gets called when an +instance of the addon is unloaded. This overload accepts an additional hint to +be passed to `fini`. + +### GetModuleFileName + +```cpp +const char* Napi::Env::GetModuleFileName() const; +``` + +Returns a A URL containing the absolute path of the location from which the +add-on was loaded. For a file on the local file system it will start with +`file://`. The string is null-terminated and owned by env and must thus not be +modified or freed. It is only valid while the add-on is loaded. + +### AddCleanupHook + +```cpp +template +CleanupHook AddCleanupHook(Hook hook); +``` + +- `[in] hook`: A function to call when the environment exits. Accepts a function + of the form `void ()`. + +Registers `hook` as a function to be run once the current Node.js environment +exits. Unlike the underlying C-based Node-API, providing the same `hook` +multiple times **is** allowed. The hooks will be called in reverse order, i.e. +the most recently added one will be called first. + +Returns an `Env::CleanupHook` object, which can be used to remove the hook via +its `Remove()` method. + +### PostFinalizer + +```cpp +template +inline void PostFinalizer(Finalizer finalizeCallback) const; +``` + +- `[in] finalizeCallback`: The function to queue for execution outside of the GC + finalization, implementing `operator()(Napi::Env)`. See [Finalization]() for + more details. + +### PostFinalizer + +```cpp +template +inline void PostFinalizer(Finalizer finalizeCallback, T* data) const; +``` + +- `[in] finalizeCallback`: The function to queue for execution outside of the GC + finalization, implementing `operator()(Napi::Env, T*)`. See [Finalization]() + for more details. +- `[in] data`: The data to associate with the object. + +### PostFinalizer + +```cpp +template +inline void PostFinalizer(Finalizer finalizeCallback, + T* data, + Hint* finalizeHint) const; +``` + +- `[in] finalizeCallback`: The function to queue for execution outside of the GC + finalization, implementing `operator()(Napi::Env, T*, Hint*)`. See + [Finalization]() for more details. +- `[in] data`: The data to associate with the object. +- `[in] finalizeHint`: The hint value passed to the `finalizeCallback` function. + +### AddCleanupHook + +```cpp +template +CleanupHook AddCleanupHook(Hook hook, Arg* arg); +``` + +- `[in] hook`: A function to call when the environment exits. Accepts a function + of the form `void (Arg* arg)`. +- `[in] arg`: A pointer to data that will be passed as the argument to `hook`. + +Registers `hook` as a function to be run with the `arg` parameter once the +current Node.js environment exits. Unlike the underlying C-based Node-API, +providing the same `hook` and `arg` pair multiple times **is** allowed. The +hooks will be called in reverse order, i.e. the most recently added one will be +called first. + +Returns an `Env::CleanupHook` object, which can be used to remove the hook via +its `Remove()` method. + +# Env::CleanupHook + +The `Env::CleanupHook` object allows removal of the hook added via +`Env::AddCleanupHook()` + +## Methods + +### IsEmpty + +```cpp +bool IsEmpty(); +``` + +Returns `true` if the cleanup hook was **not** successfully registered. + +### Remove + +```cpp +bool Remove(Env env); +``` + +Unregisters the hook from running once the current Node.js environment exits. + +Returns `true` if the hook was successfully removed from the Node.js +environment. + +[Finalization]: ./finalization.md diff --git a/doc/buffer.md b/doc/buffer.md index 427eeee2f..2e2ac87de 100644 --- a/doc/buffer.md +++ b/doc/buffer.md @@ -27,16 +27,15 @@ Returns a new `Napi::Buffer` object. Wraps the provided external data into a new `Napi::Buffer` object. -The `Napi::Buffer` object does not assume ownership for the data and expects it to be -valid for the lifetime of the object. Since the `Napi::Buffer` is subject to garbage -collection this overload is only suitable for data which is static and never -needs to be freed. -This factory method will not provide the caller with an opportunity to free the -data when the `Napi::Buffer` gets garbage-collected. If you need to free the -data retained by the `Napi::Buffer` object please use other variants of the -`Napi::Buffer::New` factory method that accept `Napi::Finalizer`, which is a -function that will be invoked when the `Napi::Buffer` object has been -destroyed. +The `Napi::Buffer` object does not assume ownership for the data and expects it +to be valid for the lifetime of the object. Since the `Napi::Buffer` is subject +to garbage collection this overload is only suitable for data which is static +and never needs to be freed. This factory method will not provide the caller +with an opportunity to free the data when the `Napi::Buffer` gets +garbage-collected. If you need to free the data retained by the `Napi::Buffer` +object please use other variants of the `Napi::Buffer::New` factory method that +accept `Finalizer`, which is a function that will be invoked when the +`Napi::Buffer` object has been destroyed. See [Finalization]() for more details. ```cpp static Napi::Buffer Napi::Buffer::New(napi_env env, T* data, size_t length); @@ -70,9 +69,9 @@ static Napi::Buffer 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 an Napi::Env, a `T*` (which is the - external data pointer), and return `void`. +- `[in] finalizeCallback`: The function called when the engine destroys the + `Napi::Buffer` object, implementing `operator()(Napi::BasicEnv, T*)`. See + [Finalization]() for more details. Returns a new `Napi::Buffer` object. @@ -99,11 +98,10 @@ static Napi::Buffer 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 an Napi::Env, a `T*` (which is the - external data pointer) and `Hint*`, and return `void`. -- `[in] finalizeHint`: The hint to be passed as the second parameter of the - finalize callback. +- `[in] finalizeCallback`: The function called when the engine destroys the + `Napi::Buffer` object, implementing `operator()(Napi::BasicEnv, T*, Hint*)`. + See [Finalization]() for more details. +- `[in] finalizeHint`: The hint value passed to the `finalizeCallback` function. Returns a new `Napi::Buffer` object. @@ -157,9 +155,9 @@ static Napi::Buffer Napi::Buffer::NewOrCopy(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 an Napi::Env, a `T*` (which is the - external data pointer), and return `void`. +- `[in] finalizeCallback`: The function called when the engine destroys the + `Napi::Buffer` object, implementing `operator()(Napi::BasicEnv, T*)`. See + [Finalization]() for more details. Returns a new `Napi::Buffer` object. @@ -186,11 +184,10 @@ static Napi::Buffer Napi::Buffer::NewOrCopy(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 an Napi::Env, a `T*` (which is the - external data pointer) and `Hint*`, and return `void`. -- `[in] finalizeHint`: The hint to be passed as the second parameter of the - finalize callback. +- `[in] finalizeCallback`: The function called when the engine destroys the + `Napi::Buffer` object, implementing `operator()(Napi::BasicEnv, T*, Hint*)`. + See [Finalization]() for more details. +- `[in] finalizeHint`: The hint value passed to the `finalizeCallback` function. Returns a new `Napi::Buffer` object. @@ -245,3 +242,4 @@ Returns the number of `T` elements in the external data. [`Napi::Uint8Array`]: ./typed_array_of.md [External Buffer]: ./external_buffer.md +[Finalization]: ./finalization.md diff --git a/doc/env.md b/doc/env.md index 29aa4459e..1989ea4e2 100644 --- a/doc/env.md +++ b/doc/env.md @@ -1,8 +1,13 @@ # Env -The opaque data structure containing the environment in which the request is being run. +The opaque data structure containing the environment in which the request is +being run. -The Env object is usually created and passed by the Node.js runtime or node-addon-api infrastructure. +The `Napi::Env` object is usually created and passed by the Node.js runtime or +node-addon-api infrastructure. + +The `Napi::Env` object represents an environment that has a superset of APIs +when compared to `Napi::BasicEnv` and therefore _cannot_ be used in basic finalizers. ## Methods @@ -76,132 +81,3 @@ The `script` can be any of the following types: - `const char *` - `const std::string &` -### GetInstanceData -```cpp -template T* GetInstanceData() const; -``` - -Returns the instance data that was previously associated with the environment, -or `nullptr` if none was associated. - -### SetInstanceData - -```cpp -template using Finalizer = void (*)(Env, T*); -template fini = Env::DefaultFini> -void SetInstanceData(T* data) 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, T* data)`. If -not given, the default finalizer will be used, which simply uses the `delete` -operator to destroy `T*` when the addon instance is unloaded. -- `[in] data`: A pointer to data that will be associated with the instance of -the addon for the duration of its lifecycle. - -Associates a data item stored at `T* data` with the current instance of the -addon. The item will be passed to the function `fini` which gets called when an -instance of the addon is unloaded. - -### SetInstanceData - -```cpp -template -using FinalizerWithHint = void (*)(Env, DataType*, HintType*); -template fini = - Env::DefaultFiniWithHint> -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 addon instance is unloaded. -- `[in] data`: A pointer to data that will be associated with the instance of -the addon for the duration of its lifecycle. -- `[in] hint`: A pointer to data that will be associated with the instance of -the addon for the duration of its lifecycle and will be passed as a hint to -`fini` when the addon instance is unloaded. - -Associates a data item stored at `T* data` with the current instance of the -addon. The item will be passed to the function `fini` which gets called when an -instance of the addon is unloaded. This overload accepts an additional hint to -be passed to `fini`. - -### GetModuleFileName - -```cpp -const char* Napi::Env::GetModuleFileName() const; -``` - -Returns a A URL containing the absolute path of the location from which the -add-on was loaded. For a file on the local file system it will start with -`file://`. The string is null-terminated and owned by env and must thus not be -modified or freed. It is only valid while the add-on is loaded. - -### AddCleanupHook - -```cpp -template -CleanupHook AddCleanupHook(Hook hook); -``` - -- `[in] hook`: A function to call when the environment exits. Accepts a - function of the form `void ()`. - -Registers `hook` as a function to be run once the current Node.js environment -exits. Unlike the underlying C-based Node-API, providing the same `hook` -multiple times **is** allowed. The hooks will be called in reverse order, i.e. -the most recently added one will be called first. - -Returns an `Env::CleanupHook` object, which can be used to remove the hook via -its `Remove()` method. - -### AddCleanupHook - -```cpp -template -CleanupHook AddCleanupHook(Hook hook, Arg* arg); -``` - -- `[in] hook`: A function to call when the environment exits. Accepts a - function of the form `void (Arg* arg)`. -- `[in] arg`: A pointer to data that will be passed as the argument to `hook`. - -Registers `hook` as a function to be run with the `arg` parameter once the -current Node.js environment exits. Unlike the underlying C-based Node-API, -providing the same `hook` and `arg` pair multiple times **is** allowed. The -hooks will be called in reverse order, i.e. the most recently added one will be -called first. - -Returns an `Env::CleanupHook` object, which can be used to remove the hook via -its `Remove()` method. - -# Env::CleanupHook - -The `Env::CleanupHook` object allows removal of the hook added via -`Env::AddCleanupHook()` - -## Methods - -### IsEmpty - -```cpp -bool IsEmpty(); -``` - -Returns `true` if the cleanup hook was **not** successfully registered. - -### Remove - -```cpp -bool Remove(Env env); -``` - -Unregisters the hook from running once the current Node.js environment exits. - -Returns `true` if the hook was successfully removed from the Node.js -environment. diff --git a/doc/external.md b/doc/external.md index ce42e112a..962da722f 100644 --- a/doc/external.md +++ b/doc/external.md @@ -4,7 +4,11 @@ Class `Napi::External` inherits from class [`Napi::TypeTaggable`][]. The `Napi::External` template class implements the ability to create a `Napi::Value` object with arbitrary C++ data. It is the user's responsibility to manage the memory for the arbitrary C++ data. -`Napi::External` objects can be created with an optional Finalizer function and optional Hint value. The Finalizer function, if specified, is called when your `Napi::External` object is released by Node's garbage collector. It gives your code the opportunity to free any dynamically created data. If you specify a Hint value, it is passed to your Finalizer function. +`Napi::External` objects can be created with an optional Finalizer function and +optional Hint value. The `Finalizer` function, if specified, is called when your +`Napi::External` object is released by Node's garbage collector. It gives your +code the opportunity to free any dynamically created data. If you specify a Hint +value, it is passed to your `Finalizer` function. See [Finalization]() for more details. Note that `Napi::Value::IsExternal()` will return `true` for any external value. It does not differentiate between the templated parameter `T` in @@ -38,7 +42,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`: The function called when the engine destroys the + `Napi::External` object, implementing `operator()(Napi::BasicEnv, T*)`. See + [Finalization]() for more details. Returns the created `Napi::External` object. @@ -54,8 +60,10 @@ 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] finalizeHint`: A hint value passed to the `finalizeCallback` function. +- `[in] finalizeCallback`: The function called when the engine destroys the + `Napi::External` object, implementing `operator()(Napi::BasicEnv, T*, Hint*)`. + See [Finalization]() for more details. +- `[in] finalizeHint`: The hint value passed to the `finalizeCallback` function. Returns the created `Napi::External` object. @@ -67,4 +75,5 @@ T* Napi::External::Data() const; Returns a pointer to the arbitrary C++ data held by the `Napi::External` object. +[Finalization]: ./finalization.md [`Napi::TypeTaggable`]: ./type_taggable.md diff --git a/doc/object_wrap.md b/doc/object_wrap.md index 43546646a..29e1eee48 100644 --- a/doc/object_wrap.md +++ b/doc/object_wrap.md @@ -241,9 +241,24 @@ request being made. ### Finalize -Provides an opportunity to run cleanup code that requires access to the -`Napi::Env` before the wrapped native object instance is freed. Override to -implement. +Provides an opportunity to run cleanup code that only utilizes basic Node APIs, if any. +Override to implement. See [Finalization]() for more details. + +```cpp +virtual void Finalize(Napi::BasicEnv env); +``` + +- `[in] env`: `Napi::Env`. + +### Finalize + +Provides an opportunity to run cleanup code that utilizes non-basic Node APIs. +Override to implement. + +*NOTE*: Defining this method causes the deletion of the underlying `T* data` to +be postponed until _after_ the garbage collection cycle. Since an `Napi::Env` +has access to non-basic Node APIs, it cannot run in the same current tick as the +garbage collector. ```cpp virtual void Finalize(Napi::Env env); @@ -586,3 +601,4 @@ Returns `Napi::PropertyDescriptor` object that represents an static value property of a JavaScript class [`Napi::InstanceWrap`]: ./instance_wrap.md +[Finalization]: ./finalization.md