Skip to content

Commit c2f4d8d

Browse files
gabrielschulhofaduh95
gabrielschulhof
authored and
aduh95
committed
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: #55676 Reviewed-By: Chengzhong Wu <legendecas@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com>
1 parent 4f77920 commit c2f4d8d

File tree

14 files changed

+46
-65
lines changed

14 files changed

+46
-65
lines changed

‎doc/api/n-api.md

Lines changed: 8 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1748,7 +1748,7 @@ will not be freed. This can be avoided by calling
17481748

17491749
**Change History:**
17501750

1751-
* Experimental (`NAPI_EXPERIMENTAL` is defined):
1751+
* Version 10 (`NAPI_VERSION` is defined as `10` or higher):
17521752

17531753
References can be created for all value types. The new supported value
17541754
types do not support weak reference semantic and the values of these types
@@ -2700,10 +2700,9 @@ JavaScript `TypedArray` objects are described in
27002700

27012701
<!-- YAML
27022702
added: v23.0.0
2703+
napiVersion: 10
27032704
-->
27042705

2705-
> Stability: 1 - Experimental
2706-
27072706
```c
27082707
napi_status NAPI_CDECL node_api_create_buffer_from_arraybuffer(napi_env env,
27092708
napi_value arraybuffer,
@@ -2965,10 +2964,9 @@ The JavaScript `string` type is described in
29652964
added:
29662965
- v20.4.0
29672966
- v18.18.0
2967+
napiVersion: 10
29682968
-->
29692969

2970-
> Stability: 1 - Experimental
2971-
29722970
```c
29732971
napi_status
29742972
node_api_create_external_string_latin1(napi_env env,
@@ -3045,10 +3043,9 @@ The JavaScript `string` type is described in
30453043
added:
30463044
- v20.4.0
30473045
- v18.18.0
3046+
napiVersion: 10
30483047
-->
30493048

3050-
> Stability: 1 - Experimental
3051-
30523049
```c
30533050
napi_status
30543051
node_api_create_external_string_utf16(napi_env env,
@@ -3140,10 +3137,9 @@ creation methods.
31403137
added:
31413138
- v22.9.0
31423139
- v20.18.0
3140+
napiVersion: 10
31433141
-->
31443142

3145-
> Stability: 1 - Experimental
3146-
31473143
```c
31483144
napi_status NAPI_CDECL node_api_create_property_key_latin1(napi_env env,
31493145
const char* str,
@@ -3175,10 +3171,9 @@ The JavaScript `string` type is described in
31753171
added:
31763172
- v21.7.0
31773173
- v20.12.0
3174+
napiVersion: 10
31783175
-->
31793176

3180-
> Stability: 1 - Experimental
3181-
31823177
```c
31833178
napi_status NAPI_CDECL node_api_create_property_key_utf16(napi_env env,
31843179
const char16_t* str,
@@ -3208,10 +3203,9 @@ The JavaScript `string` type is described in
32083203
added:
32093204
- v22.9.0
32103205
- v20.18.0
3206+
napiVersion: 10
32113207
-->
32123208

3213-
> Stability: 1 - Experimental
3214-
32153209
```c
32163210
napi_status NAPI_CDECL node_api_create_property_key_utf8(napi_env env,
32173211
const char* str,
@@ -6531,7 +6525,7 @@ napi_create_threadsafe_function(napi_env env,
65316525

65326526
**Change History:**
65336527

6534-
* Experimental (`NAPI_EXPERIMENTAL` is defined):
6528+
* Version 10 (`NAPI_VERSION` is defined as `10` or higher):
65356529

65366530
Uncaught exceptions thrown in `call_js_cb` are handled with the
65376531
[`'uncaughtException'`][] event, instead of being ignored.

‎doc/contributing/releases-node-api.md

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,7 @@ with:
8585
8686
```bash
8787
grep \
88-
-E \
88+
-nHE \
8989
'N(ODE_)?API_EXPERIMENTAL' \
9090
src/js_native_api{_types,}.h \
9191
src/node_api{_types,}.h
@@ -95,13 +95,13 @@ and update the define version guards with the release version:
9595

9696
```diff
9797
- #ifdef NAPI_EXPERIMENTAL
98-
+ #if NAPI_VERSION >= 10
98+
+ #if NAPI_VERSION >= 11
9999

100100
NAPI_EXTERN napi_status NAPI_CDECL
101101
node_api_function(napi_env env);
102102

103103
- #endif // NAPI_EXPERIMENTAL
104-
+ #endif // NAPI_VERSION >= 10
104+
+ #endif // NAPI_VERSION >= 11
105105
```
106106
107107
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
121121
#### Step 2. Update runtime version guards
122122

123123
If this release includes runtime behavior version guards, the relevant commits
124-
should already include `NAPI_VERSION_EXPERIMENTAL` guard for the change. Check
125-
for these guards with:
124+
should already include the `NAPI_VERSION_EXPERIMENTAL` guard for the change.
125+
Check for these guards with:
126126

127127
```bash
128-
grep NAPI_VERSION_EXPERIMENTAL src/js_native_api_v8* src/node_api.cc
128+
grep -nH NAPI_VERSION_EXPERIMENTAL src/js_native_api_v8* src/node_api.cc
129129
```
130130

131131
and substitute this guard version with the release version `x`.
@@ -138,7 +138,7 @@ Check for these definitions with:
138138

139139
```bash
140140
grep \
141-
-E \
141+
-nHE \
142142
'N(ODE_)?API_EXPERIMENTAL' \
143143
test/node-api/*/{*.{h,c},binding.gyp} \
144144
test/js-native-api/*/{*.{h,c},binding.gyp}
@@ -170,7 +170,7 @@ stability banner:
170170
<!-- YAML
171171
added:
172172
- v1.2.3
173-
+ napiVersion: 10
173+
+ napiVersion: 11
174174
-->
175175

176176
- > Stability: 1 - Experimental
@@ -186,7 +186,7 @@ For all runtime version guards updated in Step 2, check for these definitions
186186
with:
187187

188188
```bash
189-
grep NAPI_EXPERIMENTAL doc/api/n-api.md
189+
grep -nH NAPI_EXPERIMENTAL doc/api/n-api.md
190190
```
191191

192192
In `doc/api/n-api.md`, update the `experimental` change history item to be the

‎src/js_native_api.h

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -92,8 +92,7 @@ NAPI_EXTERN napi_status NAPI_CDECL napi_create_string_utf16(napi_env env,
9292
const char16_t* str,
9393
size_t length,
9494
napi_value* result);
95-
#ifdef NAPI_EXPERIMENTAL
96-
#define NODE_API_EXPERIMENTAL_HAS_EXTERNAL_STRINGS
95+
#if NAPI_VERSION >= 10
9796
NAPI_EXTERN napi_status NAPI_CDECL node_api_create_external_string_latin1(
9897
napi_env env,
9998
char* str,
@@ -110,17 +109,14 @@ node_api_create_external_string_utf16(napi_env env,
110109
void* finalize_hint,
111110
napi_value* result,
112111
bool* copied);
113-
#endif // NAPI_EXPERIMENTAL
114112

115-
#ifdef NAPI_EXPERIMENTAL
116-
#define NODE_API_EXPERIMENTAL_HAS_PROPERTY_KEYS
117113
NAPI_EXTERN napi_status NAPI_CDECL node_api_create_property_key_latin1(
118114
napi_env env, const char* str, size_t length, napi_value* result);
119115
NAPI_EXTERN napi_status NAPI_CDECL node_api_create_property_key_utf8(
120116
napi_env env, const char* str, size_t length, napi_value* result);
121117
NAPI_EXTERN napi_status NAPI_CDECL node_api_create_property_key_utf16(
122118
napi_env env, const char16_t* str, size_t length, napi_value* result);
123-
#endif // NAPI_EXPERIMENTAL
119+
#endif // NAPI_VERSION >= 10
124120

125121
NAPI_EXTERN napi_status NAPI_CDECL napi_create_symbol(napi_env env,
126122
napi_value description,

‎src/js_native_api_v8.cc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2753,7 +2753,7 @@ napi_status NAPI_CDECL napi_create_reference(napi_env env,
27532753
CHECK_ARG(env, result);
27542754

27552755
v8::Local<v8::Value> v8_value = v8impl::V8LocalValueFromJsValue(value);
2756-
if (env->module_api_version != NAPI_VERSION_EXPERIMENTAL) {
2756+
if (env->module_api_version < 10) {
27572757
if (!(v8_value->IsObject() || v8_value->IsFunction() ||
27582758
v8_value->IsSymbol())) {
27592759
return napi_set_last_error(env, napi_invalid_arg);

‎src/js_native_api_v8.h

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -234,11 +234,11 @@ inline napi_status napi_set_last_error(node_api_basic_env basic_env,
234234
CHECK_ENV_NOT_IN_GC((env)); \
235235
RETURN_STATUS_IF_FALSE( \
236236
(env), (env)->last_exception.IsEmpty(), napi_pending_exception); \
237-
RETURN_STATUS_IF_FALSE((env), \
238-
(env)->can_call_into_js(), \
239-
(env->module_api_version == NAPI_VERSION_EXPERIMENTAL \
240-
? napi_cannot_run_js \
241-
: napi_pending_exception)); \
237+
RETURN_STATUS_IF_FALSE( \
238+
(env), \
239+
(env)->can_call_into_js(), \
240+
(env->module_api_version >= 10 ? napi_cannot_run_js \
241+
: napi_pending_exception)); \
242242
napi_clear_last_error((env)); \
243243
v8impl::TryCatch try_catch((env))
244244

‎src/node_api.cc

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -93,11 +93,11 @@ void node_napi_env__::CallbackIntoModule(T&& call) {
9393
return;
9494
}
9595
node::Environment* node_env = env->node_env();
96-
// If the module api version is less than NAPI_VERSION_EXPERIMENTAL,
97-
// and the option --force-node-api-uncaught-exceptions-policy is not
98-
// specified, emit a warning about the uncaught exception instead of
99-
// triggering uncaught exception event.
100-
if (env->module_api_version < NAPI_VERSION_EXPERIMENTAL &&
96+
// If the module api version is less than 10, and the option
97+
// --force-node-api-uncaught-exceptions-policy is not specified, emit a
98+
// warning about the uncaught exception instead of triggering the uncaught
99+
// exception event.
100+
if (env->module_api_version < 10 &&
101101
!node_env->options()->force_node_api_uncaught_exceptions_policy &&
102102
!enforceUncaughtExceptionPolicy) {
103103
ProcessEmitDeprecationWarning(
@@ -678,11 +678,13 @@ node::addon_context_register_func get_node_api_context_register_func(
678678
const char* module_name,
679679
int32_t module_api_version) {
680680
static_assert(
681-
NODE_API_SUPPORTED_VERSION_MAX == 9,
681+
NODE_API_SUPPORTED_VERSION_MAX == 10,
682682
"New version of Node-API requires adding another else-if statement below "
683683
"for the new version and updating this assert condition.");
684684
if (module_api_version == 9) {
685685
return node_api_context_register_func<9>;
686+
} else if (module_api_version == 10) {
687+
return node_api_context_register_func<10>;
686688
} else if (module_api_version == NAPI_VERSION_EXPERIMENTAL) {
687689
return node_api_context_register_func<NAPI_VERSION_EXPERIMENTAL>;
688690
} else if (module_api_version >= NODE_API_SUPPORTED_VERSION_MIN &&

‎src/node_api.h

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -133,16 +133,15 @@ napi_create_external_buffer(napi_env env,
133133
napi_value* result);
134134
#endif // NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED
135135

136-
#ifdef NAPI_EXPERIMENTAL
137-
#define NODE_API_EXPERIMENTAL_HAS_CREATE_BUFFER_FROM_ARRAYBUFFER
136+
#if NAPI_VERSION >= 10
138137

139138
NAPI_EXTERN napi_status NAPI_CDECL
140139
node_api_create_buffer_from_arraybuffer(napi_env env,
141140
napi_value arraybuffer,
142141
size_t byte_offset,
143142
size_t byte_length,
144143
napi_value* result);
145-
#endif // NAPI_EXPERIMENTAL
144+
#endif // NAPI_VERSION >= 10
146145

147146
NAPI_EXTERN napi_status NAPI_CDECL napi_create_buffer_copy(napi_env env,
148147
size_t length,

‎src/node_version.h

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -100,7 +100,7 @@
100100

101101
// The NAPI_VERSION supported by the runtime. This is the inclusive range of
102102
// versions which the Node.js binary being built supports.
103-
#define NODE_API_SUPPORTED_VERSION_MAX 9
103+
#define NODE_API_SUPPORTED_VERSION_MAX 10
104104
#define NODE_API_SUPPORTED_VERSION_MIN 1
105105

106106
// Node API modules use NAPI_VERSION 8 by default if it is not explicitly

‎test/js-native-api/test_cannot_run_js/binding.gyp

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,14 +5,14 @@
55
"sources": [
66
"test_cannot_run_js.c"
77
],
8-
"defines": [ "NAPI_EXPERIMENTAL" ],
8+
"defines": [ "NAPI_VERSION=10" ],
99
},
1010
{
1111
"target_name": "test_pending_exception",
1212
"sources": [
1313
"test_cannot_run_js.c"
1414
],
15-
"defines": [ "NAPI_VERSION=8" ],
15+
"defines": [ "NAPI_VERSION=9" ],
1616
}
1717
]
1818
}

‎test/js-native-api/test_cannot_run_js/test_cannot_run_js.c

Lines changed: 3 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ static void Finalize(napi_env env, void* data, void* hint) {
2222
// napi_pending_exception is returned). This is not deterministic from
2323
// the point of view of the addon.
2424

25-
#ifdef NAPI_EXPERIMENTAL
25+
#if NAPI_VERSION > 9
2626
NODE_API_BASIC_ASSERT_RETURN_VOID(
2727
result == napi_cannot_run_js || result == napi_ok,
2828
"getting named property from global in finalizer should succeed "
@@ -32,19 +32,10 @@ static void Finalize(napi_env env, void* data, void* hint) {
3232
result == napi_pending_exception || result == napi_ok,
3333
"getting named property from global in finalizer should succeed "
3434
"or return napi_pending_exception");
35-
#endif // NAPI_EXPERIMENTAL
35+
#endif // NAPI_VERSION > 9
3636
free(ref);
3737
}
3838

39-
static void BasicFinalize(node_api_basic_env env, void* data, void* hint) {
40-
#ifdef NAPI_EXPERIMENTAL
41-
NODE_API_BASIC_CALL_RETURN_VOID(
42-
env, node_api_post_finalizer(env, Finalize, data, hint));
43-
#else
44-
Finalize(env, data, hint);
45-
#endif
46-
}
47-
4839
static napi_value CreateRef(napi_env env, napi_callback_info info) {
4940
size_t argc = 1;
5041
napi_value cb;
@@ -55,8 +46,7 @@ static napi_value CreateRef(napi_env env, napi_callback_info info) {
5546
NODE_API_CALL(env, napi_typeof(env, cb, &value_type));
5647
NODE_API_ASSERT(
5748
env, value_type == napi_function, "argument must be function");
58-
NODE_API_CALL(env,
59-
napi_add_finalizer(env, cb, ref, BasicFinalize, NULL, ref));
49+
NODE_API_CALL(env, napi_add_finalizer(env, cb, ref, Finalize, NULL, ref));
6050
return cb;
6151
}
6252

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy