ffi: reuse libffi call plans

benchmark/ffi/invoke-function.js

@@ -0,0 +1,79 @@
+'use strict';
+
+const assert = require('node:assert');
+const common = require('../common.js');
+const { libraryPath, ensureFixtureLibrary } = require('./common.js');
+
+// Measure the invocation (call) path for signatures that bypass V8 Fast API
+// and use libffi through FFIFunction::Invoke(). On x86-64 System V with
+// libffi >= 3.7, Invoke() reuses a precomputed call plan that avoids repeating
+// argument-placement work on every call. This benchmark quantifies the
+// per-call benefit.
+//
+// Signatures chosen to bypass both V8 Fast API and keep native work minimal:
+// - call_int_callback (null): 'function' type forces the generic path; null
+// pointer triggers the early return in C so native computation is negligible.
+// From libffi's perspective this is a register-only plan (2 pointer-sized
+// args both fit in GP registers on x86-64 System V).
+// - sum_8_i32: 8 GP args exceed the x86-64 Fast API register cap (6), forcing
+// the generic path. From libffi's perspective 6 args go in registers and 2
+// spill to the stack, exercising a stack-spilled plan.
+
+const bench = common.createBenchmark(main, {
+ n: [1e7],
+ symbol: ['call_int_callback', 'sum_8_i32'],
+}, {
+ flags: ['--experimental-ffi', '--no-warnings'],
+});
+
+ensureFixtureLibrary();
+
+function main({ n, symbol }) {
+ const ffi = require('node:ffi');
+
+ if (symbol === 'call_int_callback') {
+ // 'function' type bypasses Fast API (IsFastCallEligible rejects it).
+ // Pass 0n (null function pointer) so the native function returns -1
+ // immediately without invoking any callback, keeping per-call overhead
+ // dominated by the FFI call machinery itself.
+ const { lib, functions } = ffi.dlopen(libraryPath, {
+ call_int_callback: { return: 'i32', arguments: ['function', 'i32'] },
+ });
+
+ try {
+ // Verify the null-pointer early return.
+ assert.strictEqual(functions.call_int_callback(0n, 7), -1);
+
+ bench.start();
+ for (let i = 0; i < n; ++i)
+ functions.call_int_callback(0n, 21);
+ bench.end(n);
+ } finally {
+ lib.close();
+ }
+ } else {
+ // 8 integer args exceed the x86-64 SysV GP register cap (6), which makes
+ // CreateFastFFIMetadata reject the signature. Calls go through the
+ // SharedBuffer or generic invoker into FFIFunction::Invoke().
+ const { lib, functions } = ffi.dlopen(libraryPath, {
+ sum_8_i32: {
+ return: 'i32',
+ arguments: [
+ 'i32', 'i32', 'i32', 'i32',
+ 'i32', 'i32', 'i32', 'i32',
+ ],
+ },
+ });
+
+ const fn = functions.sum_8_i32;
+
+ assert.strictEqual(fn(1, 2, 3, 4, 5, 6, 7, 8), 36);
+
+ bench.start();
+ for (let i = 0; i < n; ++i)
+ fn(1, 2, 3, 4, 5, 6, 7, 14);
+ bench.end(n);
+
+ lib.close();
+ }
+}

src/ffi/fast.cc

@@ -192,13 +192,31 @@ bool SignatureNeedsFastBufferInvoke(const FFIFunction& fn) {
  IsBufferTypeName(fn.arg_type_names[0]));
 }
 
