ffi: reuse libffi call plans

Precompute a libffi call plan for each fixed signature on x86-64
System V and reuse it from the generic and SharedBuffer invokers. This
avoids repeating argument-placement work for every call.
Continue to use ffi_call() with libffi older than 3.7, on other ABIs,
and when plan allocation fails.
Signed-off-by: umuoy1 <burningdian@gmail.com>
PR-URL: #64958Fixes: #64562
Refs: libffi/libffi@3cc6beb
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Gürgün Dayıoğlu <hey@gurgun.day>
Reviewed-By: Paolo Insogna <paolo@cowtech.it>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>

Author: umuoy1

benchmark/ffi/invoke-function.js

@@ -0,0 +1,79 @@
+'use strict';
+
+constassert=require('node:assert');
+constcommon=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.
+
+constbench=common.createBenchmark(main,{
+n: [1e7],
+symbol: ['call_int_callback','sum_8_i32'],
+},{
+flags: ['--experimental-ffi','--no-warnings'],
+});
+
+ensureFixtureLibrary();
+
+functionmain({ n, symbol }){
+constffi=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(leti=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',
+],
+},
+});
+
+constfn=functions.sum_8_i32;
+
+assert.strictEqual(fn(1,2,3,4,5,6,7,8),36);
+
+bench.start();
+for(leti=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;
 
 namespaceffi {
 
+voidFFIFunction::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);
+}
+
 voidFFIFunctionInfo::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;
@@ -552,7 +569,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);
@@ -611,7 +628,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)
+#defineNODE_FFI_HAS_FAST_CALL_PLAN1
+#endif
+
 namespacenode::ffi {
 
 classDynamicLibrary;
 structFFIFunction;
 
 structFFIFunction {
-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
+
+voidInvoke(void* result, void** values);
 };
 
 classFFIFunctionInfofinal : public BaseObject {

benchmark/ffi/invoke-function.js

@@ -0,0 +1,79 @@
+'use strict';
+
+constassert=require('node:assert');
+constcommon=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.
+
+constbench=common.createBenchmark(main,{
+n: [1e7],
+symbol: ['call_int_callback','sum_8_i32'],
+},{
+flags: ['--experimental-ffi','--no-warnings'],
+});
+
+ensureFixtureLibrary();
+
+functionmain({ n, symbol }){
+constffi=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(leti=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',
+],
+},
+});
+
+constfn=functions.sum_8_i32;
+
+assert.strictEqual(fn(1,2,3,4,5,6,7,8),36);
+
+bench.start();
+for(leti=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;
 
 namespaceffi {
 
+voidFFIFunction::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);
+}
+
 voidFFIFunctionInfo::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;
@@ -552,7 +569,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);
@@ -611,7 +628,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)
+#defineNODE_FFI_HAS_FAST_CALL_PLAN1
+#endif
+
 namespacenode::ffi {
 
 classDynamicLibrary;
 structFFIFunction;
 
 structFFIFunction {
-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
+
+voidInvoke(void* result, void** values);
 };
 
 classFFIFunctionInfofinal : public BaseObject {

benchmark/ffi/invoke-function.js

@@ -0,0 +1,79 @@
+'use strict';
+
+constassert=require('node:assert');
+constcommon=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.
+
+constbench=common.createBenchmark(main,{
+n: [1e7],
+symbol: ['call_int_callback','sum_8_i32'],
+},{
+flags: ['--experimental-ffi','--no-warnings'],
+});
+
+ensureFixtureLibrary();
+
+functionmain({ n, symbol }){
+constffi=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(leti=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',
+],
+},
+});
+
+constfn=functions.sum_8_i32;
+
+assert.strictEqual(fn(1,2,3,4,5,6,7,8),36);
+
+bench.start();
+for(leti=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;
 
 namespaceffi {
 
+voidFFIFunction::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);
+}
+
 voidFFIFunctionInfo::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;
@@ -552,7 +569,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);
@@ -611,7 +628,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)
+#defineNODE_FFI_HAS_FAST_CALL_PLAN1
+#endif
+
 namespacenode::ffi {
 
 classDynamicLibrary;
 structFFIFunction;
 
 structFFIFunction {
-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
+
+voidInvoke(void* result, void** values);
 };
 
 classFFIFunctionInfofinal : public BaseObject {

benchmark/ffi/invoke-function.js

@@ -0,0 +1,79 @@
+'use strict';
+
+constassert=require('node:assert');
+constcommon=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.
+
+constbench=common.createBenchmark(main,{
+n: [1e7],
+symbol: ['call_int_callback','sum_8_i32'],
+},{
+flags: ['--experimental-ffi','--no-warnings'],
+});
+
+ensureFixtureLibrary();
+
+functionmain({ n, symbol }){
+constffi=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(leti=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',
+],
+},
+});
+
+constfn=functions.sum_8_i32;
+
+assert.strictEqual(fn(1,2,3,4,5,6,7,8),36);
+
+bench.start();
+for(leti=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;
 
 namespaceffi {
 
+voidFFIFunction::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);
+}
+
 voidFFIFunctionInfo::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;
