feat: add support for nogc types via BasicEnv (#1514)

* src: introduce `NogcEnv`; support for nogc finalizers

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)

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

doc/basic_env.md

@@ -0,0 +1,200 @@
+# BasicEnv
+
+The 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 <typename T> T* GetInstanceData() const;
+```
+
+Returns the instance data that was previously associated with the environment,
+or `nullptr` if none was associated.
+
+### SetInstanceData
+
+
+```cpp
+template <typename T> using Finalizer = void (*)(Env, T*);
+template <typename T, Finalizer<T> fini = Env::DefaultFini<T>>
+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 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.
+
+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.
+
+### SetInstanceData
+
+```cpp
+template <typename DataType, typename HintType>
+using FinalizerWithHint = void (*)(Env, DataType*, HintType*);
+template <typename DataType,
+          typename HintType,
+          FinalizerWithHint<DataType, HintType> fini =
+            Env::DefaultFiniWithHint<DataType, HintType>>
+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.
+- `[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`.
+
+### GetModuleFileName
+
+```cpp
+const char* Napi::Env::GetModuleFileName() const;
+```
+
+Returns 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 <typename Hook>
+CleanupHook<Hook> 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 <typename FinalizerType>
+inline void PostFinalizer(FinalizerType 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 <typename FinalizerType, typename T>
+inline void PostFinalizer(FinalizerType 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 <typename FinalizerType, typename T, typename Hint>
+inline void PostFinalizer(FinalizerType 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 <typename Hook, typename Arg>
+CleanupHook<Hook, Arg> 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

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<T> Napi::Buffer::New(napi_env env, T* data, size_t length);
@@ -70,9 +69,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 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<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 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<T> 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<T> 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