Commit 282a45d
doc: update wrapping-related documentation
Update the N-API documentation to reflect that wrapping no longer
affects the object's prototype chain.
PR-URL: #22363
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Minwoo Jung <minwoo@nodesource.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>1 parent 611f423 commit 282a45d
1 file changed
Lines changed: 7 additions & 13 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -3569,8 +3569,7 @@ napi_status napi_wrap(napi_env env, | |||
| 3569 | 3569 | ||
| 3570 | 3570 | - `[in] env`: The environment that the API is invoked under. | |
| 3571 | 3571 | - `[in] js_object`: The JavaScript object that will be the wrapper for the | |
| 3572 | - native object. This object _must_ have been created from the `prototype` of | ||
| 3573 | - a constructor that was created using `napi_define_class()`. | ||
| 3572 | + native object. | ||
| 3574 | 3573 | - `[in] native_object`: The native instance that will be wrapped in the | |
| 3575 | 3574 | JavaScript object. | |
| 3576 | 3575 | - `[in] finalize_cb`: Optional native callback that can be used to free the | |
@@ -3602,13 +3601,9 @@ temporarily during async operations that require the instance to remain valid. | |||
| 3602 | 3601 | ||
| 3603 | 3602 | *Caution*: The optional returned reference (if obtained) should be deleted via | |
| 3604 | 3603 | [`napi_delete_reference`][] ONLY in response to the finalize callback | |
| 3605 | - invocation. (If it is deleted before then, then the finalize callback may never | ||
| 3606 | - be invoked.) Therefore, when obtaining a reference a finalize callback is also | ||
| 3607 | - required in order to enable correct proper of the reference. | ||
| 3608 | - | ||
| 3609 | - This API may modify the prototype chain of the wrapper object. Afterward, | ||
| 3610 | - additional manipulation of the wrapper's prototype chain may cause | ||
| 3611 | - `napi_unwrap()` to fail. | ||
| 3604 | + invocation. If it is deleted before then, then the finalize callback may never | ||
| 3605 | + be invoked. Therefore, when obtaining a reference a finalize callback is also | ||
| 3606 | + required in order to enable correct disposal of the reference. | ||
| 3612 | 3607 | ||
| 3613 | 3608 | Calling `napi_wrap()` a second time on an object will return an error. To | |
| 3614 | 3609 | associate another native instance with the object, use `napi_remove_wrap()` | |
@@ -3658,10 +3653,9 @@ napi_status napi_remove_wrap(napi_env env, | |||
| 3658 | 3653 | Returns `napi_ok` if the API succeeded. | |
| 3659 | 3654 | ||
| 3660 | 3655 | Retrieves a native instance that was previously wrapped in the JavaScript | |
| 3661 | - object `js_object` using `napi_wrap()` and removes the wrapping, thereby | ||
| 3662 | - restoring the JavaScript object's prototype chain. If a finalize callback was | ||
| 3663 | - associated with the wrapping, it will no longer be called when the JavaScript | ||
| 3664 | - object becomes garbage-collected. | ||
| 3656 | + object `js_object` using `napi_wrap()` and removes the wrapping. If a finalize | ||
| 3657 | + callback was associated with the wrapping, it will no longer be called when the | ||
| 3658 | + JavaScript object becomes garbage-collected. | ||
| 3665 | 3659 | ||
| 3666 | 3660 | ## Simple Asynchronous Operations | |
| 3667 | 3661 | ||
0 commit comments