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 对象准备进行垃圾回收时将调用它。它类似于 napi_wrap()，但有以下不同：

🌐 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:

  • 本地数据以后无法通过 napi_unwrap() 获取，
  • 也不能随后使用 napi_remove_wrap() 移除，并且
  • 由 API 创建的对象可以与 napi_wrap() 一起使用。

JavaScript 的 ArrayBuffer 在 ECMAScript 语言规范的 第24.1节 中有描述。

🌐 JavaScript ArrayBuffers are described in Section 24.1 of the ECMAScript Language Specification.