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.

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

node-api: rename nogc to basic #53830

Closed
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
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
2 changes: 1 addition & 1 deletion benchmark/napi/ref/addon.c
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
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:
Expand All @@ -806,11 +806,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 @@ -820,7 +820,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 @@ -834,10 +834,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 @@ -862,9 +862,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 @@ -1066,7 +1066,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 @@ -1885,7 +1885,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 @@ -1915,7 +1915,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 @@ -1944,7 +1944,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 @@ -5533,7 +5533,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 @@ -5574,7 +5574,7 @@ added:
> 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 @@ -5644,7 +5644,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 @@ -5736,7 +5736,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 @@ -5757,7 +5757,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 @@ -5961,7 +5961,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 @@ -5984,7 +5984,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 @@ -6017,7 +6017,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 @@ -6234,7 +6234,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 @@ -6554,7 +6554,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 @@ -6580,7 +6580,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 @@ -6606,7 +6606,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 @@ -6731,10 +6731,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
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
Loading