From 4b280d5361dc394bc788869c70fb30b75b49d5c0 Mon Sep 17 00:00:00 2001 From: Vladimir Morozov Date: Fri, 12 May 2023 07:12:11 -0700 Subject: [PATCH] node-api: napi_ref on all types is experimental PR-URL: https://github.com/nodejs/node/pull/47975 Reviewed-By: Chengzhong Wu Reviewed-By: Michael Dawson --- doc/api/n-api.md | 36 ++++++++++++++++++------------------ src/js_native_api_v8.cc | 2 +- 2 files changed, 19 insertions(+), 19 deletions(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 78df0d4c03ae78..e65352295cff99 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -1650,23 +1650,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 @@ -1677,11 +1677,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 @@ -1699,6 +1694,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`