ffi: add shared-buffer fast path for numeric and pointer signatures

Adds an ArrayBuffer-based invocation path for FFI functions whose
signatures are composed entirely of numeric types (i8..i64, u8..u64,
f32, f64, bool, char) and/or pointer types. The JS wrapper packs
arguments directly into a per-function AB via primordial DataView
setters and the C++ invoker (`InvokeFunctionSB`) reads them without
going through V8's `FunctionCallbackInfo`. Results are returned the same
way.

Pointer arguments use runtime dispatch: BigInt, null, and undefined take
the fast path, while Buffer, ArrayBuffer, ArrayBufferView, and String
fall back transparently to the classic `InvokeFunction` path via a
stashed `_invokeSlow` function. Signatures containing
non-numeric/non-pointer types also bypass the fast path.

The fast path is disabled on big-endian platforms.

Callers do not opt in, and the fast path is transparent in every way
users should rely on. One observable change: function wrappers returned
by `library.getFunction`, `library.getFunctions`, and `library.functions`
now have `.length` equal to the declared parameter count rather than
`0`. Code that relied on the previous value will need to be updated.

Adds microbenchmarks covering the common FFI call shapes so future
changes to the invoker can be evaluated:

- add-i32.js: 2-arg integer
- add-f64.js: 2-arg float
- many-args.js: 6-arg integer
- pointer-bigint.js: 1-arg pointer (BigInt)
- sum-buffer.js: pointer + length (Buffer)

A `common.js` helper resolves the fixture-library path from
`test/ffi/fixture_library` without pulling in the test harness, and
throws a clear message if the fixture hasn't been built yet.

Also adds `sum_6_i32` to the fixture library for the many-args case.

Signed-off-by: Bryan English <[email protected]>
PR-URL: #62918
Reviewed-By: Anna Henningsen <[email protected]>
Reviewed-By: Stephen Belanger <[email protected]>
Reviewed-By: Paolo Insogna <[email protected]>

Author: bengl

benchmark/ffi/add-f64.js

@@ -0,0 +1,28 @@
+'use strict';
+
+const common = require('../common.js');
+const ffi = require('node:ffi');
+const { libraryPath, ensureFixtureLibrary } = require('./common.js');
+
+const bench = common.createBenchmark(main, {
+  n: [1e7],
+}, {
+  flags: ['--experimental-ffi'],
+});
+
+ensureFixtureLibrary();
+
+const { lib, functions } = ffi.dlopen(libraryPath, {
+  add_f64: { result: 'f64', parameters: ['f64', 'f64'] },
+});
+
+const add = functions.add_f64;
+
+function main({ n }) {
+  bench.start();
+  for (let i = 0; i < n; ++i)
+    add(1.5, 2.5);
+  bench.end(n);
+
+  lib.close();
+}

benchmark/ffi/add-i32.js

@@ -0,0 +1,28 @@
+'use strict';
+
+const common = require('../common.js');
+const ffi = require('node:ffi');
+const { libraryPath, ensureFixtureLibrary } = require('./common.js');
+
+const bench = common.createBenchmark(main, {
+  n: [1e7],
+}, {
+  flags: ['--experimental-ffi'],
+});
+
+ensureFixtureLibrary();
+
+const { lib, functions } = ffi.dlopen(libraryPath, {
+  add_i32: { result: 'i32', parameters: ['i32', 'i32'] },
+});
+
+const add = functions.add_i32;
+
+function main({ n }) {
+  bench.start();
+  for (let i = 0; i < n; ++i)
+    add(20, 22);
+  bench.end(n);
+
+  lib.close();
+}

benchmark/ffi/common.js

@@ -0,0 +1,24 @@
+'use strict';
+
+const common = require('../common.js');
+const fs = require('node:fs');
+const path = require('node:path');
+
+// Cannot use test/ffi/ffi-test-common.js because it requires test/common
+// (the test harness module). Construct the path directly.
+const libraryPath = path.join(__dirname, '..', '..', 'test', 'ffi',
+                              'fixture_library', 'build', common.buildType,
+                              process.platform === 'win32' ? 'ffi_test_library.dll' :
+                                process.platform === 'darwin' ? 'ffi_test_library.dylib' :
+                                  'ffi_test_library.so');
+
+function ensureFixtureLibrary() {
+  if (!fs.existsSync(libraryPath)) {
+    throw new Error(
+      `Missing FFI fixture library: ${libraryPath}. ` +
+      'Build it with `tools/test.py test/ffi/test-ffi-calls.js` first.',
+    );
+  }
+}
+
+module.exports = { libraryPath, ensureFixtureLibrary };

benchmark/ffi/many-args.js

@@ -0,0 +1,28 @@
+'use strict';
+
+const common = require('../common.js');
+const ffi = require('node:ffi');
+const { libraryPath, ensureFixtureLibrary } = require('./common.js');
+
+const bench = common.createBenchmark(main, {
+  n: [1e7],
+}, {
+  flags: ['--experimental-ffi'],
+});
+
+ensureFixtureLibrary();
+
+const { lib, functions } = ffi.dlopen(libraryPath, {
+  sum_6_i32: { result: 'i32', parameters: ['i32', 'i32', 'i32', 'i32', 'i32', 'i32'] },
+});
+
+const fn = functions.sum_6_i32;
+
+function main({ n }) {
+  bench.start();
+  for (let i = 0; i < n; ++i)
+    fn(1, 2, 3, 4, 5, 6);
+  bench.end(n);
+
+  lib.close();
+}

benchmark/ffi/pointer-bigint.js

@@ -0,0 +1,28 @@
+'use strict';
+
+const common = require('../common.js');
+const ffi = require('node:ffi');
+const { libraryPath, ensureFixtureLibrary } = require('./common.js');
+
+const bench = common.createBenchmark(main, {
+  n: [1e7],
+}, {
+  flags: ['--experimental-ffi'],
+});
+
+ensureFixtureLibrary();
+
+const { lib, functions } = ffi.dlopen(libraryPath, {
+  pointer_to_usize: { result: 'u64', parameters: ['pointer'] },
+});
+
+const fn = functions.pointer_to_usize;
+
+function main({ n }) {
+  bench.start();
+  for (let i = 0; i < n; ++i)
+    fn(0xdeadbeefn);
+  bench.end(n);
+
+  lib.close();
+}

benchmark/ffi/sum-buffer.js

@@ -0,0 +1,33 @@
+'use strict';
+
+const common = require('../common.js');
+const ffi = require('node:ffi');
+const { libraryPath, ensureFixtureLibrary } = require('./common.js');
+
+const bench = common.createBenchmark(main, {
+  size: [64, 1024, 16384],
+  n: [1e6],
+}, {
+  flags: ['--experimental-ffi'],
+});
+
+ensureFixtureLibrary();
+
+const { lib, functions } = ffi.dlopen(libraryPath, {
+  sum_buffer: { result: 'u64', parameters: ['pointer', 'u64'] },
+});
+
+function main({ n, size }) {
+  const buf = Buffer.alloc(size, 0x42);
+  const ptr = ffi.getRawPointer(buf);
+  const len = BigInt(size);
+
+  const sum = functions.sum_buffer;
+
+  bench.start();
+  for (let i = 0; i < n; ++i)
+    sum(ptr, len);
+  bench.end(n);
+
+  lib.close();
+}

lib/ffi.js

@@ -53,6 +53,8 @@ const {
   toArrayBuffer,
 } = internalBinding('ffi');
 
+require('internal/ffi-shared-buffer');
+
 function checkFFIPermission() {
   if (!permission.isEnabled() || permission.has('ffi')) {
     return;