diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 77cc49946c4231..54c53efcef87f9 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. -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`