From 7ab1196cb67354eda832b4aae117e147ed191c06 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Thu, 17 Feb 2022 13:49:51 -0500 Subject: [PATCH 1/4] doc: clarify persistent ref behavior Add explanation of case to be careful of in order to avoid native memory being kept alive. Signed-off-by: Michael Dawson --- doc/api/n-api.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 909e7d88ea6f4b..0d006ac351d4f4 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -1649,7 +1649,14 @@ the corresponding object on the heap being retained forever. There can be multiple persistent references created which refer to the same object, each of which will either keep the object live or not based on its -individual count. +individual count. Multiple persistent references to the same object +can result in unexpectedly keeping alive native memory. The native structures +for a persistent reference must be kept alive until finalizers for the +referenced object are executed. If a new persistent reference to the +is created for the same object, the finalizers for that object will not be +run and the native memory from 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. #### `napi_create_reference` From de0a9e581c2204bb33390c9c62da26e28645823d Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Mon, 21 Feb 2022 16:01:55 -0500 Subject: [PATCH 2/4] Update doc/api/n-api.md Co-authored-by: Mohammed Keyvanzadeh --- doc/api/n-api.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 0d006ac351d4f4..803267610de5fd 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -1652,11 +1652,11 @@ object, each of which will either keep the object live or not based on its individual count. Multiple persistent references to the same object can result in unexpectedly keeping alive native memory. The native structures for a persistent reference must be kept alive until finalizers for the -referenced object are executed. If a new persistent reference to the -is created for the same object, the finalizers for that object will not be -run and the native memory from 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. +referenced object are executed. If a new persistent reference is created +for the same object, the finalizers for that object will not be run and the +native memory from 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. #### `napi_create_reference` From 24c862be9cda95d643f7caef5de5ac45c0106b29 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Mon, 21 Feb 2022 16:05:44 -0500 Subject: [PATCH 3/4] squash: address comments --- doc/api/n-api.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 803267610de5fd..e26e8b415e24c1 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -1653,10 +1653,10 @@ individual count. Multiple persistent references to the same object can result in unexpectedly keeping alive native memory. The native structures for a persistent reference must be kept alive until finalizers for the referenced object are executed. If a new persistent reference is created -for the same object, the finalizers for that object will not be run and the -native memory from 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. +for the same object, the finalizers for that object will not be +run and the native memory pointed by the earlier persistent reference +will not be will not be freed. This can be avoided by calling +`napi_delete_reference` in addition to `napi_reference_unref` when possible. #### `napi_create_reference` From 5d744deb98ec54e0c341a40c686591f62d64e977 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Tue, 22 Feb 2022 09:46:34 -0500 Subject: [PATCH 4/4] fixup --- doc/api/n-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index e26e8b415e24c1..4a67c680372b33 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -1655,7 +1655,7 @@ for a persistent reference must be kept alive until finalizers for the referenced object are executed. If a new persistent reference is created for the same object, the finalizers for that object will not be run and the native memory pointed by the earlier persistent reference -will not be will not be freed. This can be avoided by calling +will not be freed. This can be avoided by calling `napi_delete_reference` in addition to `napi_reference_unref` when possible. #### `napi_create_reference`