@@ -1652,23 +1652,23 @@ managed by scopes and all scopes must be closed before the end of a native
1652
1652
method.
1653
1653
1654
1654
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
+
1655
1658
Each reference has an associated count with a value of 0 or higher,
1656
1659
which determines whether the reference will keep the corresponding value alive.
1657
1660
References with a count of 0 do not prevent values from being collected.
1658
1661
Values of object (object, function, external) and symbol types are becoming
1659
1662
'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.
1662
1663
Any count greater than 0 will prevent the values from being collected.
1663
1664
1664
1665
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.
1672
1672
1673
1673
References can be created with an initial reference count. The count can
1674
1674
then be modified through [`napi_reference_ref`][] and
@@ -1679,11 +1679,6 @@ will return `NULL` for the returned `napi_value`. An attempt to call
1679
1679
[`napi_reference_ref`][] for a reference whose object has been collected
1680
1680
results in an error.
1681
1681
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
-
1687
1682
References must be deleted once they are no longer required by the addon. When
1688
1683
a reference is deleted, it will no longer prevent the corresponding object from
1689
1684
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
1701
1696
will not be freed. This can be avoided by calling
1702
1697
`napi_delete_reference` in addition to `napi_reference_unref` when possible.
1703
1698
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
+
1704
1708
#### `napi_create_reference`
1705
1709
1706
1710
<!-- YAML
@@ -1725,10 +1729,6 @@ Returns `napi_ok` if the API succeeded.
1725
1729
This API creates a new reference with the specified reference count
1726
1730
to the value passed in.
1727
1731
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
-
1732
1732
#### `napi_delete_reference`
1733
1733
1734
1734
<!-- YAML
0 commit comments