Skip to content

Commit 3cc6beb

Browse files
Anthony Greenclaude
andcommitted
x86-64: replace the transparent plan cache with an explicit ffi_call_plan API
The transparent plan cache sped up ffi_call and closures by caching a precomputed argument-placement plan per signature, but it charged every call a cache lookup and content fingerprint, and it slightly regressed signatures with no fast path (struct-by-value) that paid the key computation only to find there was nothing to do. Replace it with an opt-in API. ffi_call_plan_alloc builds a plan from a prepared cif, ffi_call_plan_invoke applies it with no per-call lookup, and ffi_call_plan_free releases it. The plan is opaque and caller-owned, immutable once built (so it may be shared across threads), and falls back to ffi_call for signatures with no fast path. ffi_call and the closure path return to their original behaviour, so callers that don't adopt the API pay nothing. The x86-64 backend provides an accelerated plan; every other target gets a portable fallback in prep_cif.c that wraps ffi_call, so the symbols are defined on all platforms. The per-thread cache, content fingerprint, thread-exit cleanup and closure demarshal layout are removed. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
1 parent 0c8f175 commit 3cc6beb

7 files changed

Lines changed: 159 additions & 282 deletions

File tree

‎doc/libffi.texi‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -118,6 +118,7 @@ values passed between the two languages.
118118
* Simple Example:: A simple example.
119119
* Types:: libffi type descriptions.
120120
* Multiple ABIs:: Different passing styles on one platform.
121+
* Reusable Call Plans:: Building a call plan once and reusing it.
121122
* The Closure API:: Writing a generic function.
122123
* Closure Example:: A closure example.
123124
* Thread Safety:: Thread safety.
@@ -806,6 +807,45 @@ necessarily platform-specific.
806807

807808
@c FIXME: document the platforms
808809

810+
@node Reusable Call Plans
811+
@section Reusable Call Plans
812+
813+
When the same signature is called many times -- as language bindings
814+
typically do -- you can build a @dfn{call plan} once and reuse it, so
815+
that each call avoids the work @code{ffi_call} would otherwise repeat
816+
on every invocation. A plan is an opaque, caller-owned object built
817+
from a prepared @code{ffi_cif}.
818+
819+
@findex ffi_call_plan_alloc
820+
@defun {ffi_call_plan *} ffi_call_plan_alloc (ffi_cif *@var{cif})
821+
Builds and returns a reusable plan for the signature described by
822+
@var{cif}, which must already have been prepared with
823+
@code{ffi_prep_cif}. The plan does not copy @var{cif}; @var{cif} must
824+
remain valid for as long as the plan is used.
825+
826+
Returns @code{NULL} only when memory cannot be allocated. A signature
827+
for which no accelerated path exists is still valid: the returned plan
828+
simply falls back to @code{ffi_call} when it is invoked.
829+
@end defun
830+
831+
@findex ffi_call_plan_invoke
832+
@defun void ffi_call_plan_invoke (ffi_call_plan *@var{plan}, void *@var{fn}, void *@var{rvalue}, void **@var{avalues})
833+
Calls @var{fn} using @var{plan}. The @var{fn}, @var{rvalue}, and
834+
@var{avalues} arguments have exactly the same meaning as for
835+
@code{ffi_call} (@pxref{The Basics}), including the rule that integral
836+
return values narrower than a register are widened to @code{ffi_arg}.
837+
838+
A plan is immutable once built, so a single plan may be invoked
839+
concurrently from multiple threads without additional locking.
840+
@end defun
841+
842+
@findex ffi_call_plan_free
843+
@defun void ffi_call_plan_free (ffi_call_plan *@var{plan})
844+
Releases a plan returned by @code{ffi_call_plan_alloc}. Passing
845+
@code{NULL} is harmless. The @code{ffi_cif} the plan was built from is
846+
not affected.
847+
@end defun
848+
809849
@node The Closure API
810850
@section The Closure API
811851

‎include/ffi.h.in‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -524,6 +524,32 @@ void ffi_call(ffi_cif *cif,
524524
void *rvalue,
525525
void **avalue);
526526

