napi_create_external_arraybuffer

新增于: v8.0.0 N-API 版本: 1 
napi_status
napi_create_external_arraybuffer(napi_env env,
                                 void* external_data,
                                 size_t byte_length,
                                 napi_finalize finalize_cb,
                                 void* finalize_hint,
                                 napi_value* result)
  • [in] env：调用该 API 时所处的环境。
  • [in] external_data：指向 ArrayBuffer 的底层字节缓冲区的指针。
  • [in] byte_length：底层缓冲区的字节长度。
  • [in] finalize_cb：可选回调，当 ArrayBuffer 被回收时调用。napi_finalize 提供了更多细节。
  • [in] finalize_hint：在收集期间传递给 finalize 回调的可选提示。
  • [out] result：一个 napi_value，表示 JavaScript 的 ArrayBuffer。

如果 API 成功，则返回 napi_ok。

【Returns napi_ok if the API succeeded.】

除 Node.js 外的一些运行时已停止支持外部缓冲区。
在除 Node.js 外的运行时中，该方法可能返回 napi_no_external_buffers_allowed，以表示不支持外部缓冲区。Electron 就是其中一种运行时，如本问题中所述 electron/issues/35801。

为了保持与所有运行时的最广泛兼容性，你可以在包含 node-api 头文件之前在你的插件中定义 NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED。这样做会隐藏创建外部缓冲区的两个函数。这将确保如果你不小心使用了其中一个方法，会发生编译错误。

【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.】

此 API 返回与 JavaScript ArrayBuffer 对应的 Node-API 值。ArrayBuffer 的底层字节缓冲区是外部分配和管理的。调用者必须确保字节缓冲区在终结回调被调用之前保持有效。

【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 finalize callback is called.】

该 API 添加了一个 napi_finalize 回调，当刚创建的 JavaScript 对象被垃圾回收时，该回调将被调用。

【The API adds a napi_finalize callback which will be called when the JavaScript object just created has been garbage collected.】

JavaScript 的 ArrayBuffer 在 ECMAScript 语言规范的 ArrayBuffer 对象部分 中有描述。

【JavaScript ArrayBuffers are described in Section ArrayBuffer objects of the ECMAScript Language Specification.】