Commit aecc77b
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 <rtrott@gmail.com>
Reviewed-By: Tierney Cyren <hello@bnb.im>
Reviewed-By: Tobias Nießen <tniessen@tnie.de>
Reviewed-By: Michael Dawson <midawson@redhat.com>
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>1 parent 3684fd1 commit aecc77b
1 file changed
Lines changed: 5 additions & 0 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -5119,6 +5119,11 @@ invocation. If it is deleted before then, then the finalize callback may never | |||
| 5119 | 5119 | be invoked. Therefore, when obtaining a reference a finalize callback is also | |
| 5120 | 5120 | required in order to enable correct disposal of the reference. | |
| 5121 | 5121 | ||
| 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 | + | ||
| 5122 | 5127 | Calling `napi_wrap()` a second time on an object will return an error. To | |
| 5123 | 5128 | associate another native instance with the object, use `napi_remove_wrap()` | |
| 5124 | 5129 | first. | |
0 commit comments