@@ -3,7 +3,7 @@ This is libffi.info, produced by makeinfo version 7.1 from libffi.texi.
33This manual is for libffi, a portable foreign function interface
44library.
55
6- Copyright © 2008-2025 Anthony Green and Red Hat, Inc.
6+ Copyright © 2008-2026 Anthony Green and Red Hat, Inc.
77
88 Permission is hereby granted, free of charge, to any person obtaining
99a copy of this software and associated documentation files (the
3838This manual is for libffi, a portable foreign function interface
3939library.
4040
41- Copyright © 2008-2025 Anthony Green and Red Hat, Inc.
41+ Copyright © 2008-2026 Anthony Green and Red Hat, Inc.
4242
4343 Permission is hereby granted, free of charge, to any person obtaining
4444a copy of this software and associated documentation files (the
@@ -112,6 +112,7 @@ File: libffi.info, Node: Using libffi, Next: Memory Usage, Prev: Introduction
112112* Simple Example:: A simple example.
113113* Types:: libffi type descriptions.
114114* Multiple ABIs:: Different passing styles on one platform.
115+ * Reusable Call Plans:: Building a call plan once and reusing it.
115116* The Closure API:: Writing a generic function.
116117* Closure Example:: A closure example.
117118* Thread Safety:: Thread safety.
@@ -200,6 +201,11 @@ function:
200201 responsibility to ensure this. If CIF declares that the function
201202 returns ‘void’ (using ‘ffi_type_void’), then RVALUE is ignored.
202203
204+ RVALUE may also be ‘NULL’, in which case the call is performed and
205+ the return value is discarded. This works for any return type,
206+ including structures returned in memory; ‘libffi’ supplies internal
207+ scratch space for the callee when needed.
208+
203209 In most situations, ‘libffi’ will handle promotion according to the
204210 ABI. However, for historical reasons, there is a special case with
205211 return values that must be handled by your code. In particular,
@@ -213,7 +219,9 @@ function:
213219 AVALUES is a vector of ‘void *’ pointers that point to the memory
214220 locations holding the argument values for a call. If CIF declares
215221 that the function has no arguments (i.e., NARGS was 0), then
216- AVALUES is ignored.
222+ AVALUES is ignored. ‘ffi_call’ does not modify the vector or the
223+ argument values it points to, so both may be reused for subsequent
224+ calls.
217225
218226 Note that while the return value must be register-sized, arguments
219227 should exactly match their declared type. For example, if an
@@ -739,7 +747,7 @@ compilers that support them:
739747type descriptors in the previous example.
740748
741749
742- File: libffi.info, Node: Multiple ABIs, Next: The Closure API , Prev: Types, Up: Using libffi
750+ File: libffi.info, Node: Multiple ABIs, Next: Reusable Call Plans , Prev: Types, Up: Using libffi
743751
7447522.4 Multiple ABIs
745753=================
@@ -751,9 +759,46 @@ instance, the x86 platform has both ‘stdcall’ and ‘fastcall’ functions.
751759necessarily platform-specific.
752760
753761
754- File: libffi.info, Node: The Closure API, Next: Closure Example, Prev: Multiple ABIs, Up: Using libffi
762+ File: libffi.info, Node: Reusable Call Plans, Next: The Closure API, Prev: Multiple ABIs, Up: Using libffi
763+
764+ 2.5 Reusable Call Plans
765+ =======================
766+
767+ When the same signature is called many times - as language bindings
768+ typically do - you can build a “call plan” once and reuse it, so that
769+ each call avoids the work ‘ffi_call’ would otherwise repeat on every
770+ invocation. A plan is an opaque, caller-owned object built from a
771+ prepared ‘ffi_cif’.
772+
773+ -- Function: ffi_call_plan * ffi_call_plan_alloc (ffi_cif *CIF)
774+ Builds and returns a reusable plan for the signature described by
775+ CIF, which must already have been prepared with ‘ffi_prep_cif’.
776+ The plan does not copy CIF; CIF must remain valid for as long as
777+ the plan is used.
778+
779+ Returns ‘NULL’ only when memory cannot be allocated. A signature
780+ for which no accelerated path exists is still valid: the returned
781+ plan simply falls back to ‘ffi_call’ when it is invoked.
782+
783+ -- Function: void ffi_call_plan_invoke (ffi_call_plan *PLAN, void *FN,
784+ void *RVALUE, void **AVALUES)
785+ Calls FN using PLAN. The FN, RVALUE, and AVALUES arguments have
786+ exactly the same meaning as for ‘ffi_call’ (*note The Basics::),
787+ including the rule that integral return values narrower than a
788+ register are widened to ‘ffi_arg’.
789+
790+ A plan is immutable once built, so a single plan may be invoked
791+ concurrently from multiple threads without additional locking.
792+
793+ -- Function: void ffi_call_plan_free (ffi_call_plan *PLAN)
794+ Releases a plan returned by ‘ffi_call_plan_alloc’. Passing ‘NULL’
795+ is harmless. The ‘ffi_cif’ the plan was built from is not
796+ affected.
797+
798+
799+ File: libffi.info, Node: The Closure API, Next: Closure Example, Prev: Reusable Call Plans, Up: Using libffi
755800
756- 2.5 The Closure API
801+ 2.6 The Closure API
757802===================
758803
759804‘libffi’ also provides a way to write a generic function - a function
@@ -857,7 +902,7 @@ executable addresses.
857902
858903File: libffi.info, Node: Closure Example, Next: Thread Safety, Prev: The Closure API, Up: Using libffi
859904
860- 2.6 Closure Example
905+ 2.7 Closure Example
861906===================
862907
863908A trivial example that creates a new ‘puts’ by binding ‘fputs’ with
@@ -916,7 +961,7 @@ A trivial example that creates a new ‘puts’ by binding ‘fputs’ with
916961
917962File: libffi.info, Node: Thread Safety, Prev: Closure Example, Up: Using libffi
918963
919- 2.7 Thread Safety
964+ 2.8 Thread Safety
920965=================
921966
922967‘libffi’ is not completely thread-safe. However, many parts are, and if
@@ -1004,17 +1049,21 @@ Index
10041049* cif: The Basics. (line 14)
10051050* closure API: The Closure API. (line 13)
10061051* closures: The Closure API. (line 13)
1007- * const char *: The Basics. (line 106 )
1052+ * const char *: The Basics. (line 113 )
10081053* FFI: Introduction. (line 31)
10091054* ffi_call: The Basics. (line 72)
1055+ * ffi_call_plan *: Reusable Call Plans. (line 12)
1056+ * ffi_call_plan_alloc: Reusable Call Plans. (line 12)
1057+ * ffi_call_plan_free: Reusable Call Plans. (line 32)
1058+ * ffi_call_plan_invoke: Reusable Call Plans. (line 22)
10101059* ffi_closure_alloc: The Closure API. (line 19)
10111060* ffi_closure_free: The Closure API. (line 26)
10121061* FFI_CLOSURES: The Closure API. (line 13)
1013- * ffi_get_closure_size: The Basics. (line 118 )
1014- * ffi_get_default_abi: The Basics. (line 115 )
1062+ * ffi_get_closure_size: The Basics. (line 125 )
1063+ * ffi_get_default_abi: The Basics. (line 122 )
10151064* ffi_get_struct_offsets: Size and Alignment. (line 39)
1016- * ffi_get_version: The Basics. (line 106 )
1017- * ffi_get_version_number: The Basics. (line 110 )
1065+ * ffi_get_version: The Basics. (line 113 )
1066+ * ffi_get_version_number: The Basics. (line 117 )
10181067* ffi_prep_cif: The Basics. (line 16)
10191068* ffi_prep_cif_var: The Basics. (line 39)
10201069* ffi_prep_closure_loc: The Closure API. (line 41)
@@ -1051,36 +1100,39 @@ Index
10511100* ffi_type_ushort: Primitive Types. (line 53)
10521101* ffi_type_void: Primitive Types. (line 10)
10531102* Foreign Function Interface: Introduction. (line 31)
1054- * size_t: The Basics. (line 118 )
1055- * unsigned int: The Basics. (line 115 )
1056- * unsigned long: The Basics. (line 110 )
1103+ * size_t: The Basics. (line 125 )
1104+ * unsigned int: The Basics. (line 122 )
1105+ * unsigned long: The Basics. (line 117 )
10571106* void: The Basics. (line 72)
1058- * void <1>: The Closure API. (line 19)
1059- * void <2>: The Closure API. (line 26)
1107+ * void <1>: Reusable Call Plans. (line 22)
1108+ * void <2>: Reusable Call Plans. (line 32)
1109+ * void <3>: The Closure API. (line 19)
1110+ * void <4>: The Closure API. (line 26)
10601111
10611112
10621113
10631114Tag Table:
10641115Node: Top1387
10651116Node: Introduction2909
10661117Node: Using libffi4569
1067- Node: The Basics5098
1068- Node: Simple Example10868
1069- Node: Types11925
1070- Node: Primitive Types12436
1071- Node: Structures14753
1072- Node: Size and Alignment15864
1073- Node: Arrays Unions Enums18135
1074- Node: Type Example21112
1075- Node: Complex22418
1076- Node: Complex Type Example23932
1077- Node: Multiple ABIs26984
1078- Node: The Closure API27367
1079- Node: Closure Example31703
1080- Node: Thread Safety33347
1081- Node: Memory Usage34180
1082- Node: Missing Features35455
1083- Node: Index35832
1118+ Node: The Basics5172
1119+ Node: Simple Example11346
1120+ Node: Types12403
1121+ Node: Primitive Types12914
1122+ Node: Structures15231
1123+ Node: Size and Alignment16342
1124+ Node: Arrays Unions Enums18613
1125+ Node: Type Example21590
1126+ Node: Complex22896
1127+ Node: Complex Type Example24410
1128+ Node: Multiple ABIs27462
1129+ Node: Reusable Call Plans27849
1130+ Node: The Closure API29566
1131+ Node: Closure Example33908
1132+ Node: Thread Safety35552
1133+ Node: Memory Usage36385
1134+ Node: Missing Features37660
1135+ Node: Index38037
10841136
10851137End Tag Table
10861138
0 commit comments