Skip to content

Commit eafe0c3

Browse files
vmoroztargos
authored andcommittedMay 30, 2023
node-api: napi_ref on all types is experimental
PR-URL: #47975 Reviewed-By: Chengzhong Wu <[email protected]> Reviewed-By: Michael Dawson <[email protected]>
1 parent ebb6536 commit eafe0c3

File tree

2 files changed

+19
-19
lines changed

2 files changed

+19
-19
lines changed
 

‎doc/api/n-api.md

+18-18
Original file line numberDiff line numberDiff line change
@@ -1652,23 +1652,23 @@ managed by scopes and all scopes must be closed before the end of a native
16521652
method.
16531653

16541654
Node-API provides methods for creating persistent references to values.
1655+
Currently Node-API only allows references to be created for a
1656+
limited set of value types, including object, external, function, and symbol.
1657+
16551658
Each reference has an associated count with a value of 0 or higher,
16561659
which determines whether the reference will keep the corresponding value alive.
16571660
References with a count of 0 do not prevent values from being collected.
16581661
Values of object (object, function, external) and symbol types are becoming
16591662
'weak' references and can still be accessed while they are not collected.
1660-
Values of other types are released when the count becomes 0
1661-
and cannot be accessed from the reference any more.
16621663
Any count greater than 0 will prevent the values from being collected.
16631664

16641665
Symbol values have different flavors. The true weak reference behavior is
1665-
only supported by local symbols created with the `Symbol()` constructor call.
1666-
Globally registered symbols created with the `Symbol.for()` call remain
1667-
always strong references because the garbage collector does not collect them.
1668-
The same is true for well-known symbols such as `Symbol.iterator`. They are
1669-
also never collected by the garbage collector. JavaScript's `WeakRef` and
1670-
`WeakMap` types return an error when registered symbols are used,
1671-
but they succeed for local and well-known symbols.
1666+
only supported by local symbols created with the `napi_create_symbol` function
1667+
or the JavaScript `Symbol()` constructor calls. Globally registered symbols
1668+
created with the `node_api_symbol_for` function or JavaScript `Symbol.for()`
1669+
function calls remain always strong references because the garbage collector
1670+
does not collect them. The same is true for well-known symbols such as
1671+
`Symbol.iterator`. They are also never collected by the garbage collector.
16721672

16731673
References can be created with an initial reference count. The count can
16741674
then be modified through [`napi_reference_ref`][] and
@@ -1679,11 +1679,6 @@ will return `NULL` for the returned `napi_value`. An attempt to call
16791679
[`napi_reference_ref`][] for a reference whose object has been collected
16801680
results in an error.
16811681

1682-
Node-API versions 8 and earlier only allow references to be created for a
1683-
limited set of value types, including object, external, function, and symbol.
1684-
However, in newer Node-API versions, references can be created for any
1685-
value type.
1686-
16871682
References must be deleted once they are no longer required by the addon. When
16881683
a reference is deleted, it will no longer prevent the corresponding object from
16891684
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
17011696
will not be freed. This can be avoided by calling
17021697
`napi_delete_reference` in addition to `napi_reference_unref` when possible.
17031698

1699+
**Change History:**
1700+
1701+
* Experimental (`NAPI_EXPERIMENTAL` is defined):
1702+
1703+
References can be created for all value types. The new supported value
1704+
types do not support weak reference semantic and the values of these types
1705+
are released when the reference count becomes 0 and cannot be accessed from
1706+
the reference anymore.
1707+
17041708
#### `napi_create_reference`
17051709

17061710
<!-- YAML
@@ -1725,10 +1729,6 @@ Returns `napi_ok` if the API succeeded.
17251729
This API creates a new reference with the specified reference count
17261730
to the value passed in.
17271731

1728-
In Node-API version 8 and earlier, a reference could only be created for
1729-
object, function, external, and symbol value types. However, in newer Node-API
1730-
versions, a reference can be created for any value type.
1731-
17321732
#### `napi_delete_reference`
17331733

17341734
<!-- YAML

‎src/js_native_api_v8.cc

+1-1
Original file line numberDiff line numberDiff line change
@@ -2436,7 +2436,7 @@ napi_status NAPI_CDECL napi_create_reference(napi_env env,
24362436
CHECK_ARG(env, result);
24372437

24382438
v8::Local<v8::Value> v8_value = v8impl::V8LocalValueFromJsValue(value);
2439-
if (env->module_api_version <= 8) {
2439+
if (env->module_api_version != NAPI_VERSION_EXPERIMENTAL) {
24402440
if (!(v8_value->IsObject() || v8_value->IsFunction() ||
24412441
v8_value->IsSymbol())) {
24422442
return napi_set_last_error(env, napi_invalid_arg);

0 commit comments

Comments
 (0)
Please sign in to comment.