From 44dba47690f769f8af735c15a015fddcf50ba158 Mon Sep 17 00:00:00 2001 From: Vladimir Morozov Date: Fri, 12 May 2023 07:12:11 -0700 Subject: [PATCH 1/5] node-api: napi_ref for all value types is experimental --- doc/api/n-api.md | 16 ++++++++-------- src/js_native_api_v8.cc | 2 +- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 77cc49946c4231..656b0fcb868c70 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -1657,8 +1657,8 @@ which determines whether the reference will keep the corresponding value alive. References with a count of 0 do not prevent values from being collected. Values of object (object, function, external) and symbol types are becoming 'weak' references and can still be accessed while they are not collected. -Values of other types are released when the count becomes 0 -and cannot be accessed from the reference any more. +In experimental Node-API version values of other types are released when the +count becomes 0 and cannot be accessed from the reference any more. Any count greater than 0 will prevent the values from being collected. Symbol values have different flavors. The true weak reference behavior is @@ -1679,10 +1679,10 @@ will return `NULL` for the returned `napi_value`. An attempt to call [`napi_reference_ref`][] for a reference whose object has been collected results in an error. -Node-API versions 8 and earlier only allow references to be created for a +Currently Node-API only allows references to be created for a limited set of value types, including object, external, function, and symbol. -However, in newer Node-API versions, references can be created for any -value type. +However, in the experimental Node-API version, references can be created for +any value type. References must be deleted once they are no longer required by the addon. When a reference is deleted, it will no longer prevent the corresponding object from @@ -1725,9 +1725,9 @@ Returns `napi_ok` if the API succeeded. This API creates a new reference with the specified reference count to the value passed in. -In Node-API version 8 and earlier, a reference could only be created for -object, function, external, and symbol value types. However, in newer Node-API -versions, a reference can be created for any value type. +In current Node-API version a reference can be created only for +object, function, external, and symbol value types. However, in the +experimental Node-API version, a reference can be created for any value type. #### `napi_delete_reference` diff --git a/src/js_native_api_v8.cc b/src/js_native_api_v8.cc index 9cbcd2445d1980..827f3603efc5d8 100644 --- a/src/js_native_api_v8.cc +++ b/src/js_native_api_v8.cc @@ -2436,7 +2436,7 @@ napi_status NAPI_CDECL napi_create_reference(napi_env env, CHECK_ARG(env, result); v8::Local v8_value = v8impl::V8LocalValueFromJsValue(value); - if (env->module_api_version <= 8) { + if (env->module_api_version != NAPI_VERSION_EXPERIMENTAL) { if (!(v8_value->IsObject() || v8_value->IsFunction() || v8_value->IsSymbol())) { return napi_set_last_error(env, napi_invalid_arg); From 326c6b310722ba5a63ee072eecaa022700fcf6e8 Mon Sep 17 00:00:00 2001 From: Vladimir Morozov Date: Mon, 15 May 2023 08:57:40 -0700 Subject: [PATCH 2/5] extract experimental behavior into a paragraph --- doc/api/n-api.md | 33 +++++++++++++++------------------ 1 file changed, 15 insertions(+), 18 deletions(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 656b0fcb868c70..e02185f1759c73 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -1652,23 +1652,23 @@ managed by scopes and all scopes must be closed before the end of a native method. Node-API provides methods for creating persistent references to values. +Currently Node-API only allows references to be created for a +limited set of value types, including object, external, function, and symbol. + Each reference has an associated count with a value of 0 or higher, which determines whether the reference will keep the corresponding value alive. References with a count of 0 do not prevent values from being collected. Values of object (object, function, external) and symbol types are becoming 'weak' references and can still be accessed while they are not collected. -In experimental Node-API version values of other types are released when the -count becomes 0 and cannot be accessed from the reference any more. Any count greater than 0 will prevent the values from being collected. Symbol values have different flavors. The true weak reference behavior is -only supported by local symbols created with the `Symbol()` constructor call. -Globally registered symbols created with the `Symbol.for()` call remain -always strong references because the garbage collector does not collect them. -The same is true for well-known symbols such as `Symbol.iterator`. They are -also never collected by the garbage collector. JavaScript's `WeakRef` and -`WeakMap` types return an error when registered symbols are used, -but they succeed for local and well-known symbols. +only supported by local symbols created with the `napi_create_symbol` function +or the JavaScript `Symbol()` constructor calls. Globally registered symbols +created with the `node_api_symbol_for` function or JavaScript `Symbol.for()` +function calls remain always strong references because the garbage collector +does not collect them. The same is true for well-known symbols such as +`Symbol.iterator`. They are also never collected by the garbage collector. References can be created with an initial reference count. The count can then be modified through [`napi_reference_ref`][] and @@ -1679,11 +1679,6 @@ will return `NULL` for the returned `napi_value`. An attempt to call [`napi_reference_ref`][] for a reference whose object has been collected results in an error. -Currently Node-API only allows references to be created for a -limited set of value types, including object, external, function, and symbol. -However, in the experimental Node-API version, references can be created for -any value type. - References must be deleted once they are no longer required by the addon. When a reference is deleted, it will no longer prevent the corresponding object from being collected. Failure to delete a persistent reference results in @@ -1701,6 +1696,12 @@ run and the native memory pointed by the earlier persistent reference will not be freed. This can be avoided by calling `napi_delete_reference` in addition to `napi_reference_unref` when possible. +**Experimental behavior changes:** +When `NAPI_EXPERIMENTAL` is defined, the 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 are released when the +count becomes 0 and cannot be accessed from the reference any more. + #### `napi_create_reference`