+namespace {
+
+std::shared_ptr<FFIFunction> CloneForFastMetadata(
+ const std::shared_ptr<FFIFunction>& fn) {
+ // Fast metadata only needs the native target and signature. In particular,
+ // its temporary clone must not borrow the original function's cif or plan.
+ auto clone = std::make_shared<FFIFunction>();
+ clone->closed = fn->closed;
+ clone->ptr = fn->ptr;
+ clone->args = fn->args;
+ clone->return_type = fn->return_type;
+ clone->arg_type_names = fn->arg_type_names;
+ clone->return_type_name = fn->return_type_name;
+ return clone;
+}
+
+} // namespace
+
 std::shared_ptr<FFIFunction> CloneWithRawPointerArgNames(
  const std::shared_ptr<FFIFunction>& fn) {
  // The primary Fast API entrypoint receives pointer-compatible values as
  // BigInts after the JS wrapper has converted strings, nullish values, and
  // memory-backed objects. A secondary entrypoint handles the monomorphic
  // memory-backed case without extracting the pointer in JS.
- auto clone = std::make_shared<FFIFunction>(*fn);
+ auto clone = CloneForFastMetadata(fn);
  for (std::string& name : clone->arg_type_names) {
  if (IsBufferTypeName(name)) {
  name = "pointer";
@@ -209,10 +227,10 @@ std::shared_ptr<FFIFunction> CloneWithRawPointerArgNames(
 
 std::shared_ptr<FFIFunction> CloneWithFastBufferArgNames(
  const std::shared_ptr<FFIFunction>& fn) {
- // Reuse the same native target and libffi metadata, but describe the JS
+ // Reuse the same native target and signature metadata, but describe the JS
  // argument as `buffer` so CreateFastFFIMetadata() emits a trampoline that
  // receives a V8 value and calls node_ffi_fast_buffer_data().
- auto clone = std::make_shared<FFIFunction>(*fn);
+ auto clone = CloneForFastMetadata(fn);
  for (std::string& name : clone->arg_type_names) {
  if (IsPointerTypeName(name)) {
  name = "buffer";

src/node_ffi.cc

@@ -42,6 +42,17 @@ using v8::Value;
 
 namespace ffi {
 
+void FFIFunction::Invoke(void* result, void** values) {
+#if defined(NODE_FFI_HAS_FAST_CALL_PLAN)
+ if (call_plan != nullptr) {
+ ffi_call_plan_invoke(call_plan.get(), FFI_FN(ptr), result, values);
+ return;
+ }
+#endif
+
+ ffi_call(&cif, FFI_FN(ptr), result, values);
+}
+
 void FFIFunctionInfo::MemoryInfo(MemoryTracker* tracker) const {
  tracker->TrackField("sb_backing", sb_backing);
 }
@@ -146,14 +157,12 @@ Maybe<DynamicLibrary::PreparedFunction> DynamicLibrary::PrepareFunction(
 
  should_cache_symbol = symbols_.find(name) == symbols_.end();
 
- fn = std::make_shared<FFIFunction>(
- FFIFunction{.closed = false,
- .ptr = ptr,
- .cif = {},
- .args = args,
- .return_type = return_type,
- .arg_type_names = std::move(arg_type_names),
- .return_type_name = std::move(return_type_name)});
+ fn = std::make_shared<FFIFunction>();
+ fn->ptr = ptr;
+ fn->args = std::move(args);
+ fn->return_type = return_type;
+ fn->arg_type_names = std::move(arg_type_names);
+ fn->return_type_name = std::move(return_type_name);
 
  ffi_status status = ffi_prep_cif(&fn->cif,
  FFI_DEFAULT_ABI,
@@ -178,6 +187,14 @@ Maybe<DynamicLibrary::PreparedFunction> DynamicLibrary::PrepareFunction(
  return {};
  }
 
+#if defined(NODE_FFI_HAS_FAST_CALL_PLAN)
+ // Allocation failure is non-fatal. Invoke() falls back to ffi_call().
+ ffi_call_plan* call_plan = ffi_call_plan_alloc(&fn->cif);
+ if (call_plan != nullptr) {
+ fn->call_plan.reset(call_plan);
+ }
+#endif
+
  should_cache_function = true;
  } else {
  fn = existing->second;
@@ -550,7 +567,7 @@ void DynamicLibrary::InvokeFunction(const FunctionCallbackInfo<Value>& args) {
  result = Malloc(GetFFIReturnValueStorageSize(fn->return_type));
  }
 
-ffi_call(&fn->cif, FFI_FN(fn->ptr), result, ffi_args.data());
+ fn->Invoke(result, ffi_args.data());
 
  // Return result back to Javascript
  ToJSReturnValue(env, args, fn->return_type, result);
@@ -609,7 +626,7 @@ void DynamicLibrary::InvokeFunctionSB(const FunctionCallbackInfo<Value>& args) {
  alignas(8) uint8_t result_storage[kSBResultStorageSize] = {0};
  void* result = (fn->return_type != &ffi_type_void) ? result_storage : nullptr;
 
-ffi_call(&fn->cif, FFI_FN(fn->ptr), result, ffi_args.data());
+ fn->Invoke(result, ffi_args.data());
 
  if (result != nullptr) {
  WriteFFIReturnToBuffer(fn->return_type, result, buffer, 0);

src/node_ffi.h

@@ -14,20 +14,41 @@
 #include <unordered_map>
 #include <vector>
 
+// libffi only accelerates reusable call plans on x86-64 System V. Other
+// targets implement the API by calling ffi_call(), which adds no benefit.
+#if defined(FFI_VERSION_NUMBER) && FFI_VERSION_NUMBER >= 30700 && \
+ defined(__x86_64__) && !defined(__ILP32__) && !defined(X86_WIN64) && \
+ !defined(_WIN32)
+#define NODE_FFI_HAS_FAST_CALL_PLAN 1
+#endif
+
 namespace node::ffi {
 
 class DynamicLibrary;
 struct FFIFunction;
 
 struct FFIFunction {
- bool closed;
+ FFIFunction() = default;
+ FFIFunction(const FFIFunction&) = delete;
+ FFIFunction& operator=(const FFIFunction&) = delete;
+ FFIFunction(FFIFunction&&) = delete;
+ FFIFunction& operator=(FFIFunction&&) = delete;
 
- void* ptr;
- ffi_cif cif;
+ bool closed = false;
+
+ void* ptr = nullptr;
+ ffi_cif cif = {};
  std::vector<ffi_type*> args;
- ffi_type* return_type;
+ ffi_type* return_type = nullptr;
  std::vector<std::string> arg_type_names;
  std::string return_type_name;
+#if defined(NODE_FFI_HAS_FAST_CALL_PLAN)
+ // The plan borrows cif, so it must remain uniquely owned by this instance.
+ std::unique_ptr<ffi_call_plan, decltype(&ffi_call_plan_free)> call_plan{
+ nullptr, ffi_call_plan_free};
+#endif
+
+ void Invoke(void* result, void** values);
 };
 
 class FFIFunctionInfo final : public BaseObject {

benchmark/ffi/invoke-function.js

@@ -0,0 +1,79 @@
+'use strict';
+
+const assert = require('node:assert');
+const common = require('../common.js');
+const { libraryPath, ensureFixtureLibrary } = require('./common.js');
+
+// Measure the invocation (call) path for signatures that bypass V8 Fast API
+// and use libffi through FFIFunction::Invoke(). On x86-64 System V with
+// libffi >= 3.7, Invoke() reuses a precomputed call plan that avoids repeating
+// argument-placement work on every call. This benchmark quantifies the
+// per-call benefit.
+//
+// Signatures chosen to bypass both V8 Fast API and keep native work minimal:
+// - call_int_callback (null): 'function' type forces the generic path; null
+// pointer triggers the early return in C so native computation is negligible.
+// From libffi's perspective this is a register-only plan (2 pointer-sized
+// args both fit in GP registers on x86-64 System V).
+// - sum_8_i32: 8 GP args exceed the x86-64 Fast API register cap (6), forcing
+// the generic path. From libffi's perspective 6 args go in registers and 2
+// spill to the stack, exercising a stack-spilled plan.
+
+const bench = common.createBenchmark(main, {
+ n: [1e7],
+ symbol: ['call_int_callback', 'sum_8_i32'],
+}, {
+ flags: ['--experimental-ffi', '--no-warnings'],
+});
+
+ensureFixtureLibrary();
+
+function main({ n, symbol }) {
+ const ffi = require('node:ffi');
+
+ if (symbol === 'call_int_callback') {
+ // 'function' type bypasses Fast API (IsFastCallEligible rejects it).
+ // Pass 0n (null function pointer) so the native function returns -1
+ // immediately without invoking any callback, keeping per-call overhead
+ // dominated by the FFI call machinery itself.
+ const { lib, functions } = ffi.dlopen(libraryPath, {
+ call_int_callback: { return: 'i32', arguments: ['function', 'i32'] },
+ });
+
+ try {
+ // Verify the null-pointer early return.
+ assert.strictEqual(functions.call_int_callback(0n, 7), -1);
+
+ bench.start();
+ for (let i = 0; i < n; ++i)
+ functions.call_int_callback(0n, 21);
+ bench.end(n);
+ } finally {
+ lib.close();
+ }
+ } else {
+ // 8 integer args exceed the x86-64 SysV GP register cap (6), which makes
+ // CreateFastFFIMetadata reject the signature. Calls go through the
+ // SharedBuffer or generic invoker into FFIFunction::Invoke().
+ const { lib, functions } = ffi.dlopen(libraryPath, {
+ sum_8_i32: {
+ return: 'i32',
+ arguments: [
+ 'i32', 'i32', 'i32', 'i32',
+ 'i32', 'i32', 'i32', 'i32',
+ ],
+ },
+ });
+
+ const fn = functions.sum_8_i32;
+
+ assert.strictEqual(fn(1, 2, 3, 4, 5, 6, 7, 8), 36);
+
+ bench.start();
+ for (let i = 0; i < n; ++i)
+ fn(1, 2, 3, 4, 5, 6, 7, 14);
+ bench.end(n);
+
+ lib.close();
+ }
+}

src/ffi/fast.cc

@@ -192,13 +192,31 @@ bool SignatureNeedsFastBufferInvoke(const FFIFunction& fn) {
  IsBufferTypeName(fn.arg_type_names[0]));
 }
 
+namespace {
+
+std::shared_ptr<FFIFunction> CloneForFastMetadata(
+ const std::shared_ptr<FFIFunction>& fn) {
+ // Fast metadata only needs the native target and signature. In particular,
+ // its temporary clone must not borrow the original function's cif or plan.
+ auto clone = std::make_shared<FFIFunction>();
+ clone->closed = fn->closed;
+ clone->ptr = fn->ptr;
+ clone->args = fn->args;
+ clone->return_type = fn->return_type;
+ clone->arg_type_names = fn->arg_type_names;
+ clone->return_type_name = fn->return_type_name;
+ return clone;
+}
+
+} // namespace
+
 std::shared_ptr<FFIFunction> CloneWithRawPointerArgNames(
  const std::shared_ptr<FFIFunction>& fn) {
  // The primary Fast API entrypoint receives pointer-compatible values as
  // BigInts after the JS wrapper has converted strings, nullish values, and
  // memory-backed objects. A secondary entrypoint handles the monomorphic
  // memory-backed case without extracting the pointer in JS.
- auto clone = std::make_shared<FFIFunction>(*fn);
+ auto clone = CloneForFastMetadata(fn);
  for (std::string& name : clone->arg_type_names) {
  if (IsBufferTypeName(name)) {
  name = "pointer";
@@ -209,10 +227,10 @@ std::shared_ptr<FFIFunction> CloneWithRawPointerArgNames(
 
 std::shared_ptr<FFIFunction> CloneWithFastBufferArgNames(
  const std::shared_ptr<FFIFunction>& fn) {
- // Reuse the same native target and libffi metadata, but describe the JS
+ // Reuse the same native target and signature metadata, but describe the JS
  // argument as `buffer` so CreateFastFFIMetadata() emits a trampoline that
  // receives a V8 value and calls node_ffi_fast_buffer_data().
- auto clone = std::make_shared<FFIFunction>(*fn);
+ auto clone = CloneForFastMetadata(fn);
  for (std::string& name : clone->arg_type_names) {
  if (IsPointerTypeName(name)) {
  name = "buffer";

src/node_ffi.cc

@@ -42,6 +42,17 @@ using v8::Value;
 
 namespace ffi {
 
+void FFIFunction::Invoke(void* result, void** values) {
+#if defined(NODE_FFI_HAS_FAST_CALL_PLAN)
+ if (call_plan != nullptr) {
+ ffi_call_plan_invoke(call_plan.get(), FFI_FN(ptr), result, values);
+ return;
+ }
+#endif
+
+ ffi_call(&cif, FFI_FN(ptr), result, values);
+}
+
 void FFIFunctionInfo::MemoryInfo(MemoryTracker* tracker) const {
  tracker->TrackField("sb_backing", sb_backing);
 }
@@ -146,14 +157,12 @@ Maybe<DynamicLibrary::PreparedFunction> DynamicLibrary::PrepareFunction(
 
  should_cache_symbol = symbols_.find(name) == symbols_.end();
 
- fn = std::make_shared<FFIFunction>(
- FFIFunction{.closed = false,
- .ptr = ptr,
- .cif = {},
- .args = args,
- .return_type = return_type,
- .arg_type_names = std::move(arg_type_names),
- .return_type_name = std::move(return_type_name)});
+ fn = std::make_shared<FFIFunction>();
+ fn->ptr = ptr;
+ fn->args = std::move(args);
+ fn->return_type = return_type;
+ fn->arg_type_names = std::move(arg_type_names);
+ fn->return_type_name = std::move(return_type_name);
 
  ffi_status status = ffi_prep_cif(&fn->cif,
  FFI_DEFAULT_ABI,
@@ -178,6 +187,14 @@ Maybe<DynamicLibrary::PreparedFunction> DynamicLibrary::PrepareFunction(
  return {};
  }
 
+#if defined(NODE_FFI_HAS_FAST_CALL_PLAN)
+ // Allocation failure is non-fatal. Invoke() falls back to ffi_call().
+ ffi_call_plan* call_plan = ffi_call_plan_alloc(&fn->cif);
+ if (call_plan != nullptr) {
+ fn->call_plan.reset(call_plan);
+ }
+#endif
+
  should_cache_function = true;
  } else {
  fn = existing->second;
@@ -550,7 +567,7 @@ void DynamicLibrary::InvokeFunction(const FunctionCallbackInfo<Value>& args) {
  result = Malloc(GetFFIReturnValueStorageSize(fn->return_type));
  }
 
-ffi_call(&fn->cif, FFI_FN(fn->ptr), result, ffi_args.data());
+ fn->Invoke(result, ffi_args.data());
 
  // Return result back to Javascript
  ToJSReturnValue(env, args, fn->return_type, result);
@@ -609,7 +626,7 @@ void DynamicLibrary::InvokeFunctionSB(const FunctionCallbackInfo<Value>& args) {
  alignas(8) uint8_t result_storage[kSBResultStorageSize] = {0};
  void* result = (fn->return_type != &ffi_type_void) ? result_storage : nullptr;
 
-ffi_call(&fn->cif, FFI_FN(fn->ptr), result, ffi_args.data());
+ fn->Invoke(result, ffi_args.data());
 
  if (result != nullptr) {
  WriteFFIReturnToBuffer(fn->return_type, result, buffer, 0);

src/node_ffi.h

@@ -14,20 +14,41 @@
 #include <unordered_map>
 #include <vector>
 
+// libffi only accelerates reusable call plans on x86-64 System V. Other
+// targets implement the API by calling ffi_call(), which adds no benefit.
+#if defined(FFI_VERSION_NUMBER) && FFI_VERSION_NUMBER >= 30700 && \
+ defined(__x86_64__) && !defined(__ILP32__) && !defined(X86_WIN64) && \
+ !defined(_WIN32)
+#define NODE_FFI_HAS_FAST_CALL_PLAN 1
+#endif
+
 namespace node::ffi {
 
 class DynamicLibrary;
 struct FFIFunction;
 
 struct FFIFunction {
- bool closed;
+ FFIFunction() = default;
+ FFIFunction(const FFIFunction&) = delete;
+ FFIFunction& operator=(const FFIFunction&) = delete;
+ FFIFunction(FFIFunction&&) = delete;
+ FFIFunction& operator=(FFIFunction&&) = delete;
 
- void* ptr;
- ffi_cif cif;
+ bool closed = false;
+
+ void* ptr = nullptr;
+ ffi_cif cif = {};
  std::vector<ffi_type*> args;
- ffi_type* return_type;
+ ffi_type* return_type = nullptr;
  std::vector<std::string> arg_type_names;
  std::string return_type_name;
+#if defined(NODE_FFI_HAS_FAST_CALL_PLAN)
+ // The plan borrows cif, so it must remain uniquely owned by this instance.
+ std::unique_ptr<ffi_call_plan, decltype(&ffi_call_plan_free)> call_plan{
+ nullptr, ffi_call_plan_free};
+#endif
+
+ void Invoke(void* result, void** values);
 };
 
 class FFIFunctionInfo final : public BaseObject {

benchmark/ffi/invoke-function.js

@@ -0,0 +1,79 @@
+'use strict';
+
+const assert = require('node:assert');
+const common = require('../common.js');
+const { libraryPath, ensureFixtureLibrary } = require('./common.js');
+
+// Measure the invocation (call) path for signatures that bypass V8 Fast API
+// and use libffi through FFIFunction::Invoke(). On x86-64 System V with
+// libffi >= 3.7, Invoke() reuses a precomputed call plan that avoids repeating
+// argument-placement work on every call. This benchmark quantifies the
+// per-call benefit.
+//
+// Signatures chosen to bypass both V8 Fast API and keep native work minimal:
+// - call_int_callback (null): 'function' type forces the generic path; null
+// pointer triggers the early return in C so native computation is negligible.
+// From libffi's perspective this is a register-only plan (2 pointer-sized
+// args both fit in GP registers on x86-64 System V).
+// - sum_8_i32: 8 GP args exceed the x86-64 Fast API register cap (6), forcing
+// the generic path. From libffi's perspective 6 args go in registers and 2
+// spill to the stack, exercising a stack-spilled plan.
+
+const bench = common.createBenchmark(main, {
+ n: [1e7],
+ symbol: ['call_int_callback', 'sum_8_i32'],
+}, {
+ flags: ['--experimental-ffi', '--no-warnings'],
+});
+
+ensureFixtureLibrary();
+
+function main({ n, symbol }) {
+ const ffi = require('node:ffi');
+
+ if (symbol === 'call_int_callback') {
+ // 'function' type bypasses Fast API (IsFastCallEligible rejects it).
+ // Pass 0n (null function pointer) so the native function returns -1
+ // immediately without invoking any callback, keeping per-call overhead
+ // dominated by the FFI call machinery itself.
+ const { lib, functions } = ffi.dlopen(libraryPath, {
+ call_int_callback: { return: 'i32', arguments: ['function', 'i32'] },
+ });
+
+ try {
+ // Verify the null-pointer early return.
+ assert.strictEqual(functions.call_int_callback(0n, 7), -1);
+
+ bench.start();
+ for (let i = 0; i < n; ++i)
+ functions.call_int_callback(0n, 21);
+ bench.end(n);
+ } finally {
+ lib.close();
+ }
+ } else {
+ // 8 integer args exceed the x86-64 SysV GP register cap (6), which makes
+ // CreateFastFFIMetadata reject the signature. Calls go through the
+ // SharedBuffer or generic invoker into FFIFunction::Invoke().
+ const { lib, functions } = ffi.dlopen(libraryPath, {
+ sum_8_i32: {
+ return: 'i32',
+ arguments: [
+ 'i32', 'i32', 'i32', 'i32',
+ 'i32', 'i32', 'i32', 'i32',
+ ],
+ },
+ });
+
+ const fn = functions.sum_8_i32;
+
+ assert.strictEqual(fn(1, 2, 3, 4, 5, 6, 7, 8), 36);
+
+ bench.start();
+ for (let i = 0; i < n; ++i)
+ fn(1, 2, 3, 4, 5, 6, 7, 14);
+ bench.end(n);
+
+ lib.close();
+ }
+}

src/ffi/fast.cc

@@ -192,13 +192,31 @@ bool SignatureNeedsFastBufferInvoke(const FFIFunction& fn) {
  IsBufferTypeName(fn.arg_type_names[0]));
 }
 
+namespace {
+
+std::shared_ptr<FFIFunction> CloneForFastMetadata(
+ const std::shared_ptr<FFIFunction>& fn) {
+ // Fast metadata only needs the native target and signature. In particular,
+ // its temporary clone must not borrow the original function's cif or plan.
+ auto clone = std::make_shared<FFIFunction>();
+ clone->closed = fn->closed;
+ clone->ptr = fn->ptr;
+ clone->args = fn->args;
+ clone->return_type = fn->return_type;
+ clone->arg_type_names = fn->arg_type_names;
+ clone->return_type_name = fn->return_type_name;
+ return clone;
+}
+
+} // namespace
+
 std::shared_ptr<FFIFunction> CloneWithRawPointerArgNames(
  const std::shared_ptr<FFIFunction>& fn) {
  // The primary Fast API entrypoint receives pointer-compatible values as
  // BigInts after the JS wrapper has converted strings, nullish values, and
  // memory-backed objects. A secondary entrypoint handles the monomorphic
  // memory-backed case without extracting the pointer in JS.
- auto clone = std::make_shared<FFIFunction>(*fn);
+ auto clone = CloneForFastMetadata(fn);
  for (std::string& name : clone->arg_type_names) {
  if (IsBufferTypeName(name)) {
  name = "pointer";
@@ -209,10 +227,10 @@ std::shared_ptr<FFIFunction> CloneWithRawPointerArgNames(
 
 std::shared_ptr<FFIFunction> CloneWithFastBufferArgNames(
  const std::shared_ptr<FFIFunction>& fn) {
- // Reuse the same native target and libffi metadata, but describe the JS
+ // Reuse the same native target and signature metadata, but describe the JS
  // argument as `buffer` so CreateFastFFIMetadata() emits a trampoline that
  // receives a V8 value and calls node_ffi_fast_buffer_data().
- auto clone = std::make_shared<FFIFunction>(*fn);
+ auto clone = CloneForFastMetadata(fn);
  for (std::string& name : clone->arg_type_names) {
  if (IsPointerTypeName(name)) {
  name = "buffer";

src/node_ffi.cc

@@ -42,6 +42,17 @@ using v8::Value;
 
 namespace ffi {
 
+void FFIFunction::Invoke(void* result, void** values) {
+#if defined(NODE_FFI_HAS_FAST_CALL_PLAN)
+ if (call_plan != nullptr) {
+ ffi_call_plan_invoke(call_plan.get(), FFI_FN(ptr), result, values);
+ return;
+ }
+#endif
+
+ ffi_call(&cif, FFI_FN(ptr), result, values);
+}
+
 void FFIFunctionInfo::MemoryInfo(MemoryTracker* tracker) const {
  tracker->TrackField("sb_backing", sb_backing);
 }
@@ -146,14 +157,12 @@ Maybe<DynamicLibrary::PreparedFunction> DynamicLibrary::PrepareFunction(
 
  should_cache_symbol = symbols_.find(name) == symbols_.end();
 
- fn = std::make_shared<FFIFunction>(
- FFIFunction{.closed = false,
- .ptr = ptr,
- .cif = {},
- .args = args,
- .return_type = return_type,
- .arg_type_names = std::move(arg_type_names),
- .return_type_name = std::move(return_type_name)});
+ fn = std::make_shared<FFIFunction>();
+ fn->ptr = ptr;
+ fn->args = std::move(args);
+ fn->return_type = return_type;
+ fn->arg_type_names = std::move(arg_type_names);
+ fn->return_type_name = std::move(return_type_name);
 
  ffi_status status = ffi_prep_cif(&fn->cif,
  FFI_DEFAULT_ABI,
@@ -178,6 +187,14 @@ Maybe<DynamicLibrary::PreparedFunction> DynamicLibrary::PrepareFunction(
  return {};
  }
 
+#if defined(NODE_FFI_HAS_FAST_CALL_PLAN)
+ // Allocation failure is non-fatal. Invoke() falls back to ffi_call().
+ ffi_call_plan* call_plan = ffi_call_plan_alloc(&fn->cif);
+ if (call_plan != nullptr) {
+ fn->call_plan.reset(call_plan);
+ }
+#endif
+
  should_cache_function = true;
  } else {
  fn = existing->second;
@@ -550,7 +567,7 @@ void DynamicLibrary::InvokeFunction(const FunctionCallbackInfo<Value>& args) {
  result = Malloc(GetFFIReturnValueStorageSize(fn->return_type));
  }
 
-ffi_call(&fn->cif, FFI_FN(fn->ptr), result, ffi_args.data());
+ fn->Invoke(result, ffi_args.data());
 
  // Return result back to Javascript
  ToJSReturnValue(env, args, fn->return_type, result);
@@ -609,7 +626,7 @@ void DynamicLibrary::InvokeFunctionSB(const FunctionCallbackInfo<Value>& args) {
  alignas(8) uint8_t result_storage[kSBResultStorageSize] = {0};
  void* result = (fn->return_type != &ffi_type_void) ? result_storage : nullptr;
 
-ffi_call(&fn->cif, FFI_FN(fn->ptr), result, ffi_args.data());
+ fn->Invoke(result, ffi_args.data());
 
  if (result != nullptr) {
  WriteFFIReturnToBuffer(fn->return_type, result, buffer, 0);

src/node_ffi.h

@@ -14,20 +14,41 @@
 #include <unordered_map>
 #include <vector>
 
+// libffi only accelerates reusable call plans on x86-64 System V. Other
+// targets implement the API by calling ffi_call(), which adds no benefit.
+#if defined(FFI_VERSION_NUMBER) && FFI_VERSION_NUMBER >= 30700 && \
+ defined(__x86_64__) && !defined(__ILP32__) && !defined(X86_WIN64) && \
+ !defined(_WIN32)
+#define NODE_FFI_HAS_FAST_CALL_PLAN 1
+#endif
+
 namespace node::ffi {
 
 class DynamicLibrary;
 struct FFIFunction;
 
 struct FFIFunction {
- bool closed;
+ FFIFunction() = default;
+ FFIFunction(const FFIFunction&) = delete;
+ FFIFunction& operator=(const FFIFunction&) = delete;
+ FFIFunction(FFIFunction&&) = delete;
+ FFIFunction& operator=(FFIFunction&&) = delete;
 
- void* ptr;
- ffi_cif cif;
+ bool closed = false;
+
+ void* ptr = nullptr;
+ ffi_cif cif = {};
  std::vector<ffi_type*> args;
- ffi_type* return_type;
+ ffi_type* return_type = nullptr;
  std::vector<std::string> arg_type_names;
  std::string return_type_name;
+#if defined(NODE_FFI_HAS_FAST_CALL_PLAN)
+ // The plan borrows cif, so it must remain uniquely owned by this instance.
+ std::unique_ptr<ffi_call_plan, decltype(&ffi_call_plan_free)> call_plan{
+ nullptr, ffi_call_plan_free};
+#endif
+
+ void Invoke(void* result, void** values);
 };
 
 class FFIFunctionInfo final : public BaseObject {

benchmark/ffi/invoke-function.js

@@ -0,0 +1,79 @@
+'use strict';
+
+const assert = require('node:assert');
+const common = require('../common.js');
+const { libraryPath, ensureFixtureLibrary } = require('./common.js');
+
+// Measure the invocation (call) path for signatures that bypass V8 Fast API
+// and use libffi through FFIFunction::Invoke(). On x86-64 System V with
+// libffi >= 3.7, Invoke() reuses a precomputed call plan that avoids repeating
+// argument-placement work on every call. This benchmark quantifies the
+// per-call benefit.
+//
+// Signatures chosen to bypass both V8 Fast API and keep native work minimal:
+// - call_int_callback (null): 'function' type forces the generic path; null
+// pointer triggers the early return in C so native computation is negligible.
+// From libffi's perspective this is a register-only plan (2 pointer-sized
+// args both fit in GP registers on x86-64 System V).
+// - sum_8_i32: 8 GP args exceed the x86-64 Fast API register cap (6), forcing
+// the generic path. From libffi's perspective 6 args go in registers and 2
+// spill to the stack, exercising a stack-spilled plan.
+
+const bench = common.createBenchmark(main, {
+ n: [1e7],
+ symbol: ['call_int_callback', 'sum_8_i32'],
+}, {
+ flags: ['--experimental-ffi', '--no-warnings'],
+});
+
+ensureFixtureLibrary();
+
+function main({ n, symbol }) {
+ const ffi = require('node:ffi');
+
+ if (symbol === 'call_int_callback') {
+ // 'function' type bypasses Fast API (IsFastCallEligible rejects it).
+ // Pass 0n (null function pointer) so the native function returns -1
+ // immediately without invoking any callback, keeping per-call overhead
+ // dominated by the FFI call machinery itself.
+ const { lib, functions } = ffi.dlopen(libraryPath, {
+ call_int_callback: { return: 'i32', arguments: ['function', 'i32'] },
+ });
+
+ try {
+ // Verify the null-pointer early return.
+ assert.strictEqual(functions.call_int_callback(0n, 7), -1);
+
+ bench.start();
+ for (let i = 0; i < n; ++i)
+ functions.call_int_callback(0n, 21);
+ bench.end(n);
+ } finally {
+ lib.close();
+ }
+ } else {
+ // 8 integer args exceed the x86-64 SysV GP register cap (6), which makes
+ // CreateFastFFIMetadata reject the signature. Calls go through the
+ // SharedBuffer or generic invoker into FFIFunction::Invoke().
+ const { lib, functions } = ffi.dlopen(libraryPath, {
+ sum_8_i32: {
+ return: 'i32',
+ arguments: [
+ 'i32', 'i32', 'i32', 'i32',
+ 'i32', 'i32', 'i32', 'i32',
+ ],
+ },
+ });
+
+ const fn = functions.sum_8_i32;
+
+ assert.strictEqual(fn(1, 2, 3, 4, 5, 6, 7, 8), 36);
+
+ bench.start();
+ for (let i = 0; i < n; ++i)
+ fn(1, 2, 3, 4, 5, 6, 7, 14);
+ bench.end(n);
+
+ lib.close();
+ }
+}

src/ffi/fast.cc

@@ -192,13 +192,31 @@ bool SignatureNeedsFastBufferInvoke(const FFIFunction& fn) {
  IsBufferTypeName(fn.arg_type_names[0]));
 }
 
+namespace {
+
+std::shared_ptr<FFIFunction> CloneForFastMetadata(
+ const std::shared_ptr<FFIFunction>& fn) {
+ // Fast metadata only needs the native target and signature. In particular,
+ // its temporary clone must not borrow the original function's cif or plan.
+ auto clone = std::make_shared<FFIFunction>();
+ clone->closed = fn->closed;
+ clone->ptr = fn->ptr;
+ clone->args = fn->args;
+ clone->return_type = fn->return_type;
+ clone->arg_type_names = fn->arg_type_names;
+ clone->return_type_name = fn->return_type_name;
+ return clone;
+}
+
+} // namespace
+
 std::shared_ptr<FFIFunction> CloneWithRawPointerArgNames(
  const std::shared_ptr<FFIFunction>& fn) {
  // The primary Fast API entrypoint receives pointer-compatible values as
  // BigInts after the JS wrapper has converted strings, nullish values, and
  // memory-backed objects. A secondary entrypoint handles the monomorphic
  // memory-backed case without extracting the pointer in JS.
- auto clone = std::make_shared<FFIFunction>(*fn);
+ auto clone = CloneForFastMetadata(fn);
  for (std::string& name : clone->arg_type_names) {
  if (IsBufferTypeName(name)) {
  name = "pointer";
@@ -209,10 +227,10 @@ std::shared_ptr<FFIFunction> CloneWithRawPointerArgNames(
 
 std::shared_ptr<FFIFunction> CloneWithFastBufferArgNames(
  const std::shared_ptr<FFIFunction>& fn) {
- // Reuse the same native target and libffi metadata, but describe the JS
+ // Reuse the same native target and signature metadata, but describe the JS
  // argument as `buffer` so CreateFastFFIMetadata() emits a trampoline that
  // receives a V8 value and calls node_ffi_fast_buffer_data().
- auto clone = std::make_shared<FFIFunction>(*fn);
+ auto clone = CloneForFastMetadata(fn);
  for (std::string& name : clone->arg_type_names) {
  if (IsPointerTypeName(name)) {
  name = "buffer";

src/node_ffi.cc

@@ -42,6 +42,17 @@ using v8::Value;
 
 namespace ffi {
 
+void FFIFunction::Invoke(void* result, void** values) {
+#if defined(NODE_FFI_HAS_FAST_CALL_PLAN)
+ if (call_plan != nullptr) {
+ ffi_call_plan_invoke(call_plan.get(), FFI_FN(ptr), result, values);
+ return;
+ }
+#endif
+
+ ffi_call(&cif, FFI_FN(ptr), result, values);
+}
+
 void FFIFunctionInfo::MemoryInfo(MemoryTracker* tracker) const {
  tracker->TrackField("sb_backing", sb_backing);
 }
@@ -146,14 +157,12 @@ Maybe<DynamicLibrary::PreparedFunction> DynamicLibrary::PrepareFunction(
 
  should_cache_symbol = symbols_.find(name) == symbols_.end();
 
- fn = std::make_shared<FFIFunction>(
- FFIFunction{.closed = false,
- .ptr = ptr,
- .cif = {},
- .args = args,
- .return_type = return_type,
- .arg_type_names = std::move(arg_type_names),
- .return_type_name = std::move(return_type_name)});
+ fn = std::make_shared<FFIFunction>();
+ fn->ptr = ptr;
+ fn->args = std::move(args);
+ fn->return_type = return_type;
+ fn->arg_type_names = std::move(arg_type_names);
+ fn->return_type_name = std::move(return_type_name);
 
  ffi_status status = ffi_prep_cif(&fn->cif,
  FFI_DEFAULT_ABI,
@@ -178,6 +187,14 @@ Maybe<DynamicLibrary::PreparedFunction> DynamicLibrary::PrepareFunction(
  return {};
  }
 
+#if defined(NODE_FFI_HAS_FAST_CALL_PLAN)
+ // Allocation failure is non-fatal. Invoke() falls back to ffi_call().
+ ffi_call_plan* call_plan = ffi_call_plan_alloc(&fn->cif);
+ if (call_plan != nullptr) {
+ fn->call_plan.reset(call_plan);
+ }
+#endif
+
  should_cache_function = true;
  } else {
  fn = existing->second;
@@ -550,7 +567,7 @@ void DynamicLibrary::InvokeFunction(const FunctionCallbackInfo<Value>& args) {
  result = Malloc(GetFFIReturnValueStorageSize(fn->return_type));
  }
 
-ffi_call(&fn->cif, FFI_FN(fn->ptr), result, ffi_args.data());
+ fn->Invoke(result, ffi_args.data());
 
  // Return result back to Javascript
  ToJSReturnValue(env, args, fn->return_type, result);
@@ -609,7 +626,7 @@ void DynamicLibrary::InvokeFunctionSB(const FunctionCallbackInfo<Value>& args) {
  alignas(8) uint8_t result_storage[kSBResultStorageSize] = {0};
  void* result = (fn->return_type != &ffi_type_void) ? result_storage : nullptr;
 
-ffi_call(&fn->cif, FFI_FN(fn->ptr), result, ffi_args.data());
+ fn->Invoke(result, ffi_args.data());
 
  if (result != nullptr) {
  WriteFFIReturnToBuffer(fn->return_type, result, buffer, 0);

src/node_ffi.h

@@ -14,20 +14,41 @@
 #include <unordered_map>
 #include <vector>
 
+// libffi only accelerates reusable call plans on x86-64 System V. Other
+// targets implement the API by calling ffi_call(), which adds no benefit.
+#if defined(FFI_VERSION_NUMBER) && FFI_VERSION_NUMBER >= 30700 && \
+ defined(__x86_64__) && !defined(__ILP32__) && !defined(X86_WIN64) && \
+ !defined(_WIN32)
+#define NODE_FFI_HAS_FAST_CALL_PLAN 1
+#endif
+
 namespace node::ffi {
 
 class DynamicLibrary;
 struct FFIFunction;
 
 struct FFIFunction {
- bool closed;
+ FFIFunction() = default;
+ FFIFunction(const FFIFunction&) = delete;
+ FFIFunction& operator=(const FFIFunction&) = delete;
+ FFIFunction(FFIFunction&&) = delete;
+ FFIFunction& operator=(FFIFunction&&) = delete;
 
- void* ptr;
- ffi_cif cif;
+ bool closed = false;
+
+ void* ptr = nullptr;
+ ffi_cif cif = {};
  std::vector<ffi_type*> args;
- ffi_type* return_type;
+ ffi_type* return_type = nullptr;
  std::vector<std::string> arg_type_names;
  std::string return_type_name;
+#if defined(NODE_FFI_HAS_FAST_CALL_PLAN)
+ // The plan borrows cif, so it must remain uniquely owned by this instance.
+ std::unique_ptr<ffi_call_plan, decltype(&ffi_call_plan_free)> call_plan{
+ nullptr, ffi_call_plan_free};
+#endif
+
+ void Invoke(void* result, void** values);
 };
 
 class FFIFunctionInfo final : public BaseObject {

benchmark/ffi/invoke-function.js

@@ -0,0 +1,79 @@
+'use strict';
+
+const assert = require('node:assert');
+const common = require('../common.js');
+const { libraryPath, ensureFixtureLibrary } = require('./common.js');
+
+// Measure the invocation (call) path for signatures that bypass V8 Fast API
+// and use libffi through FFIFunction::Invoke(). On x86-64 System V with
+// libffi >= 3.7, Invoke() reuses a precomputed call plan that avoids repeating
+// argument-placement work on every call. This benchmark quantifies the
+// per-call benefit.
+//
+// Signatures chosen to bypass both V8 Fast API and keep native work minimal:
+// - call_int_callback (null): 'function' type forces the generic path; null
+// pointer triggers the early return in C so native computation is negligible.
+// From libffi's perspective this is a register-only plan (2 pointer-sized
+// args both fit in GP registers on x86-64 System V).
+// - sum_8_i32: 8 GP args exceed the x86-64 Fast API register cap (6), forcing
+// the generic path. From libffi's perspective 6 args go in registers and 2
+// spill to the stack, exercising a stack-spilled plan.
+
+const bench = common.createBenchmark(main, {
+ n: [1e7],
+ symbol: ['call_int_callback', 'sum_8_i32'],
+}, {
+ flags: ['--experimental-ffi', '--no-warnings'],
+});
+
+ensureFixtureLibrary();
+
+function main({ n, symbol }) {
+ const ffi = require('node:ffi');
+
+ if (symbol === 'call_int_callback') {
+ // 'function' type bypasses Fast API (IsFastCallEligible rejects it).
+ // Pass 0n (null function pointer) so the native function returns -1
+ // immediately without invoking any callback, keeping per-call overhead
+ // dominated by the FFI call machinery itself.
+ const { lib, functions } = ffi.dlopen(libraryPath, {
+ call_int_callback: { return: 'i32', arguments: ['function', 'i32'] },
+ });
+
+ try {
+ // Verify the null-pointer early return.
+ assert.strictEqual(functions.call_int_callback(0n, 7), -1);
+
+ bench.start();
+ for (let i = 0; i < n; ++i)
+ functions.call_int_callback(0n, 21);
+ bench.end(n);
+ } finally {
+ lib.close();
+ }
+ } else {
+ // 8 integer args exceed the x86-64 SysV GP register cap (6), which makes
+ // CreateFastFFIMetadata reject the signature. Calls go through the
+ // SharedBuffer or generic invoker into FFIFunction::Invoke().
+ const { lib, functions } = ffi.dlopen(libraryPath, {
+ sum_8_i32: {
+ return: 'i32',
+ arguments: [
+ 'i32', 'i32', 'i32', 'i32',
+ 'i32', 'i32', 'i32', 'i32',
+ ],
+ },
+ });
+
+ const fn = functions.sum_8_i32;
+
+ assert.strictEqual(fn(1, 2, 3, 4, 5, 6, 7, 8), 36);
+
+ bench.start();
+ for (let i = 0; i < n; ++i)
+ fn(1, 2, 3, 4, 5, 6, 7, 14);
+ bench.end(n);
+
+ lib.close();
+ }
+}

src/ffi/fast.cc

@@ -192,13 +192,31 @@ bool SignatureNeedsFastBufferInvoke(const FFIFunction& fn) {
  IsBufferTypeName(fn.arg_type_names[0]));
 }
 
+namespace {
+
+std::shared_ptr<FFIFunction> CloneForFastMetadata(
+ const std::shared_ptr<FFIFunction>& fn) {
+ // Fast metadata only needs the native target and signature. In particular,
+ // its temporary clone must not borrow the original function's cif or plan.
+ auto clone = std::make_shared<FFIFunction>();
+ clone->closed = fn->closed;
+ clone->ptr = fn->ptr;
+ clone->args = fn->args;
+ clone->return_type = fn->return_type;
+ clone->arg_type_names = fn->arg_type_names;
+ clone->return_type_name = fn->return_type_name;
+ return clone;
+}
+
+} // namespace
+
 std::shared_ptr<FFIFunction> CloneWithRawPointerArgNames(
  const std::shared_ptr<FFIFunction>& fn) {
  // The primary Fast API entrypoint receives pointer-compatible values as
  // BigInts after the JS wrapper has converted strings, nullish values, and
  // memory-backed objects. A secondary entrypoint handles the monomorphic
  // memory-backed case without extracting the pointer in JS.
- auto clone = std::make_shared<FFIFunction>(*fn);
+ auto clone = CloneForFastMetadata(fn);
  for (std::string& name : clone->arg_type_names) {
  if (IsBufferTypeName(name)) {
  name = "pointer";
@@ -209,10 +227,10 @@ std::shared_ptr<FFIFunction> CloneWithRawPointerArgNames(
 
 std::shared_ptr<FFIFunction> CloneWithFastBufferArgNames(
  const std::shared_ptr<FFIFunction>& fn) {
- // Reuse the same native target and libffi metadata, but describe the JS
+ // Reuse the same native target and signature metadata, but describe the JS
  // argument as `buffer` so CreateFastFFIMetadata() emits a trampoline that
  // receives a V8 value and calls node_ffi_fast_buffer_data().
- auto clone = std::make_shared<FFIFunction>(*fn);
+ auto clone = CloneForFastMetadata(fn);
  for (std::string& name : clone->arg_type_names) {
  if (IsPointerTypeName(name)) {
  name = "buffer";

src/node_ffi.cc

@@ -42,6 +42,17 @@ using v8::Value;
 
 namespace ffi {
 
+void FFIFunction::Invoke(void* result, void** values) {
+#if defined(NODE_FFI_HAS_FAST_CALL_PLAN)
+ if (call_plan != nullptr) {
+ ffi_call_plan_invoke(call_plan.get(), FFI_FN(ptr), result, values);
+ return;
+ }
+#endif
+
+ ffi_call(&cif, FFI_FN(ptr), result, values);
+}
+
 void FFIFunctionInfo::MemoryInfo(MemoryTracker* tracker) const {
  tracker->TrackField("sb_backing", sb_backing);
 }
@@ -146,14 +157,12 @@ Maybe<DynamicLibrary::PreparedFunction> DynamicLibrary::PrepareFunction(
 
  should_cache_symbol = symbols_.find(name) == symbols_.end();
 
- fn = std::make_shared<FFIFunction>(
- FFIFunction{.closed = false,
- .ptr = ptr,
- .cif = {},
- .args = args,
- .return_type = return_type,
- .arg_type_names = std::move(arg_type_names),
- .return_type_name = std::move(return_type_name)});
+ fn = std::make_shared<FFIFunction>();
+ fn->ptr = ptr;
+ fn->args = std::move(args);
+ fn->return_type = return_type;
+ fn->arg_type_names = std::move(arg_type_names);
+ fn->return_type_name = std::move(return_type_name);
 
  ffi_status status = ffi_prep_cif(&fn->cif,
  FFI_DEFAULT_ABI,
@@ -178,6 +187,14 @@ Maybe<DynamicLibrary::PreparedFunction> DynamicLibrary::PrepareFunction(
  return {};
  }
 
+#if defined(NODE_FFI_HAS_FAST_CALL_PLAN)
+ // Allocation failure is non-fatal. Invoke() falls back to ffi_call().
+ ffi_call_plan* call_plan = ffi_call_plan_alloc(&fn->cif);
+ if (call_plan != nullptr) {
+ fn->call_plan.reset(call_plan);
+ }
+#endif
+
  should_cache_function = true;
  } else {
  fn = existing->second;
@@ -550,7 +567,7 @@ void DynamicLibrary::InvokeFunction(const FunctionCallbackInfo<Value>& args) {
  result = Malloc(GetFFIReturnValueStorageSize(fn->return_type));
  }
 
-ffi_call(&fn->cif, FFI_FN(fn->ptr), result, ffi_args.data());
+ fn->Invoke(result, ffi_args.data());
 
  // Return result back to Javascript
  ToJSReturnValue(env, args, fn->return_type, result);
@@ -609,7 +626,7 @@ void DynamicLibrary::InvokeFunctionSB(const FunctionCallbackInfo<Value>& args) {
  alignas(8) uint8_t result_storage[kSBResultStorageSize] = {0};
  void* result = (fn->return_type != &ffi_type_void) ? result_storage : nullptr;
 
-ffi_call(&fn->cif, FFI_FN(fn->ptr), result, ffi_args.data());
+ fn->Invoke(result, ffi_args.data());
 
  if (result != nullptr) {
  WriteFFIReturnToBuffer(fn->return_type, result, buffer, 0);

src/node_ffi.h

@@ -14,20 +14,41 @@
 #include <unordered_map>
 #include <vector>
 
+// libffi only accelerates reusable call plans on x86-64 System V. Other
+// targets implement the API by calling ffi_call(), which adds no benefit.
+#if defined(FFI_VERSION_NUMBER) && FFI_VERSION_NUMBER >= 30700 && \
+ defined(__x86_64__) && !defined(__ILP32__) && !defined(X86_WIN64) && \
+ !defined(_WIN32)
+#define NODE_FFI_HAS_FAST_CALL_PLAN 1
+#endif
+
 namespace node::ffi {
 
 class DynamicLibrary;
 struct FFIFunction;
 
 struct FFIFunction {
- bool closed;
+ FFIFunction() = default;
+ FFIFunction(const FFIFunction&) = delete;
+ FFIFunction& operator=(const FFIFunction&) = delete;
+ FFIFunction(FFIFunction&&) = delete;
+ FFIFunction& operator=(FFIFunction&&) = delete;
 
- void* ptr;
- ffi_cif cif;
+ bool closed = false;
+
+ void* ptr = nullptr;
+ ffi_cif cif = {};
  std::vector<ffi_type*> args;
- ffi_type* return_type;
+ ffi_type* return_type = nullptr;
  std::vector<std::string> arg_type_names;
  std::string return_type_name;
+#if defined(NODE_FFI_HAS_FAST_CALL_PLAN)
+ // The plan borrows cif, so it must remain uniquely owned by this instance.
+ std::unique_ptr<ffi_call_plan, decltype(&ffi_call_plan_free)> call_plan{
+ nullptr, ffi_call_plan_free};
+#endif
+
+ void Invoke(void* result, void** values);
 };
 
 class FFIFunctionInfo final : public BaseObject {

benchmark/ffi/invoke-function.js

@@ -0,0 +1,79 @@
+'use strict';
+
+const assert = require('node:assert');
+const common = require('../common.js');
+const { libraryPath, ensureFixtureLibrary } = require('./common.js');
+
+// Measure the invocation (call) path for signatures that bypass V8 Fast API
+// and use libffi through FFIFunction::Invoke(). On x86-64 System V with
+// libffi >= 3.7, Invoke() reuses a precomputed call plan that avoids repeating
+// argument-placement work on every call. This benchmark quantifies the
+// per-call benefit.
+//
+// Signatures chosen to bypass both V8 Fast API and keep native work minimal:
+// - call_int_callback (null): 'function' type forces the generic path; null
+// pointer triggers the early return in C so native computation is negligible.
+// From libffi's perspective this is a register-only plan (2 pointer-sized
+// args both fit in GP registers on x86-64 System V).
+// - sum_8_i32: 8 GP args exceed the x86-64 Fast API register cap (6), forcing
+// the generic path. From libffi's perspective 6 args go in registers and 2
+// spill to the stack, exercising a stack-spilled plan.
+
+const bench = common.createBenchmark(main, {
+ n: [1e7],
+ symbol: ['call_int_callback', 'sum_8_i32'],
+}, {
+ flags: ['--experimental-ffi', '--no-warnings'],
+});
+
+ensureFixtureLibrary();
+
+function main({ n, symbol }) {
+ const ffi = require('node:ffi');
+
+ if (symbol === 'call_int_callback') {
+ // 'function' type bypasses Fast API (IsFastCallEligible rejects it).
+ // Pass 0n (null function pointer) so the native function returns -1
+ // immediately without invoking any callback, keeping per-call overhead
+ // dominated by the FFI call machinery itself.
+ const { lib, functions } = ffi.dlopen(libraryPath, {
+ call_int_callback: { return: 'i32', arguments: ['function', 'i32'] },
+ });
+
+ try {
+ // Verify the null-pointer early return.
+ assert.strictEqual(functions.call_int_callback(0n, 7), -1);
+
+ bench.start();
+ for (let i = 0; i < n; ++i)
+ functions.call_int_callback(0n, 21);
+ bench.end(n);
+ } finally {
+ lib.close();
+ }
+ } else {
+ // 8 integer args exceed the x86-64 SysV GP register cap (6), which makes
+ // CreateFastFFIMetadata reject the signature. Calls go through the
+ // SharedBuffer or generic invoker into FFIFunction::Invoke().
+ const { lib, functions } = ffi.dlopen(libraryPath, {
+ sum_8_i32: {
+ return: 'i32',
+ arguments: [
+ 'i32', 'i32', 'i32', 'i32',
+ 'i32', 'i32', 'i32', 'i32',
+ ],
+ },
+ });
+
+ const fn = functions.sum_8_i32;
+
+ assert.strictEqual(fn(1, 2, 3, 4, 5, 6, 7, 8), 36);
+
+ bench.start();
+ for (let i = 0; i < n; ++i)
+ fn(1, 2, 3, 4, 5, 6, 7, 14);
+ bench.end(n);
+
+ lib.close();
+ }
+}

src/ffi/fast.cc

@@ -192,13 +192,31 @@ bool SignatureNeedsFastBufferInvoke(const FFIFunction& fn) {
  IsBufferTypeName(fn.arg_type_names[0]));
 }
 
+namespace {
+
+std::shared_ptr<FFIFunction> CloneForFastMetadata(
+ const std::shared_ptr<FFIFunction>& fn) {
+ // Fast metadata only needs the native target and signature. In particular,
+ // its temporary clone must not borrow the original function's cif or plan.
+ auto clone = std::make_shared<FFIFunction>();
+ clone->closed = fn->closed;
+ clone->ptr = fn->ptr;
+ clone->args = fn->args;
+ clone->return_type = fn->return_type;
+ clone->arg_type_names = fn->arg_type_names;
+ clone->return_type_name = fn->return_type_name;
+ return clone;
+}
+
+} // namespace
+
 std::shared_ptr<FFIFunction> CloneWithRawPointerArgNames(
  const std::shared_ptr<FFIFunction>& fn) {
  // The primary Fast API entrypoint receives pointer-compatible values as
  // BigInts after the JS wrapper has converted strings, nullish values, and
  // memory-backed objects. A secondary entrypoint handles the monomorphic
  // memory-backed case without extracting the pointer in JS.
- auto clone = std::make_shared<FFIFunction>(*fn);
+ auto clone = CloneForFastMetadata(fn);
  for (std::string& name : clone->arg_type_names) {
  if (IsBufferTypeName(name)) {
  name = "pointer";
@@ -209,10 +227,10 @@ std::shared_ptr<FFIFunction> CloneWithRawPointerArgNames(
 
 std::shared_ptr<FFIFunction> CloneWithFastBufferArgNames(
  const std::shared_ptr<FFIFunction>& fn) {
- // Reuse the same native target and libffi metadata, but describe the JS
+ // Reuse the same native target and signature metadata, but describe the JS
  // argument as `buffer` so CreateFastFFIMetadata() emits a trampoline that
  // receives a V8 value and calls node_ffi_fast_buffer_data().
- auto clone = std::make_shared<FFIFunction>(*fn);
+ auto clone = CloneForFastMetadata(fn);
  for (std::string& name : clone->arg_type_names) {
  if (IsPointerTypeName(name)) {
  name = "buffer";

src/node_ffi.cc

@@ -42,6 +42,17 @@ using v8::Value;
 
 namespace ffi {
 
+void FFIFunction::Invoke(void* result, void** values) {
+#if defined(NODE_FFI_HAS_FAST_CALL_PLAN)
+ if (call_plan != nullptr) {
+ ffi_call_plan_invoke(call_plan.get(), FFI_FN(ptr), result, values);
+ return;
+ }
+#endif
+
+ ffi_call(&cif, FFI_FN(ptr), result, values);
+}
+
 void FFIFunctionInfo::MemoryInfo(MemoryTracker* tracker) const {
  tracker->TrackField("sb_backing", sb_backing);
 }
@@ -146,14 +157,12 @@ Maybe<DynamicLibrary::PreparedFunction> DynamicLibrary::PrepareFunction(
 
  should_cache_symbol = symbols_.find(name) == symbols_.end();
 
- fn = std::make_shared<FFIFunction>(
- FFIFunction{.closed = false,
- .ptr = ptr,
- .cif = {},
- .args = args,
- .return_type = return_type,
- .arg_type_names = std::move(arg_type_names),
- .return_type_name = std::move(return_type_name)});
+ fn = std::make_shared<FFIFunction>();
+ fn->ptr = ptr;
+ fn->args = std::move(args);
+ fn->return_type = return_type;
+ fn->arg_type_names = std::move(arg_type_names);
+ fn->return_type_name = std::move(return_type_name);
 
  ffi_status status = ffi_prep_cif(&fn->cif,
  FFI_DEFAULT_ABI,
@@ -178,6 +187,14 @@ Maybe<DynamicLibrary::PreparedFunction> DynamicLibrary::PrepareFunction(
  return {};
  }
 
+#if defined(NODE_FFI_HAS_FAST_CALL_PLAN)
+ // Allocation failure is non-fatal. Invoke() falls back to ffi_call().
+ ffi_call_plan* call_plan = ffi_call_plan_alloc(&fn->cif);
+ if (call_plan != nullptr) {
+ fn->call_plan.reset(call_plan);
+ }
+#endif
+
  should_cache_function = true;
  } else {
  fn = existing->second;
@@ -550,7 +567,7 @@ void DynamicLibrary::InvokeFunction(const FunctionCallbackInfo<Value>& args) {
  result = Malloc(GetFFIReturnValueStorageSize(fn->return_type));
  }
 
-ffi_call(&fn->cif, FFI_FN(fn->ptr), result, ffi_args.data());
+ fn->Invoke(result, ffi_args.data());
 
  // Return result back to Javascript
  ToJSReturnValue(env, args, fn->return_type, result);
@@ -609,7 +626,7 @@ void DynamicLibrary::InvokeFunctionSB(const FunctionCallbackInfo<Value>& args) {
  alignas(8) uint8_t result_storage[kSBResultStorageSize] = {0};
  void* result = (fn->return_type != &ffi_type_void) ? result_storage : nullptr;
 
-ffi_call(&fn->cif, FFI_FN(fn->ptr), result, ffi_args.data());
+ fn->Invoke(result, ffi_args.data());
 
  if (result != nullptr) {
  WriteFFIReturnToBuffer(fn->return_type, result, buffer, 0);

src/node_ffi.h

@@ -14,20 +14,41 @@
 #include <unordered_map>
 #include <vector>
 
+// libffi only accelerates reusable call plans on x86-64 System V. Other
+// targets implement the API by calling ffi_call(), which adds no benefit.
+#if defined(FFI_VERSION_NUMBER) && FFI_VERSION_NUMBER >= 30700 && \
+ defined(__x86_64__) && !defined(__ILP32__) && !defined(X86_WIN64) && \
+ !defined(_WIN32)
+#define NODE_FFI_HAS_FAST_CALL_PLAN 1
+#endif
+
 namespace node::ffi {
 
 class DynamicLibrary;
 struct FFIFunction;
 
 struct FFIFunction {
- bool closed;
+ FFIFunction() = default;
+ FFIFunction(const FFIFunction&) = delete;
+ FFIFunction& operator=(const FFIFunction&) = delete;
+ FFIFunction(FFIFunction&&) = delete;
+ FFIFunction& operator=(FFIFunction&&) = delete;
 
- void* ptr;
- ffi_cif cif;
+ bool closed = false;
+
+ void* ptr = nullptr;
+ ffi_cif cif = {};
  std::vector<ffi_type*> args;
- ffi_type* return_type;
+ ffi_type* return_type = nullptr;
  std::vector<std::string> arg_type_names;
  std::string return_type_name;
+#if defined(NODE_FFI_HAS_FAST_CALL_PLAN)
+ // The plan borrows cif, so it must remain uniquely owned by this instance.
+ std::unique_ptr<ffi_call_plan, decltype(&ffi_call_plan_free)> call_plan{
+ nullptr, ffi_call_plan_free};
+#endif
+
+ void Invoke(void* result, void** values);
 };
 
 class FFIFunctionInfo final : public BaseObject {

benchmark/ffi/invoke-function.js

@@ -0,0 +1,79 @@
+'use strict';
+
+const assert = require('node:assert');
+const common = require('../common.js');
+const { libraryPath, ensureFixtureLibrary } = require('./common.js');
+
+// Measure the invocation (call) path for signatures that bypass V8 Fast API
+// and use libffi through FFIFunction::Invoke(). On x86-64 System V with
+// libffi >= 3.7, Invoke() reuses a precomputed call plan that avoids repeating
+// argument-placement work on every call. This benchmark quantifies the
+// per-call benefit.
+//
+// Signatures chosen to bypass both V8 Fast API and keep native work minimal:
+// - call_int_callback (null): 'function' type forces the generic path; null
+// pointer triggers the early return in C so native computation is negligible.
+// From libffi's perspective this is a register-only plan (2 pointer-sized
+// args both fit in GP registers on x86-64 System V).
+// - sum_8_i32: 8 GP args exceed the x86-64 Fast API register cap (6), forcing
+// the generic path. From libffi's perspective 6 args go in registers and 2
+// spill to the stack, exercising a stack-spilled plan.
+
+const bench = common.createBenchmark(main, {
+ n: [1e7],
+ symbol: ['call_int_callback', 'sum_8_i32'],
+}, {
+ flags: ['--experimental-ffi', '--no-warnings'],
+});
+
+ensureFixtureLibrary();
+
+function main({ n, symbol }) {
+ const ffi = require('node:ffi');
+
+ if (symbol === 'call_int_callback') {
+ // 'function' type bypasses Fast API (IsFastCallEligible rejects it).
+ // Pass 0n (null function pointer) so the native function returns -1
+ // immediately without invoking any callback, keeping per-call overhead
+ // dominated by the FFI call machinery itself.
+ const { lib, functions } = ffi.dlopen(libraryPath, {
+ call_int_callback: { return: 'i32', arguments: ['function', 'i32'] },
+ });
+
+ try {
+ // Verify the null-pointer early return.
+ assert.strictEqual(functions.call_int_callback(0n, 7), -1);
+
+ bench.start();
+ for (let i = 0; i < n; ++i)
+ functions.call_int_callback(0n, 21);
+ bench.end(n);
+ } finally {
+ lib.close();
+ }
+ } else {
+ // 8 integer args exceed the x86-64 SysV GP register cap (6), which makes
+ // CreateFastFFIMetadata reject the signature. Calls go through the
+ // SharedBuffer or generic invoker into FFIFunction::Invoke().
+ const { lib, functions } = ffi.dlopen(libraryPath, {
+ sum_8_i32: {
+ return: 'i32',
+ arguments: [
+ 'i32', 'i32', 'i32', 'i32',
+ 'i32', 'i32', 'i32', 'i32',
+ ],
+ },
+ });
+
+ const fn = functions.sum_8_i32;
+
+ assert.strictEqual(fn(1, 2, 3, 4, 5, 6, 7, 8), 36);
+
+ bench.start();
+ for (let i = 0; i < n; ++i)
+ fn(1, 2, 3, 4, 5, 6, 7, 14);
+ bench.end(n);
+
+ lib.close();
+ }
+}

src/ffi/fast.cc

@@ -192,13 +192,31 @@ bool SignatureNeedsFastBufferInvoke(const FFIFunction& fn) {
  IsBufferTypeName(fn.arg_type_names[0]));
 }
 
+namespace {
+
+std::shared_ptr<FFIFunction> CloneForFastMetadata(
+ const std::shared_ptr<FFIFunction>& fn) {
+ // Fast metadata only needs the native target and signature. In particular,
+ // its temporary clone must not borrow the original function's cif or plan.
+ auto clone = std::make_shared<FFIFunction>();
+ clone->closed = fn->closed;
+ clone->ptr = fn->ptr;
+ clone->args = fn->args;
+ clone->return_type = fn->return_type;
+ clone->arg_type_names = fn->arg_type_names;
+ clone->return_type_name = fn->return_type_name;
+ return clone;
+}
+
+} // namespace
+
 std::shared_ptr<FFIFunction> CloneWithRawPointerArgNames(
  const std::shared_ptr<FFIFunction>& fn) {
  // The primary Fast API entrypoint receives pointer-compatible values as
  // BigInts after the JS wrapper has converted strings, nullish values, and
  // memory-backed objects. A secondary entrypoint handles the monomorphic
  // memory-backed case without extracting the pointer in JS.
- auto clone = std::make_shared<FFIFunction>(*fn);
+ auto clone = CloneForFastMetadata(fn);
  for (std::string& name : clone->arg_type_names) {
  if (IsBufferTypeName(name)) {
  name = "pointer";
@@ -209,10 +227,10 @@ std::shared_ptr<FFIFunction> CloneWithRawPointerArgNames(
 
 std::shared_ptr<FFIFunction> CloneWithFastBufferArgNames(
  const std::shared_ptr<FFIFunction>& fn) {
- // Reuse the same native target and libffi metadata, but describe the JS
+ // Reuse the same native target and signature metadata, but describe the JS
  // argument as `buffer` so CreateFastFFIMetadata() emits a trampoline that
  // receives a V8 value and calls node_ffi_fast_buffer_data().
- auto clone = std::make_shared<FFIFunction>(*fn);
+ auto clone = CloneForFastMetadata(fn);
  for (std::string& name : clone->arg_type_names) {
  if (IsPointerTypeName(name)) {
  name = "buffer";

src/node_ffi.cc

@@ -42,6 +42,17 @@ using v8::Value;
 
 namespace ffi {
 
+void FFIFunction::Invoke(void* result, void** values) {
+#if defined(NODE_FFI_HAS_FAST_CALL_PLAN)
+ if (call_plan != nullptr) {
+ ffi_call_plan_invoke(call_plan.get(), FFI_FN(ptr), result, values);
+ return;
+ }
+#endif
+
+ ffi_call(&cif, FFI_FN(ptr), result, values);
+}
+
 void FFIFunctionInfo::MemoryInfo(MemoryTracker* tracker) const {
  tracker->TrackField("sb_backing", sb_backing);
 }
@@ -146,14 +157,12 @@ Maybe<DynamicLibrary::PreparedFunction> DynamicLibrary::PrepareFunction(
 
  should_cache_symbol = symbols_.find(name) == symbols_.end();
 
- fn = std::make_shared<FFIFunction>(
- FFIFunction{.closed = false,
- .ptr = ptr,
- .cif = {},
- .args = args,
- .return_type = return_type,
- .arg_type_names = std::move(arg_type_names),
- .return_type_name = std::move(return_type_name)});
+ fn = std::make_shared<FFIFunction>();
+ fn->ptr = ptr;
+ fn->args = std::move(args);
+ fn->return_type = return_type;
+ fn->arg_type_names = std::move(arg_type_names);
+ fn->return_type_name = std::move(return_type_name);
 
  ffi_status status = ffi_prep_cif(&fn->cif,
  FFI_DEFAULT_ABI,
@@ -178,6 +187,14 @@ Maybe<DynamicLibrary::PreparedFunction> DynamicLibrary::PrepareFunction(
  return {};
  }
 
+#if defined(NODE_FFI_HAS_FAST_CALL_PLAN)
+ // Allocation failure is non-fatal. Invoke() falls back to ffi_call().
+ ffi_call_plan* call_plan = ffi_call_plan_alloc(&fn->cif);
+ if (call_plan != nullptr) {
+ fn->call_plan.reset(call_plan);
+ }
+#endif
+
  should_cache_function = true;
  } else {
  fn = existing->second;
@@ -550,7 +567,7 @@ void DynamicLibrary::InvokeFunction(const FunctionCallbackInfo<Value>& args) {
  result = Malloc(GetFFIReturnValueStorageSize(fn->return_type));
  }
 
-ffi_call(&fn->cif, FFI_FN(fn->ptr), result, ffi_args.data());
+ fn->Invoke(result, ffi_args.data());
 
  // Return result back to Javascript
  ToJSReturnValue(env, args, fn->return_type, result);
@@ -609,7 +626,7 @@ void DynamicLibrary::InvokeFunctionSB(const FunctionCallbackInfo<Value>& args) {
  alignas(8) uint8_t result_storage[kSBResultStorageSize] = {0};
  void* result = (fn->return_type != &ffi_type_void) ? result_storage : nullptr;
 
-ffi_call(&fn->cif, FFI_FN(fn->ptr), result, ffi_args.data());
+ fn->Invoke(result, ffi_args.data());
 
  if (result != nullptr) {
  WriteFFIReturnToBuffer(fn->return_type, result, buffer, 0);

src/node_ffi.h

@@ -14,20 +14,41 @@
 #include <unordered_map>
 #include <vector>
 
+// libffi only accelerates reusable call plans on x86-64 System V. Other
+// targets implement the API by calling ffi_call(), which adds no benefit.
+#if defined(FFI_VERSION_NUMBER) && FFI_VERSION_NUMBER >= 30700 && \
+ defined(__x86_64__) && !defined(__ILP32__) && !defined(X86_WIN64) && \
+ !defined(_WIN32)
+#define NODE_FFI_HAS_FAST_CALL_PLAN 1
+#endif
+
 namespace node::ffi {
 
 class DynamicLibrary;
 struct FFIFunction;
 
 struct FFIFunction {
- bool closed;
+ FFIFunction() = default;
+ FFIFunction(const FFIFunction&) = delete;
+ FFIFunction& operator=(const FFIFunction&) = delete;
+ FFIFunction(FFIFunction&&) = delete;
+ FFIFunction& operator=(FFIFunction&&) = delete;
 
- void* ptr;
- ffi_cif cif;
+ bool closed = false;
+
+ void* ptr = nullptr;
+ ffi_cif cif = {};
  std::vector<ffi_type*> args;
- ffi_type* return_type;
+ ffi_type* return_type = nullptr;
  std::vector<std::string> arg_type_names;
  std::string return_type_name;
+#if defined(NODE_FFI_HAS_FAST_CALL_PLAN)
+ // The plan borrows cif, so it must remain uniquely owned by this instance.
+ std::unique_ptr<ffi_call_plan, decltype(&ffi_call_plan_free)> call_plan{
+ nullptr, ffi_call_plan_free};
+#endif
+
+ void Invoke(void* result, void** values);
 };
 
 class FFIFunctionInfo final : public BaseObject {

benchmark/ffi/invoke-function.js

@@ -0,0 +1,79 @@
+'use strict';
+
+const assert = require('node:assert');
+const common = require('../common.js');
+const { libraryPath, ensureFixtureLibrary } = require('./common.js');
+
+// Measure the invocation (call) path for signatures that bypass V8 Fast API
+// and use libffi through FFIFunction::Invoke(). On x86-64 System V with
+// libffi >= 3.7, Invoke() reuses a precomputed call plan that avoids repeating
+// argument-placement work on every call. This benchmark quantifies the
+// per-call benefit.
+//
+// Signatures chosen to bypass both V8 Fast API and keep native work minimal:
+// - call_int_callback (null): 'function' type forces the generic path; null
+// pointer triggers the early return in C so native computation is negligible.
+// From libffi's perspective this is a register-only plan (2 pointer-sized
+// args both fit in GP registers on x86-64 System V).
+// - sum_8_i32: 8 GP args exceed the x86-64 Fast API register cap (6), forcing
+// the generic path. From libffi's perspective 6 args go in registers and 2
+// spill to the stack, exercising a stack-spilled plan.
+
+const bench = common.createBenchmark(main, {
+ n: [1e7],
+ symbol: ['call_int_callback', 'sum_8_i32'],
+}, {
+ flags: ['--experimental-ffi', '--no-warnings'],
+});
+
+ensureFixtureLibrary();
+
+function main({ n, symbol }) {
+ const ffi = require('node:ffi');
+
+ if (symbol === 'call_int_callback') {
+ // 'function' type bypasses Fast API (IsFastCallEligible rejects it).
+ // Pass 0n (null function pointer) so the native function returns -1
+ // immediately without invoking any callback, keeping per-call overhead
+ // dominated by the FFI call machinery itself.
+ const { lib, functions } = ffi.dlopen(libraryPath, {
+ call_int_callback: { return: 'i32', arguments: ['function', 'i32'] },
+ });
+
+ try {
+ // Verify the null-pointer early return.
+ assert.strictEqual(functions.call_int_callback(0n, 7), -1);
+
+ bench.start();
+ for (let i = 0; i < n; ++i)
+ functions.call_int_callback(0n, 21);
+ bench.end(n);
+ } finally {
+ lib.close();
+ }
+ } else {
+ // 8 integer args exceed the x86-64 SysV GP register cap (6), which makes
+ // CreateFastFFIMetadata reject the signature. Calls go through the
+ // SharedBuffer or generic invoker into FFIFunction::Invoke().
+ const { lib, functions } = ffi.dlopen(libraryPath, {
+ sum_8_i32: {
+ return: 'i32',
+ arguments: [
+ 'i32', 'i32', 'i32', 'i32',
+ 'i32', 'i32', 'i32', 'i32',
+ ],
+ },
+ });
+
+ const fn = functions.sum_8_i32;
+
+ assert.strictEqual(fn(1, 2, 3, 4, 5, 6, 7, 8), 36);
+
+ bench.start();
+ for (let i = 0; i < n; ++i)
+ fn(1, 2, 3, 4, 5, 6, 7, 14);
+ bench.end(n);
+
+ lib.close();
+ }
+}

src/ffi/fast.cc

@@ -192,13 +192,31 @@ bool SignatureNeedsFastBufferInvoke(const FFIFunction& fn) {
  IsBufferTypeName(fn.arg_type_names[0]));
 }
 
+namespace {
+
+std::shared_ptr<FFIFunction> CloneForFastMetadata(
+ const std::shared_ptr<FFIFunction>& fn) {
+ // Fast metadata only needs the native target and signature. In particular,
+ // its temporary clone must not borrow the original function's cif or plan.
+ auto clone = std::make_shared<FFIFunction>();
+ clone->closed = fn->closed;
+ clone->ptr = fn->ptr;
+ clone->args = fn->args;
+ clone->return_type = fn->return_type;
+ clone->arg_type_names = fn->arg_type_names;
+ clone->return_type_name = fn->return_type_name;
+ return clone;
+}
+
+} // namespace
+
 std::shared_ptr<FFIFunction> CloneWithRawPointerArgNames(
  const std::shared_ptr<FFIFunction>& fn) {
  // The primary Fast API entrypoint receives pointer-compatible values as
  // BigInts after the JS wrapper has converted strings, nullish values, and
  // memory-backed objects. A secondary entrypoint handles the monomorphic
  // memory-backed case without extracting the pointer in JS.
- auto clone = std::make_shared<FFIFunction>(*fn);
+ auto clone = CloneForFastMetadata(fn);
  for (std::string& name : clone->arg_type_names) {
  if (IsBufferTypeName(name)) {
  name = "pointer";
@@ -209,10 +227,10 @@ std::shared_ptr<FFIFunction> CloneWithRawPointerArgNames(
 
 std::shared_ptr<FFIFunction> CloneWithFastBufferArgNames(
  const std::shared_ptr<FFIFunction>& fn) {
- // Reuse the same native target and libffi metadata, but describe the JS
+ // Reuse the same native target and signature metadata, but describe the JS
  // argument as `buffer` so CreateFastFFIMetadata() emits a trampoline that
  // receives a V8 value and calls node_ffi_fast_buffer_data().
- auto clone = std::make_shared<FFIFunction>(*fn);
+ auto clone = CloneForFastMetadata(fn);
  for (std::string& name : clone->arg_type_names) {
  if (IsPointerTypeName(name)) {
  name = "buffer";

src/node_ffi.cc

@@ -42,6 +42,17 @@ using v8::Value;
 
 namespace ffi {
 
+void FFIFunction::Invoke(void* result, void** values) {
+#if defined(NODE_FFI_HAS_FAST_CALL_PLAN)
+ if (call_plan != nullptr) {
+ ffi_call_plan_invoke(call_plan.get(), FFI_FN(ptr), result, values);
+ return;
+ }
+#endif
+
+ ffi_call(&cif, FFI_FN(ptr), result, values);
+}
+
 void FFIFunctionInfo::MemoryInfo(MemoryTracker* tracker) const {
  tracker->TrackField("sb_backing", sb_backing);
 }
@@ -146,14 +157,12 @@ Maybe<DynamicLibrary::PreparedFunction> DynamicLibrary::PrepareFunction(
 
  should_cache_symbol = symbols_.find(name) == symbols_.end();
 
- fn = std::make_shared<FFIFunction>(
- FFIFunction{.closed = false,
- .ptr = ptr,
- .cif = {},
- .args = args,
- .return_type = return_type,
- .arg_type_names = std::move(arg_type_names),
- .return_type_name = std::move(return_type_name)});
+ fn = std::make_shared<FFIFunction>();
+ fn->ptr = ptr;
+ fn->args = std::move(args);
+ fn->return_type = return_type;
+ fn->arg_type_names = std::move(arg_type_names);
+ fn->return_type_name = std::move(return_type_name);
 
  ffi_status status = ffi_prep_cif(&fn->cif,
  FFI_DEFAULT_ABI,
@@ -178,6 +187,14 @@ Maybe<DynamicLibrary::PreparedFunction> DynamicLibrary::PrepareFunction(
  return {};
  }
 
+#if defined(NODE_FFI_HAS_FAST_CALL_PLAN)
+ // Allocation failure is non-fatal. Invoke() falls back to ffi_call().
+ ffi_call_plan* call_plan = ffi_call_plan_alloc(&fn->cif);
+ if (call_plan != nullptr) {
+ fn->call_plan.reset(call_plan);
+ }
+#endif
+
  should_cache_function = true;
  } else {
  fn = existing->second;
@@ -550,7 +567,7 @@ void DynamicLibrary::InvokeFunction(const FunctionCallbackInfo<Value>& args) {
  result = Malloc(GetFFIReturnValueStorageSize(fn->return_type));
  }
 
-ffi_call(&fn->cif, FFI_FN(fn->ptr), result, ffi_args.data());
+ fn->Invoke(result, ffi_args.data());
 
  // Return result back to Javascript
  ToJSReturnValue(env, args, fn->return_type, result);
@@ -609,7 +626,7 @@ void DynamicLibrary::InvokeFunctionSB(const FunctionCallbackInfo<Value>& args) {
  alignas(8) uint8_t result_storage[kSBResultStorageSize] = {0};
  void* result = (fn->return_type != &ffi_type_void) ? result_storage : nullptr;
 
-ffi_call(&fn->cif, FFI_FN(fn->ptr), result, ffi_args.data());
+ fn->Invoke(result, ffi_args.data());
 
  if (result != nullptr) {
  WriteFFIReturnToBuffer(fn->return_type, result, buffer, 0);

src/node_ffi.h

@@ -14,20 +14,41 @@
 #include <unordered_map>
 #include <vector>
 
+// libffi only accelerates reusable call plans on x86-64 System V. Other
+// targets implement the API by calling ffi_call(), which adds no benefit.
+#if defined(FFI_VERSION_NUMBER) && FFI_VERSION_NUMBER >= 30700 && \
+ defined(__x86_64__) && !defined(__ILP32__) && !defined(X86_WIN64) && \
+ !defined(_WIN32)
+#define NODE_FFI_HAS_FAST_CALL_PLAN 1
+#endif
+
 namespace node::ffi {
 
 class DynamicLibrary;
 struct FFIFunction;
 
 struct FFIFunction {
- bool closed;
+ FFIFunction() = default;
+ FFIFunction(const FFIFunction&) = delete;
+ FFIFunction& operator=(const FFIFunction&) = delete;
+ FFIFunction(FFIFunction&&) = delete;
+ FFIFunction& operator=(FFIFunction&&) = delete;
 
- void* ptr;
- ffi_cif cif;
+ bool closed = false;
+
+ void* ptr = nullptr;
+ ffi_cif cif = {};
  std::vector<ffi_type*> args;
- ffi_type* return_type;
+ ffi_type* return_type = nullptr;
  std::vector<std::string> arg_type_names;
  std::string return_type_name;
+#if defined(NODE_FFI_HAS_FAST_CALL_PLAN)
+ // The plan borrows cif, so it must remain uniquely owned by this instance.
+ std::unique_ptr<ffi_call_plan, decltype(&ffi_call_plan_free)> call_plan{
+ nullptr, ffi_call_plan_free};
+#endif
+
+ void Invoke(void* result, void** values);
 };
 
 class FFIFunctionInfo final : public BaseObject {