diff options
| author | Alba Mendez <me@alba.sh> | 2022-03-27 16:57:13 +0300 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2022-03-27 16:57:13 +0300 |
| commit | 01a230032b9947194183655cfb7cff8c69355f72 (patch) | |
| tree | 50e359baad0b1a44b040821d4fa0cf5299702c8e /doc/api/n-api.md | |
| parent | 9c2d12474f775b54ea53e3026f7d89044cc77ec8 (diff) | |
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: https://github.com/nodejs/node/pull/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>
Diffstat (limited to 'doc/api/n-api.md')
| -rw-r--r-- | doc/api/n-api.md | 5 |
1 files changed, 5 insertions, 0 deletions
diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 4a67c680372..002f8be0a56 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -5123,6 +5123,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. |