diff options
author | Michael Dawson <mdawson@devrus.com> | 2022-10-26 00:39:41 +0300 |
---|---|---|
committer | Michael Dawson <mdawson@devrus.com> | 2022-11-09 21:30:43 +0300 |
commit | 09ae62b9a869ff19d634b0fd1f5a17f198cd1ae7 (patch) | |
tree | 9a343b85f31ac7fe67f98483e453ced8eefbb679 /doc/api | |
parent | bf28da8617a9ba37b4aa274b38957ea39a613e48 (diff) |
node-api: handle no support for external buffers
Refs: https://github.com/electron/electron/issues/35801
Refs: https://github.com/nodejs/abi-stable-node/issues/441
Electron recently dropped support for external
buffers. Provide a way for addon authors to:
- hide the methods to create external buffers so they can
avoid using them if they want the broadest compatibility.
- call the methods that create external buffers at runtime
to check if external buffers are supported and either
use them or not based on the return code.
Signed-off-by: Michael Dawson <mdawson@devrus.com>
PR-URL: https://github.com/nodejs/node/pull/45181
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
Reviewed-By: Minwoo Jung <nodecorelab@gmail.com>
Diffstat (limited to 'doc/api')
-rw-r--r-- | doc/api/n-api.md | 27 |
1 files changed, 27 insertions, 0 deletions
diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 3a2b9bceb2a..b0b89de1c75 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -579,6 +579,7 @@ typedef enum { napi_arraybuffer_expected, napi_detachable_arraybuffer_expected, napi_would_deadlock, /* unused */ + napi_no_external_buffers_allowed } napi_status; ``` @@ -2403,6 +2404,19 @@ napi_create_external_arraybuffer(napi_env env, Returns `napi_ok` if the API succeeded. +**Some runtimes other than Node.js have dropped support for external buffers**. +On runtimes other than Node.js this method may return +`napi_no_external_buffers_allowed` to indicate that external +buffers are not supported. One such runtime is Electron as +described in this issue +[electron/issues/35801](https://github.com/electron/electron/issues/35801). + +In order to maintain broadest compatibility with all runtimes +you may define `NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED` in your addon before +includes for the node-api headers. Doing so will hide the 2 functions +that create external buffers. This will ensure a compilation error +occurs if you accidentally use one of these methods. + This API returns a Node-API value corresponding to a JavaScript `ArrayBuffer`. The underlying byte buffer of the `ArrayBuffer` is externally allocated and managed. The caller must ensure that the byte buffer remains valid until the @@ -2447,6 +2461,19 @@ napi_status napi_create_external_buffer(napi_env env, Returns `napi_ok` if the API succeeded. +**Some runtimes other than Node.js have dropped support for external buffers**. +On runtimes other than Node.js this method may return +`napi_no_external_buffers_allowed` to indicate that external +buffers are not supported. One such runtime is Electron as +described in this issue +[electron/issues/35801](https://github.com/electron/electron/issues/35801). + +In order to maintain broadest compatibility with all runtimes +you may define `NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED` in your addon before +includes for the node-api headers. Doing so will hide the 2 functions +that create external buffers. This will ensure a compilation error +occurs if you accidentally use one of these methods. + 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. |