Skip to content

Commit

Permalink
feat: add support for nogc types via BasicEnv (#1514)
Browse files Browse the repository at this point in the history
* src: introduce `NogcEnv`; support for nogc finalizers
  • Loading branch information
KevinEady authored Sep 3, 2024
1 parent a0619ff commit b4aeecb
Show file tree
Hide file tree
Showing 15 changed files with 1,045 additions and 300 deletions.
2 changes: 2 additions & 0 deletions doc/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand Down
30 changes: 15 additions & 15 deletions doc/array_buffer.md
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -163,3 +162,4 @@ Returns `true` if this `ArrayBuffer` has been detached.

[`Napi::Object`]: ./object.md
[External Buffer]: ./external_buffer.md
[Finalization]: ./finalization.md
200 changes: 200 additions & 0 deletions doc/basic_env.md
Original file line number Diff line number Diff line change
@@ -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
50 changes: 24 additions & 26 deletions doc/buffer.md
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down Expand Up @@ -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.
Expand All @@ -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.

Expand Down Expand Up @@ -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.

Expand All @@ -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.
Expand Down Expand Up @@ -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
Loading

0 comments on commit b4aeecb

Please sign in to comment.