527+
/* Reusable call plans.
528+
529+
A plan captures a signature's argument placement once so that repeated
530+
calls skip the per-call work that ffi_call would otherwise redo. Build one
531+
with ffi_call_plan_alloc, invoke it as many times as you like, and release
532+
it with ffi_call_plan_free.
533+
534+
The plan is opaque and caller-owned. The cif must outlive the plan.
535+
ffi_call_plan_alloc returns NULL only on allocation failure; a signature
536+
with no fast path is still valid and ffi_call_plan_invoke falls back to
537+
ffi_call for it. A plan is immutable once built, so it may be shared and
538+
invoked concurrently from multiple threads. */
539+
typedef struct ffi_call_plan ffi_call_plan;
540+
541+
FFI_API
542+
ffi_call_plan *ffi_call_plan_alloc (ffi_cif *cif);
543+
544+
FFI_API
545+
void ffi_call_plan_invoke (ffi_call_plan *plan,
546+
void (*fn)(void),
547+
void *rvalue,
548+
void **avalue);
549+
550+
FFI_API
551+
void ffi_call_plan_free (ffi_call_plan *plan);
552+
527553
FFI_API
528554
ffi_status ffi_get_struct_offsets (ffi_abi abi, ffi_type *struct_type,
529555
size_t *offsets);

‎libffi.map.in‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,17 @@ LIBFFI_BASE_8.1 {
5858
ffi_get_closure_size;
5959
} LIBFFI_BASE_8.0;
6060

61+
/* ----------------------------------------------------------------------
62+
Reusable call plans (ffi_call_plan_*). Additive: new symbols only, the
63+
existing struct layout and entry points are untouched.
64+
-------------------------------------------------------------------- */
65+
LIBFFI_CALL_PLAN_8.4 {
66+
global:
67+
ffi_call_plan_alloc;
68+
ffi_call_plan_invoke;
69+
ffi_call_plan_free;
70+
} LIBFFI_BASE_8.1;
71+
6172
#ifdef FFI_TARGET_HAS_COMPLEX_TYPE
6273
LIBFFI_COMPLEX_8.0 {
6374
global:

‎src/plan-cache-impl.h‎

Lines changed: 0 additions & 77 deletions
This file was deleted.

‎src/plan-cache.h‎

Lines changed: 0 additions & 80 deletions
This file was deleted.

‎src/prep_cif.c‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -278,3 +278,39 @@ ffi_get_struct_offsets (ffi_abi abi, ffi_type *struct_type, size_t *offsets)
278278

279279
return initialize_aggregate(struct_type, offsets);
280280
}
281+
282+
/* Generic ffi_call_plan: a portable fallback compiled on every target that does
283+
not provide its own accelerated implementation. The x86-64 backend defines
284+
these (with a fast path) under __x86_64__ && !__ILP32__; everywhere else this
285+
plan just records the cif and invoke calls ffi_call, so the API is always
286+
present and links on all targets. The cif must outlive the plan. */
287+
#if !(defined(__x86_64__) && !defined(__ILP32__))
288+
289+
struct ffi_call_plan
290+
{
291+
ffi_cif *cif;
292+
};
293+
294+
ffi_call_plan *
295+
ffi_call_plan_alloc (ffi_cif *cif)
296+
{
297+
ffi_call_plan *plan = malloc (sizeof (struct ffi_call_plan));
298+
if (plan != NULL)
299+
plan->cif = cif;
300+
return plan;
301+
}
302+
303+
void
304+
ffi_call_plan_invoke (ffi_call_plan *plan, void (*fn) (void),
305+
void *rvalue, void **avalue)
306+
{
307+
ffi_call (plan->cif, fn, rvalue, avalue);
308+
}
309+
310+
void
311+
ffi_call_plan_free (ffi_call_plan *plan)
312+
{
313+
free (plan);
314+
}
315+
316+
#endif /* generic ffi_call_plan fallback */

0 commit comments

Comments
 (0)