From a71fb978a40b5251fdb012bab5e03598d5397a10 Mon Sep 17 00:00:00 2001 From: legendecas Date: Tue, 1 Oct 2019 21:36:56 +0800 Subject: n-api,doc: clarify napi_finalize related APIs All these APIs have napi_finalize parameter but they don't behave exactly the same. Fixes: https://github.com/nodejs/node/issues/29750 PR-URL: https://github.com/nodejs/node/pull/29797 Reviewed-By: Gabriel Schulhof Reviewed-By: Rich Trott Reviewed-By: Michael Dawson --- doc/api/n-api.md | 32 ++++++++++++++++++++++++++++---- 1 file changed, 28 insertions(+), 4 deletions(-) (limited to 'doc') diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 40bb604d65..ff4f9da3e8 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -1809,9 +1809,15 @@ Returns `napi_ok` if the API succeeded. This API allocates a JavaScript value with external data attached to it. This is used to pass external data through JavaScript code, so it can be retrieved -later by native code. The API allows the caller to pass in a finalize callback, -in case the underlying native resource needs to be cleaned up when the external -JavaScript value gets collected. +later by native code using [`napi_get_value_external`]. + +The API adds a `napi_finalize` callback which will be called when the JavaScript +object just created is ready for garbage collection. It is similar to +`napi_wrap()` except that: + +* the native data cannot be retrieved later using `napi_unwrap()`, +* nor can it be removed later using `napi_remove_wrap()`, and +* the object created by the API can be used with `napi_wrap()`. The created value is not an object, and therefore does not support additional properties. It is considered a distinct value type: calling `napi_typeof()` with @@ -1850,6 +1856,14 @@ The underlying byte buffer of the `ArrayBuffer` is externally allocated and managed. The caller must ensure that the byte buffer remains valid until the finalize callback is called. +The API adds a `napi_finalize` callback which will be called when the JavaScript +object just created is ready for garbage collection. It is similar to +`napi_wrap()` except that: + +* the native data cannot be retrieved later using `napi_unwrap()`, +* nor can it be removed later using `napi_remove_wrap()`, and +* the object created by the API can be used with `napi_wrap()`. + JavaScript `ArrayBuffer`s are described in [Section 24.1][] of the ECMAScript Language Specification. @@ -1884,6 +1898,14 @@ This API allocates a `node::Buffer` object and initializes it with data backed by the passed in buffer. While this is still a fully-supported data structure, in most cases using a `TypedArray` will suffice. +The API adds a `napi_finalize` callback which will be called when the JavaScript +object just created is ready for garbage collection. It is similar to +`napi_wrap()` except that: + +* the native data cannot be retrieved later using `napi_unwrap()`, +* nor can it be removed later using `napi_remove_wrap()`, and +* the object created by the API can be used with `napi_wrap()`. + For Node.js >=4 `Buffers` are `Uint8Array`s. #### napi_create_object @@ -4228,7 +4250,8 @@ in `js_object` is ready for garbage collection. This API is similar to * the native data cannot be retrieved later using `napi_unwrap()`, * nor can it be removed later using `napi_remove_wrap()`, and * the API can be called multiple times with different data items in order to - attach each of them to the JavaScript object. + attach each of them to the JavaScript object, and +* the object manipulated by the API can be used with `napi_wrap()`. *Caution*: The optional returned reference (if obtained) should be deleted via [`napi_delete_reference`][] ONLY in response to the finalize callback @@ -5164,6 +5187,7 @@ This API may only be called from the main thread. [`napi_get_last_error_info`]: #n_api_napi_get_last_error_info [`napi_get_property`]: #n_api_napi_get_property [`napi_get_reference_value`]: #n_api_napi_get_reference_value +[`napi_get_value_external`]: #n_api_napi_get_value_external [`napi_has_own_property`]: #n_api_napi_has_own_property [`napi_has_property`]: #n_api_napi_has_property [`napi_is_error`]: #n_api_napi_is_error -- cgit v1.2.3