From aecc77baf3f79f2db567de455e3c8159bb35c464 Mon Sep 17 00:00:00 2001 From: Alba Mendez Date: Sun, 27 Mar 2022 15:57:13 +0200 Subject: [PATCH] doc: clarify napi_finalize behavior MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. PR-URL: https://github.com/nodejs/node/pull/42461 Reviewed-By: Rich Trott Reviewed-By: Tierney Cyren Reviewed-By: Tobias Nießen Reviewed-By: Michael Dawson Reviewed-By: Chengzhong Wu Reviewed-By: James M Snell --- doc/api/n-api.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 3d1741bad82359..709b080649fde9 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -5119,6 +5119,11 @@ 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. +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.