Skip to content

Commit

Permalink
node-api: rename nogc to basic
Browse files Browse the repository at this point in the history 
Signed-off-by: Gabriel Schulhof <gabrielschulhof@gmail.com>
PR-URL: #53830
Reviewed-By: Vladimir Morozov <vmorozov@microsoft.com>
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
Reviewed-By: Michael Dawson <midawson@redhat.com>
  • Loading branch information
@gabrielschulhof @marco-ippolito
gabrielschulhof authored and marco-ippolito committed Aug 19, 2024
1 parent 496975e commit e6a4104
Show file tree
Hide file tree
Showing 13 changed files with 157 additions and 147 deletions.
2 changes: 1 addition & 1 deletion benchmark/napi/ref/addon.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ SetCount(napi_env env, napi_callback_info info) {
return NULL;
}

static void IncrementCounter(node_api_nogc_env env, void* data, void* hint) {
static void IncrementCounter(node_api_basic_env env, void* data, void* hint) {
size_t* count = data;
(*count) = (*count) + 1;
}
Expand Down
62 changes: 31 additions & 31 deletions doc/api/n-api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -477,7 +477,7 @@ napiVersion: 6
-->

```c
napi_status napi_set_instance_data(node_api_nogc_env env,
napi_status napi_set_instance_data(node_api_basic_env env,
void* data,
napi_finalize finalize_cb,
void* finalize_hint);
Expand Down Expand Up @@ -509,7 +509,7 @@ napiVersion: 6
-->

```c
napi_status napi_get_instance_data(node_api_nogc_env env,
napi_status napi_get_instance_data(node_api_basic_env env,
void** data);
```

Expand Down Expand Up @@ -611,16 +611,16 @@ when an instance of a native addon is unloaded. Notification of this event is
delivered through the callbacks given to [`napi_add_env_cleanup_hook`][] and
[`napi_set_instance_data`][].

### `node_api_nogc_env`
### `node_api_basic_env`

> Stability: 1 - Experimental

This variant of `napi_env` is passed to synchronous finalizers
([`node_api_nogc_finalize`][]). There is a subset of Node-APIs which accept
a parameter of type `node_api_nogc_env` as their first argument. These APIs do
([`node_api_basic_finalize`][]). There is a subset of Node-APIs which accept
a parameter of type `node_api_basic_env` as their first argument. These APIs do
not access the state of the JavaScript engine and are thus safe to call from
synchronous finalizers. Passing a parameter of type `napi_env` to these APIs is
allowed, however, passing a parameter of type `node_api_nogc_env` to APIs that
allowed, however, passing a parameter of type `node_api_basic_env` to APIs that
access the JavaScript engine state is not allowed. Attempting to do so without
a cast will produce a compiler warning or an error when add-ons are compiled
with flags which cause them to emit warnings and/or errors when incorrect
Expand Down Expand Up @@ -791,7 +791,7 @@ typedef napi_value (*napi_callback)(napi_env, napi_callback_info);
Unless for reasons discussed in [Object Lifetime Management][], creating a
handle and/or callback scope inside a `napi_callback` is not necessary.

#### `node_api_nogc_finalize`
#### `node_api_basic_finalize`

<!-- YAML
added: v20.12.0
Expand All @@ -803,11 +803,11 @@ Function pointer type for add-on provided functions that allow the user to be
notified when externally-owned data is ready to be cleaned up because the
object it was associated with has been garbage-collected. The user must provide
a function satisfying the following signature which would get called upon the
object's collection. Currently, `node_api_nogc_finalize` can be used for
object's collection. Currently, `node_api_basic_finalize` can be used for
finding out when objects that have external data are collected.

```c
typedef void (*node_api_nogc_finalize)(node_api_nogc_env env,
typedef void (*node_api_basic_finalize)(node_api_basic_env env,
void* finalize_data,
void* finalize_hint);
```
Expand All @@ -817,7 +817,7 @@ handle and/or callback scope inside the function body is not necessary.

Since these functions may be called while the JavaScript engine is in a state
where it cannot execute JavaScript code, only Node-APIs which accept a
`node_api_nogc_env` as their first parameter may be called.
`node_api_basic_env` as their first parameter may be called.
[`node_api_post_finalizer`][] can be used to schedule Node-API calls that
require access to the JavaScript engine's state to run after the current
garbage collection cycle has completed.
Expand All @@ -831,10 +831,10 @@ Change History:

* experimental (`NAPI_EXPERIMENTAL`):

Only Node-API calls that accept a `node_api_nogc_env` as their first
Only Node-API calls that accept a `node_api_basic_env` as their first
parameter may be called, otherwise the application will be terminated with an
appropriate error message. This feature can be turned off by defining
`NODE_API_EXPERIMENTAL_NOGC_ENV_OPT_OUT`.
`NODE_API_EXPERIMENTAL_BASIC_ENV_OPT_OUT`.

#### `napi_finalize`

Expand All @@ -859,9 +859,9 @@ Change History:
* experimental (`NAPI_EXPERIMENTAL` is defined):

A function of this type may no longer be used as a finalizer, except with
[`node_api_post_finalizer`][]. [`node_api_nogc_finalize`][] must be used
[`node_api_post_finalizer`][]. [`node_api_basic_finalize`][] must be used
instead. This feature can be turned off by defining
`NODE_API_EXPERIMENTAL_NOGC_ENV_OPT_OUT`.
`NODE_API_EXPERIMENTAL_BASIC_ENV_OPT_OUT`.

#### `napi_async_execute_callback`

Expand Down Expand Up @@ -1063,7 +1063,7 @@ napiVersion: 1

```c
napi_status
napi_get_last_error_info(node_api_nogc_env env,
napi_get_last_error_info(node_api_basic_env env,
const napi_extended_error_info** result);
```

Expand Down Expand Up @@ -1882,7 +1882,7 @@ napiVersion: 3
-->

```c
NODE_EXTERN napi_status napi_add_env_cleanup_hook(node_api_nogc_env env,
NODE_EXTERN napi_status napi_add_env_cleanup_hook(node_api_basic_env env,
napi_cleanup_hook fun,
void* arg);
```
Expand Down Expand Up @@ -1912,7 +1912,7 @@ napiVersion: 3
-->

```c
NAPI_EXTERN napi_status napi_remove_env_cleanup_hook(node_api_nogc_env env,
NAPI_EXTERN napi_status napi_remove_env_cleanup_hook(node_api_basic_env env,
void (*fun)(void* arg),
void* arg);
```
Expand Down Expand Up @@ -1941,7 +1941,7 @@ changes:

```c
NAPI_EXTERN napi_status napi_add_async_cleanup_hook(
node_api_nogc_env env,
node_api_basic_env env,
napi_async_cleanup_hook hook,
void* arg,
napi_async_cleanup_hook_handle* remove_handle);
Expand Down Expand Up @@ -5524,7 +5524,7 @@ napiVersion: 5
napi_status napi_add_finalizer(napi_env env,
napi_value js_object,
void* finalize_data,
node_api_nogc_finalize finalize_cb,
node_api_basic_finalize finalize_cb,
void* finalize_hint,
napi_ref* result);
```
Expand Down Expand Up @@ -5562,7 +5562,7 @@ added: v20.10.0
> Stability: 1 - Experimental

```c
napi_status node_api_post_finalizer(node_api_nogc_env env,
napi_status node_api_post_finalizer(node_api_basic_env env,
napi_finalize finalize_cb,
void* finalize_data,
void* finalize_hint);
Expand Down Expand Up @@ -5632,7 +5632,7 @@ Once created the async worker can be queued
for execution using the [`napi_queue_async_work`][] function:

```c
napi_status napi_queue_async_work(node_api_nogc_env env,
napi_status napi_queue_async_work(node_api_basic_env env,
napi_async_work work);
```

Expand Down Expand Up @@ -5724,7 +5724,7 @@ napiVersion: 1
-->

```c
napi_status napi_queue_async_work(node_api_nogc_env env,
napi_status napi_queue_async_work(node_api_basic_env env,
napi_async_work work);
```

Expand All @@ -5745,7 +5745,7 @@ napiVersion: 1
-->

```c
napi_status napi_cancel_async_work(node_api_nogc_env env,
napi_status napi_cancel_async_work(node_api_basic_env env,
napi_async_work work);
```

Expand Down Expand Up @@ -5949,7 +5949,7 @@ typedef struct {
const char* release;
} napi_node_version;

napi_status napi_get_node_version(node_api_nogc_env env,
napi_status napi_get_node_version(node_api_basic_env env,
const napi_node_version** version);
```

Expand All @@ -5972,7 +5972,7 @@ napiVersion: 1
-->

```c
napi_status napi_get_version(node_api_nogc_env env,
napi_status napi_get_version(node_api_basic_env env,
uint32_t* result);
```

Expand Down Expand Up @@ -6005,7 +6005,7 @@ napiVersion: 1
-->

```c
NAPI_EXTERN napi_status napi_adjust_external_memory(node_api_nogc_env env,
NAPI_EXTERN napi_status napi_adjust_external_memory(node_api_basic_env env,
int64_t change_in_bytes,
int64_t* result);
```
Expand Down Expand Up @@ -6222,7 +6222,7 @@ napiVersion: 2
-->

```c
NAPI_EXTERN napi_status napi_get_uv_event_loop(node_api_nogc_env env,
NAPI_EXTERN napi_status napi_get_uv_event_loop(node_api_basic_env env,
struct uv_loop_s** loop);
```

Expand Down Expand Up @@ -6542,7 +6542,7 @@ napiVersion: 4

```c
NAPI_EXTERN napi_status
napi_ref_threadsafe_function(node_api_nogc_env env, napi_threadsafe_function func);
napi_ref_threadsafe_function(node_api_basic_env env, napi_threadsafe_function func);
```

* `[in] env`: The environment that the API is invoked under.
Expand All @@ -6568,7 +6568,7 @@ napiVersion: 4

```c
NAPI_EXTERN napi_status
napi_unref_threadsafe_function(node_api_nogc_env env, napi_threadsafe_function func);
napi_unref_threadsafe_function(node_api_basic_env env, napi_threadsafe_function func);
```

* `[in] env`: The environment that the API is invoked under.
Expand All @@ -6594,7 +6594,7 @@ napiVersion: 9

```c
NAPI_EXTERN napi_status
node_api_get_module_file_name(node_api_nogc_env env, const char** result);
node_api_get_module_file_name(node_api_basic_env env, const char** result);

```

Expand Down Expand Up @@ -6719,10 +6719,10 @@ the add-on's file name during loading.
[`napi_wrap`]: #napi_wrap
[`node-addon-api`]: https://github.com/nodejs/node-addon-api
[`node_api.h`]: https://github.com/nodejs/node/blob/HEAD/src/node_api.h
[`node_api_basic_finalize`]: #node_api_basic_finalize
[`node_api_create_external_string_latin1`]: #node_api_create_external_string_latin1
[`node_api_create_external_string_utf16`]: #node_api_create_external_string_utf16
[`node_api_create_syntax_error`]: #node_api_create_syntax_error
[`node_api_nogc_finalize`]: #node_api_nogc_finalize
[`node_api_post_finalizer`]: #node_api_post_finalizer
[`node_api_throw_syntax_error`]: #node_api_throw_syntax_error
[`process.release`]: process.md#processrelease
Expand Down
51 changes: 26 additions & 25 deletions src/js_native_api.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@
EXTERN_C_START

NAPI_EXTERN napi_status NAPI_CDECL napi_get_last_error_info(
node_api_nogc_env env, const napi_extended_error_info** result);
node_api_basic_env env, const napi_extended_error_info** result);

// Getters for defined singletons
NAPI_EXTERN napi_status NAPI_CDECL napi_get_undefined(napi_env env,
Expand Down Expand Up @@ -94,19 +94,19 @@ NAPI_EXTERN napi_status NAPI_CDECL napi_create_string_utf16(napi_env env,
napi_value* result);
#ifdef NAPI_EXPERIMENTAL
#define NODE_API_EXPERIMENTAL_HAS_EXTERNAL_STRINGS
NAPI_EXTERN napi_status NAPI_CDECL
node_api_create_external_string_latin1(napi_env env,
char* str,
size_t length,
node_api_nogc_finalize finalize_callback,
void* finalize_hint,
napi_value* result,
bool* copied);
NAPI_EXTERN napi_status NAPI_CDECL node_api_create_external_string_latin1(
napi_env env,
char* str,
size_t length,
node_api_basic_finalize finalize_callback,
void* finalize_hint,
napi_value* result,
bool* copied);
NAPI_EXTERN napi_status NAPI_CDECL
node_api_create_external_string_utf16(napi_env env,
char16_t* str,
size_t length,
node_api_nogc_finalize finalize_callback,
node_api_basic_finalize finalize_callback,
void* finalize_hint,
napi_value* result,
bool* copied);
Expand Down Expand Up @@ -318,12 +318,13 @@ napi_define_class(napi_env env,
napi_value* result);

// Methods to work with external data objects
NAPI_EXTERN napi_status NAPI_CDECL napi_wrap(napi_env env,
napi_value js_object,
void* native_object,
node_api_nogc_finalize finalize_cb,
void* finalize_hint,
napi_ref* result);
NAPI_EXTERN napi_status NAPI_CDECL
napi_wrap(napi_env env,
napi_value js_object,
void* native_object,
node_api_basic_finalize finalize_cb,
void* finalize_hint,
napi_ref* result);
NAPI_EXTERN napi_status NAPI_CDECL napi_unwrap(napi_env env,
napi_value js_object,
void** result);
Expand All @@ -333,7 +334,7 @@ NAPI_EXTERN napi_status NAPI_CDECL napi_remove_wrap(napi_env env,
NAPI_EXTERN napi_status NAPI_CDECL
napi_create_external(napi_env env,
void* data,
node_api_nogc_finalize finalize_cb,
node_api_basic_finalize finalize_cb,
void* finalize_hint,
napi_value* result);
NAPI_EXTERN napi_status NAPI_CDECL napi_get_value_external(napi_env env,
Expand Down Expand Up @@ -432,7 +433,7 @@ NAPI_EXTERN napi_status NAPI_CDECL
napi_create_external_arraybuffer(napi_env env,
void* external_data,
size_t byte_length,
node_api_nogc_finalize finalize_cb,
node_api_basic_finalize finalize_cb,
void* finalize_hint,
napi_value* result);
#endif // NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED
Expand Down Expand Up @@ -474,7 +475,7 @@ napi_get_dataview_info(napi_env env,
size_t* byte_offset);

// version management
NAPI_EXTERN napi_status NAPI_CDECL napi_get_version(node_api_nogc_env env,
NAPI_EXTERN napi_status NAPI_CDECL napi_get_version(node_api_basic_env env,
uint32_t* result);

// Promises
Expand All @@ -498,7 +499,7 @@ NAPI_EXTERN napi_status NAPI_CDECL napi_run_script(napi_env env,

// Memory management
NAPI_EXTERN napi_status NAPI_CDECL napi_adjust_external_memory(
node_api_nogc_env env, int64_t change_in_bytes, int64_t* adjusted_value);
node_api_basic_env env, int64_t change_in_bytes, int64_t* adjusted_value);

#if NAPI_VERSION >= 5

Expand All @@ -520,7 +521,7 @@ NAPI_EXTERN napi_status NAPI_CDECL
napi_add_finalizer(napi_env env,
napi_value js_object,
void* finalize_data,
node_api_nogc_finalize finalize_cb,
node_api_basic_finalize finalize_cb,
void* finalize_hint,
napi_ref* result);

Expand All @@ -530,7 +531,7 @@ napi_add_finalizer(napi_env env,
#define NODE_API_EXPERIMENTAL_HAS_POST_FINALIZER

NAPI_EXTERN napi_status NAPI_CDECL
node_api_post_finalizer(node_api_nogc_env env,
node_api_post_finalizer(node_api_basic_env env,
napi_finalize finalize_cb,
void* finalize_data,
void* finalize_hint);
Expand Down Expand Up @@ -575,13 +576,13 @@ napi_get_all_property_names(napi_env env,

// Instance data
NAPI_EXTERN napi_status NAPI_CDECL
napi_set_instance_data(node_api_nogc_env env,
napi_set_instance_data(node_api_basic_env env,
void* data,
napi_finalize finalize_cb,
void* finalize_hint);

NAPI_EXTERN napi_status NAPI_CDECL napi_get_instance_data(node_api_nogc_env env,
void** data);
NAPI_EXTERN napi_status NAPI_CDECL
napi_get_instance_data(node_api_basic_env env, void** data);
#endif // NAPI_VERSION >= 6

#if NAPI_VERSION >= 7
Expand Down
Loading

0 comments on commit e6a4104

Please sign in to comment.