共享缓冲调用路径

🌐 Shared buffer call path

共享缓冲区调用路径用于 Fast API 调用路径不支持的签名。当函数创建时，Node.js 会为每个函数分配一个小缓冲区，为返回值提供一个 8 字节的插槽，并为每个参数提供一个 8 字节的插槽。在每次调用时，JavaScript 封装器会验证参数，把它们写入各自的插槽，通过 libffi 调用本地符号而不传递任何 JavaScript 参数，然后从缓冲区读取返回值。这样可以避免在 JavaScript 和 C++ 边界上单独转换每个参数。

🌐 The shared buffer call path is used for signatures that the Fast API call path does not support. When the function is created, Node.js allocates a small per-function buffer with one 8-byte slot for the return value and one 8-byte slot for each argument. On every call, the JavaScript wrapper validates the arguments, writes them into their slots, invokes the native symbol through libffi without passing any JavaScript arguments, and then reads the return value back from the buffer. This avoids converting each argument individually across the JavaScript and C++ boundary.

当满足以下所有条件时，函数会使用这个调用路径：

🌐 A function uses this call path when all of the following conditions are met:

  • 该签名的快速 API 调用路径不可用。
  • 主机是小端模式。
  • 这个函数签名至少有一个参数。没有参数的函数从共享缓冲区得不到任何好处，会使用另一种调用方式。

在这条路径上支持所有类型的名称，并且参数数量没有限制。

🌐 All type names are supported on this path, and there is no limit on the number of arguments.

类似指针的参数（pointer、string、buffer、arraybuffer 和 function）只有在值是 bigint、null 或 undefined 时才会写入共享缓冲区。当某次调用将字符串、Buffer、类型化数组、DataView 或 ArrayBuffer 传递给类似指针的参数时，该特定调用会交给 通用调用路径 来处理，它会在 C++ 中执行转换。函数本身会保留在共享缓冲区调用路径上，以便后续调用使用。

🌐 Pointer-like arguments (pointer, string, buffer, arraybuffer, and function) are written to the shared buffer only when the value is a bigint, null, or undefined. When a call passes a string, Buffer, typed array, DataView, or ArrayBuffer to a pointer-like parameter, that individual call is handed off to the generic call path, which performs the conversion in C++. The function itself stays on the shared buffer call path for later calls.

共享缓冲区对每个函数都是私有的。同一个函数的可重入调用，例如从 FFI 回调中调用，是安全的，因为本地端在调用符号之前会把参数从缓冲区中复制出来。

🌐 The shared buffer is private to each function. Reentrant calls to the same function, for example from an FFI callback, are safe because the native side copies the arguments out of the buffer before invoking the symbol.