Skip to content

Commit

Permalink
doc: clarify napi_finalize behavior
Browse files Browse the repository at this point in the history
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]>
  • Loading branch information
mildsunrise authored and juanarbol committed May 31, 2022
1 parent 3684fd1 commit aecc77b
Showing 1 changed file with 5 additions and 0 deletions.
5 changes: 5 additions & 0 deletions doc/api/n-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down

0 comments on commit aecc77b

Please sign in to comment.