@@ -552,7 +569,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);
@@ -611,7 +628,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)
+#defineNODE_FFI_HAS_FAST_CALL_PLAN1
+#endif
+
 namespacenode::ffi {
 
 classDynamicLibrary;
 structFFIFunction;
 
 structFFIFunction {
-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
+
+voidInvoke(void* result, void** values);
 };
 
 classFFIFunctionInfofinal : public BaseObject {

benchmark/ffi/invoke-function.js

@@ -0,0 +1,79 @@
+'use strict';
+
+constassert=require('node:assert');
+constcommon=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.
+
+constbench=common.createBenchmark(main,{
+n: [1e7],
+symbol: ['call_int_callback','sum_8_i32'],
+},{
+flags: ['--experimental-ffi','--no-warnings'],
+});
+
+ensureFixtureLibrary();
+
+functionmain({ n, symbol }){
+constffi=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(leti=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',
+],
+},
+});
+
+constfn=functions.sum_8_i32;
+
+assert.strictEqual(fn(1,2,3,4,5,6,7,8),36);
+
+bench.start();
+for(leti=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;
 
 namespaceffi {
 
+voidFFIFunction::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);
+}
+
 voidFFIFunctionInfo::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;
@@ -552,7 +569,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);
@@ -611,7 +628,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)
+#defineNODE_FFI_HAS_FAST_CALL_PLAN1
+#endif
+
 namespacenode::ffi {
 
 classDynamicLibrary;
 structFFIFunction;
 
 structFFIFunction {
-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
+
+voidInvoke(void* result, void** values);
 };
 
 classFFIFunctionInfofinal : public BaseObject {

benchmark/ffi/invoke-function.js

@@ -0,0 +1,79 @@
+'use strict';
+
+constassert=require('node:assert');
+constcommon=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.
+
+constbench=common.createBenchmark(main,{
+n: [1e7],
+symbol: ['call_int_callback','sum_8_i32'],
+},{
+flags: ['--experimental-ffi','--no-warnings'],
+});
+
+ensureFixtureLibrary();
+
+functionmain({ n, symbol }){
+constffi=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(leti=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',
+],
+},
+});
+
+constfn=functions.sum_8_i32;
+
+assert.strictEqual(fn(1,2,3,4,5,6,7,8),36);
+
+bench.start();
+for(leti=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;
 
 namespaceffi {
 
+voidFFIFunction::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);
+}
+
 voidFFIFunctionInfo::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;
@@ -552,7 +569,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);
@@ -611,7 +628,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)
+#defineNODE_FFI_HAS_FAST_CALL_PLAN1
+#endif
+
 namespacenode::ffi {
 
 classDynamicLibrary;
 structFFIFunction;
 
 structFFIFunction {
-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
+
+voidInvoke(void* result, void** values);
 };
 
 classFFIFunctionInfofinal : public BaseObject {

benchmark/ffi/invoke-function.js

@@ -0,0 +1,79 @@
+'use strict';
+
+constassert=require('node:assert');
+constcommon=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.
+
+constbench=common.createBenchmark(main,{
+n: [1e7],
+symbol: ['call_int_callback','sum_8_i32'],
+},{
+flags: ['--experimental-ffi','--no-warnings'],
+});
+
+ensureFixtureLibrary();
+
+functionmain({ n, symbol }){
+constffi=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(leti=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',
+],
+},
+});
+
+constfn=functions.sum_8_i32;
+
+assert.strictEqual(fn(1,2,3,4,5,6,7,8),36);
+
+bench.start();
+for(leti=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;
 
 namespaceffi {
 
+voidFFIFunction::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);
+}
+
 voidFFIFunctionInfo::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;
@@ -552,7 +569,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);
@@ -611,7 +628,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)
+#defineNODE_FFI_HAS_FAST_CALL_PLAN1
+#endif
+
 namespacenode::ffi {
 
 classDynamicLibrary;
 structFFIFunction;
 
 structFFIFunction {
-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
+
+voidInvoke(void* result, void** values);
 };
 
 classFFIFunctionInfofinal : public BaseObject {

benchmark/ffi/invoke-function.js

@@ -0,0 +1,79 @@
+'use strict';
+
+constassert=require('node:assert');
+constcommon=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.
+
+constbench=common.createBenchmark(main,{
+n: [1e7],
+symbol: ['call_int_callback','sum_8_i32'],
+},{
+flags: ['--experimental-ffi','--no-warnings'],
+});
+
+ensureFixtureLibrary();
+
+functionmain({ n, symbol }){
+constffi=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(leti=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',
+],
+},
+});
+
+constfn=functions.sum_8_i32;
+
+assert.strictEqual(fn(1,2,3,4,5,6,7,8),36);
+
+bench.start();
+for(leti=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;
 
 namespaceffi {
 
+voidFFIFunction::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);
+}
+
 voidFFIFunctionInfo::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;
@@ -552,7 +569,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);
@@ -611,7 +628,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)
+#defineNODE_FFI_HAS_FAST_CALL_PLAN1
+#endif
+
 namespacenode::ffi {
 
 classDynamicLibrary;
 structFFIFunction;
 
 structFFIFunction {
-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
+
+voidInvoke(void* result, void** values);
 };
 
 classFFIFunctionInfofinal : public BaseObject {