Skip to content

Commit aecc77b

Browse files
mildsunrisejuanarbol
authored andcommitted
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. PR-URL: #42461 Reviewed-By: Rich Trott <[email protected]> Reviewed-By: Tierney Cyren <[email protected]> Reviewed-By: Tobias Nießen <[email protected]> Reviewed-By: Michael Dawson <[email protected]> Reviewed-By: Chengzhong Wu <[email protected]> Reviewed-By: James M Snell <[email protected]>
1 parent 3684fd1 commit aecc77b

File tree

1 file changed

+5
-0
lines changed

1 file changed

+5
-0
lines changed

doc/api/n-api.md

+5
Original file line numberDiff line numberDiff line change
@@ -5119,6 +5119,11 @@ invocation. If it is deleted before then, then the finalize callback may never
51195119
be invoked. Therefore, when obtaining a reference a finalize callback is also
51205120
required in order to enable correct disposal of the reference.
51215121
5122+
Finalizer callbacks may be deferred, leaving a window where the object has
5123+
been garbage collected (and the weak reference is invalid) but the finalizer
5124+
hasn't been called yet. When using `napi_get_reference_value()` on weak
5125+
references returned by `napi_wrap()`, you should still handle an empty result.
5126+
51225127
Calling `napi_wrap()` a second time on an object will return an error. To
51235128
associate another native instance with the object, use `napi_remove_wrap()`
51245129
first.

0 commit comments

Comments
 (0)