nodejs
/
node
mirror of https://github.com/nodejs/node.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

node-api: define version 10 

Notable runtime changes to existing APIs:
- returning `node_api_cannot_run_js` instead of
  `napi_pending_exception`.
- allow creating references to objects, functions, and symbols.

PR-URL: https://github.com/nodejs/node/pull/55676
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
This commit is contained in:
Gabriel Schulhof 2024-12-31 08:29:50 -08:00 committed by Antoine du Hamel
parent 18d4b502af
commit 01e69be8ff
No known key found for this signature in database
GPG Key ID: 21D900FFDB233756
14 changed files with 46 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
doc/api/n-api.md
View File

@ -1748,7 +1748,7 @@ will not be freed. This can be avoided by calling
**Change History:**
* Experimental (`NAPI_EXPERIMENTAL` is defined):
* Version 10 (`NAPI_VERSION` is defined as `10` or higher):
References can be created for all value types. The new supported value
types do not support weak reference semantic and the values of these types
@ -2700,10 +2700,9 @@ JavaScript `TypedArray` objects are described in
<!-- YAML
added: v22.12.0
napiVersion: 10
-->
> Stability: 1 - Experimental
```c
napi_status NAPI_CDECL node_api_create_buffer_from_arraybuffer(napi_env env,
napi_value arraybuffer,
@ -2965,10 +2964,9 @@ The JavaScript `string` type is described in
added:
- v20.4.0
- v18.18.0
napiVersion: 10
-->
> Stability: 1 - Experimental
```c
napi_status
node_api_create_external_string_latin1(napi_env env,
@ -3045,10 +3043,9 @@ The JavaScript `string` type is described in
added:
- v20.4.0
- v18.18.0
napiVersion: 10
-->
> Stability: 1 - Experimental
```c
napi_status
node_api_create_external_string_utf16(napi_env env,
@ -3138,10 +3135,9 @@ creation methods.
<!-- YAML
added: v22.9.0
napiVersion: 10
-->
> Stability: 1 - Experimental
```c
napi_status NAPI_CDECL node_api_create_property_key_latin1(napi_env env,
const char* str,
@ -3173,10 +3169,9 @@ The JavaScript `string` type is described in
added:
- v21.7.0
- v20.12.0
napiVersion: 10
-->
> Stability: 1 - Experimental
```c
napi_status NAPI_CDECL node_api_create_property_key_utf16(napi_env env,
const char16_t* str,
@ -3204,10 +3199,9 @@ The JavaScript `string` type is described in
<!-- YAML
added: v22.9.0
napiVersion: 10
-->
> Stability: 1 - Experimental
```c
napi_status NAPI_CDECL node_api_create_property_key_utf8(napi_env env,
const char* str,
@ -6527,7 +6521,7 @@ napi_create_threadsafe_function(napi_env env,
**Change History:**
* Experimental (`NAPI_EXPERIMENTAL` is defined):
* Version 10 (`NAPI_VERSION` is defined as `10` or higher):
Uncaught exceptions thrown in `call_js_cb` are handled with the
[`'uncaughtException'`][] event, instead of being ignored.

18
doc/contributing/releases-node-api.md
View File

@ -85,7 +85,7 @@ with:
```bash
grep \
-E \
-nHE \
'N(ODE_)?API_EXPERIMENTAL' \
src/js_native_api{_types,}.h \
src/node_api{_types,}.h
@ -95,13 +95,13 @@ and update the define version guards with the release version:
```diff
- #ifdef NAPI_EXPERIMENTAL
+ #if NAPI_VERSION >= 10
+ #if NAPI_VERSION >= 11
NAPI_EXTERN napi_status NAPI_CDECL
node_api_function(napi_env env);
- #endif // NAPI_EXPERIMENTAL
+ #endif // NAPI_VERSION >= 10
+ #endif // NAPI_VERSION >= 11
```
Remove any feature flags of the form `NODE_API_EXPERIMENTAL_HAS_<FEATURE>`.
@ -121,11 +121,11 @@ Also, update the Node-API version value of the `napi_get_version` test in
#### Step 2. Update runtime version guards
If this release includes runtime behavior version guards, the relevant commits
should already include `NAPI_VERSION_EXPERIMENTAL` guard for the change. Check
for these guards with:
should already include the `NAPI_VERSION_EXPERIMENTAL` guard for the change.
Check for these guards with:
```bash
grep NAPI_VERSION_EXPERIMENTAL src/js_native_api_v8* src/node_api.cc
grep -nH NAPI_VERSION_EXPERIMENTAL src/js_native_api_v8* src/node_api.cc
```
and substitute this guard version with the release version `x`.
@ -138,7 +138,7 @@ Check for these definitions with:
```bash
grep \
-E \
-nHE \
'N(ODE_)?API_EXPERIMENTAL' \
test/node-api/*/{*.{h,c},binding.gyp} \
test/js-native-api/*/{*.{h,c},binding.gyp}
@ -170,7 +170,7 @@ stability banner:
<!-- YAML
added:
- v1.2.3
+ napiVersion: 10
+ napiVersion: 11
-->
- > Stability: 1 - Experimental
@ -186,7 +186,7 @@ For all runtime version guards updated in Step 2, check for these definitions
with:
```bash
grep NAPI_EXPERIMENTAL doc/api/n-api.md
grep -nH NAPI_EXPERIMENTAL doc/api/n-api.md
```
In `doc/api/n-api.md`, update the `experimental` change history item to be the

8
src/js_native_api.h
View File

@ -92,8 +92,7 @@ NAPI_EXTERN napi_status NAPI_CDECL napi_create_string_utf16(napi_env env,
const char16_t* str,
size_t length,
napi_value* result);
#ifdef NAPI_EXPERIMENTAL
#define NODE_API_EXPERIMENTAL_HAS_EXTERNAL_STRINGS
#if NAPI_VERSION >= 10
NAPI_EXTERN napi_status NAPI_CDECL node_api_create_external_string_latin1(
napi_env env,
char* str,
@ -110,17 +109,14 @@ node_api_create_external_string_utf16(napi_env env,
void* finalize_hint,
napi_value* result,
bool* copied);
#endif // NAPI_EXPERIMENTAL
#ifdef NAPI_EXPERIMENTAL
#define NODE_API_EXPERIMENTAL_HAS_PROPERTY_KEYS
NAPI_EXTERN napi_status NAPI_CDECL node_api_create_property_key_latin1(
napi_env env, const char* str, size_t length, napi_value* result);
NAPI_EXTERN napi_status NAPI_CDECL node_api_create_property_key_utf8(
napi_env env, const char* str, size_t length, napi_value* result);
NAPI_EXTERN napi_status NAPI_CDECL node_api_create_property_key_utf16(
napi_env env, const char16_t* str, size_t length, napi_value* result);
#endif // NAPI_EXPERIMENTAL
#endif // NAPI_VERSION >= 10
NAPI_EXTERN napi_status NAPI_CDECL napi_create_symbol(napi_env env,
napi_value description,

2
src/js_native_api_v8.cc
View File

@ -2753,7 +2753,7 @@ napi_status NAPI_CDECL napi_create_reference(napi_env env,
CHECK_ARG(env, result);
v8::Local<v8::Value> v8_value = v8impl::V8LocalValueFromJsValue(value);
if (env->module_api_version != NAPI_VERSION_EXPERIMENTAL) {
if (env->module_api_version < 10) {
if (!(v8_value->IsObject() || v8_value->IsFunction() ||
v8_value->IsSymbol())) {
return napi_set_last_error(env, napi_invalid_arg);

10
src/js_native_api_v8.h
View File

@ -234,11 +234,11 @@ inline napi_status napi_set_last_error(node_api_basic_env basic_env,
CHECK_ENV_NOT_IN_GC((env)); \
RETURN_STATUS_IF_FALSE( \
(env), (env)->last_exception.IsEmpty(), napi_pending_exception); \
RETURN_STATUS_IF_FALSE((env), \
(env)->can_call_into_js(), \
(env->module_api_version == NAPI_VERSION_EXPERIMENTAL \
? napi_cannot_run_js \
: napi_pending_exception)); \
RETURN_STATUS_IF_FALSE( \
(env), \
(env)->can_call_into_js(), \
(env->module_api_version >= 10 ? napi_cannot_run_js \
: napi_pending_exception)); \
napi_clear_last_error((env)); \
v8impl::TryCatch try_catch((env))

14
src/node_api.cc
View File

@ -93,11 +93,11 @@ void node_napi_env__::CallbackIntoModule(T&& call) {
return;
}
node::Environment* node_env = env->node_env();
// If the module api version is less than NAPI_VERSION_EXPERIMENTAL,
// and the option --force-node-api-uncaught-exceptions-policy is not
// specified, emit a warning about the uncaught exception instead of
// triggering uncaught exception event.
if (env->module_api_version < NAPI_VERSION_EXPERIMENTAL &&
// If the module api version is less than 10, and the option
// --force-node-api-uncaught-exceptions-policy is not specified, emit a
// warning about the uncaught exception instead of triggering the uncaught
// exception event.
if (env->module_api_version < 10 &&
!node_env->options()->force_node_api_uncaught_exceptions_policy &&
!enforceUncaughtExceptionPolicy) {
ProcessEmitDeprecationWarning(
@ -678,11 +678,13 @@ node::addon_context_register_func get_node_api_context_register_func(
const char* module_name,
int32_t module_api_version) {
static_assert(
NODE_API_SUPPORTED_VERSION_MAX == 9,
NODE_API_SUPPORTED_VERSION_MAX == 10,
"New version of Node-API requires adding another else-if statement below "
"for the new version and updating this assert condition.");
if (module_api_version == 9) {
return node_api_context_register_func<9>;
} else if (module_api_version == 10) {
return node_api_context_register_func<10>;
} else if (module_api_version == NAPI_VERSION_EXPERIMENTAL) {
return node_api_context_register_func<NAPI_VERSION_EXPERIMENTAL>;
} else if (module_api_version >= NODE_API_SUPPORTED_VERSION_MIN &&

5
src/node_api.h
View File

@ -133,8 +133,7 @@ napi_create_external_buffer(napi_env env,
napi_value* result);
#endif // NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED
#ifdef NAPI_EXPERIMENTAL
#define NODE_API_EXPERIMENTAL_HAS_CREATE_BUFFER_FROM_ARRAYBUFFER
#if NAPI_VERSION >= 10
NAPI_EXTERN napi_status NAPI_CDECL
node_api_create_buffer_from_arraybuffer(napi_env env,
@ -142,7 +141,7 @@ node_api_create_buffer_from_arraybuffer(napi_env env,
size_t byte_offset,
size_t byte_length,
napi_value* result);
#endif // NAPI_EXPERIMENTAL
#endif // NAPI_VERSION >= 10
NAPI_EXTERN napi_status NAPI_CDECL napi_create_buffer_copy(napi_env env,
size_t length,

2
src/node_version.h
View File

@ -100,7 +100,7 @@
// The NAPI_VERSION supported by the runtime. This is the inclusive range of
// versions which the Node.js binary being built supports.
#define NODE_API_SUPPORTED_VERSION_MAX 9
#define NODE_API_SUPPORTED_VERSION_MAX 10
#define NODE_API_SUPPORTED_VERSION_MIN 1
// Node API modules use NAPI_VERSION 8 by default if it is not explicitly

4
test/js-native-api/test_cannot_run_js/binding.gyp
View File

@ -5,14 +5,14 @@
"sources": [
"test_cannot_run_js.c"
],
"defines": [ "NAPI_EXPERIMENTAL" ],
"defines": [ "NAPI_VERSION=10" ],
},
{
"target_name": "test_pending_exception",
"sources": [
"test_cannot_run_js.c"
],
"defines": [ "NAPI_VERSION=8" ],
"defines": [ "NAPI_VERSION=9" ],
}
]
}

16
test/js-native-api/test_cannot_run_js/test_cannot_run_js.c
View File

@ -22,7 +22,7 @@ static void Finalize(napi_env env, void* data, void* hint) {
// napi_pending_exception is returned). This is not deterministic from
// the point of view of the addon.
#ifdef NAPI_EXPERIMENTAL
#if NAPI_VERSION > 9
NODE_API_BASIC_ASSERT_RETURN_VOID(
result == napi_cannot_run_js || result == napi_ok,
"getting named property from global in finalizer should succeed "
@ -32,19 +32,10 @@ static void Finalize(napi_env env, void* data, void* hint) {
result == napi_pending_exception || result == napi_ok,
"getting named property from global in finalizer should succeed "
"or return napi_pending_exception");
#endif // NAPI_EXPERIMENTAL
#endif // NAPI_VERSION > 9
free(ref);
}
static void BasicFinalize(node_api_basic_env env, void* data, void* hint) {
#ifdef NAPI_EXPERIMENTAL
NODE_API_BASIC_CALL_RETURN_VOID(
env, node_api_post_finalizer(env, Finalize, data, hint));
#else
Finalize(env, data, hint);
#endif
}
static napi_value CreateRef(napi_env env, napi_callback_info info) {
size_t argc = 1;
napi_value cb;
@ -55,8 +46,7 @@ static napi_value CreateRef(napi_env env, napi_callback_info info) {
NODE_API_CALL(env, napi_typeof(env, cb, &value_type));
NODE_API_ASSERT(
env, value_type == napi_function, "argument must be function");
NODE_API_CALL(env,
napi_add_finalizer(env, cb, ref, BasicFinalize, NULL, ref));
NODE_API_CALL(env, napi_add_finalizer(env, cb, ref, Finalize, NULL, ref));
return cb;
}

2
test/js-native-api/test_general/test.js
View File

@ -34,7 +34,7 @@ assert.notStrictEqual(test_general.testGetPrototype(baseObject),
test_general.testGetPrototype(extendedObject));
// Test version management functions
assert.strictEqual(test_general.testGetVersion(), 9);
assert.strictEqual(test_general.testGetVersion(), 10);
[
123,

2
test/js-native-api/test_string/binding.gyp
View File

@ -7,7 +7,7 @@
"test_null.c",
],
"defines": [
"NAPI_EXPERIMENTAL",
"NAPI_VERSION=10",
],
},
],

2
test/node-api/test_buffer/binding.gyp
View File

@ -3,7 +3,7 @@
{
"target_name": "test_buffer",
"defines": [
'NAPI_EXPERIMENTAL'
'NAPI_VERSION=10'
],
"sources": [ "test_buffer.c" ]
},

4
test/node-api/test_reference_by_node_api_version/binding.gyp
View File

@ -3,12 +3,12 @@
{
"target_name": "test_reference_all_types",
"sources": [ "test_reference_by_node_api_version.c" ],
"defines": [ "NAPI_EXPERIMENTAL" ],
"defines": [ "NAPI_VERSION=10" ],
},
{
"target_name": "test_reference_obj_only",
"sources": [ "test_reference_by_node_api_version.c" ],
"defines": [ "NAPI_VERSION=8" ],
"defines": [ "NAPI_VERSION=9" ],
}
]
}