1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

node-api: napi_ref on all types is experimental

Browse Source 
PR-URL: https://github.com/nodejs/node/pull/47975
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
Reviewed-By: Michael Dawson <midawson@redhat.com>
This commit is contained in:
Vladimir Morozov 2023-05-12 07:12:11 -07:00 committed by Michael Dawson
parent 8b6947fac1
commit 0063669cce
2 changed files with 19 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -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.
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.
Node-API versions 8 and earlier only allow 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.
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,15 @@ 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.
**Change History:**
* Experimental (`NAPI_EXPERIMENTAL` is defined):
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 reference count becomes 0 and cannot be accessed from
the reference anymore.
#### `napi_create_reference`
<!-- YAML
@ -1725,10 +1729,6 @@ 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.
#### `napi_delete_reference`
<!-- YAML

2
src/js_native_api_v8.cc
View File

@ -2436,7 +2436,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 <= 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);