From f428d2de0517d779afc2eaac30164465356c07bc Mon Sep 17 00:00:00 2001 From: Alba Mendez Date: Fri, 25 Mar 2022 03:02:59 +0100 Subject: [PATCH 1/2] doc: clarify napi_finalize behavior We currently defer finalizer callbacks until the loop is idle. Warn users that the weak reference returned by napi_wrap() isn't guaranteed to be valid just because the finalizer hasn't yet been called. --- doc/api/n-api.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 4a67c680372b33..94c6de2315f33b 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -5123,6 +5123,12 @@ invocation. If it is deleted before then, then the finalize callback may never be invoked. Therefore, when obtaining a reference a finalize callback is also required in order to enable correct disposal of the reference. +_Caution_: Finalizer callbacks may be deferred, leaving a window where the +object has been garbage collected (and the weak reference is invalid) but +the finalizer hasn't been called yet. When using `napi_get_reference_value` +on weak references returned by `napi_wrap()`, you should still handle an +empty result. + Calling `napi_wrap()` a second time on an object will return an error. To associate another native instance with the object, use `napi_remove_wrap()` first. From f5ceb311b87693dc20caee74dad892548d0e07a2 Mon Sep 17 00:00:00 2001 From: Alba Mendez Date: Fri, 25 Mar 2022 03:59:48 +0100 Subject: [PATCH 2/2] fixup --- doc/api/n-api.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 94c6de2315f33b..002f8be0a568f7 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -5123,11 +5123,10 @@ invocation. If it is deleted before then, then the finalize callback may never be invoked. Therefore, when obtaining a reference a finalize callback is also required in order to enable correct disposal of the reference. -_Caution_: Finalizer callbacks may be deferred, leaving a window where the -object has been garbage collected (and the weak reference is invalid) but -the finalizer hasn't been called yet. When using `napi_get_reference_value` -on weak references returned by `napi_wrap()`, you should still handle an -empty result. +Finalizer callbacks may be deferred, leaving a window where the object has +been garbage collected (and the weak reference is invalid) but the finalizer +hasn't been called yet. When using `napi_get_reference_value()` on weak +references returned by `napi_wrap()`, you should still handle an empty result. Calling `napi_wrap()` a second time on an object will return an error. To associate another native instance with the object, use `napi_remove_wrap()`