libffi also provides a way to write a generic function – a
function that can accept and decode any combination of arguments.
This can be useful when writing an interpreter, or to provide wrappers
for arbitrary functions.
This facility is called the closure API. Closures are not
supported on all platforms; you can check the FFI_CLOSURES
define to determine whether they are supported on the current
platform.
Because closures work by assembling a tiny function at runtime, they
require special allocation on platforms that have a non-executable
heap. Memory management for closures is handled by a pair of
functions:
Free memory allocated using ffi_closure_alloc. The argument is
the writable address that was returned.
Once you have allocated the memory for a closure, you must construct a
ffi_cif describing the function call. Finally you can prepare
the closure function:
closure is the address of a ffi_closure object; this is
the writable address returned by ffi_closure_alloc.
cif is the ffi_cif describing the function parameters.
user_data is an arbitrary datum that is passed, uninterpreted,
to your closure function.
codeloc is the executable address returned by
ffi_closure_alloc.
fun is the function which will be called when the closure is
invoked. It is called with the arguments:
cif
The ffi_cif passed to ffi_prep_closure_loc.
ret
A pointer to the memory used for the function's return value.
fun must fill this, unless the function is declared as returning
void.
args
A vector of pointers to memory holding the arguments to the function.
user_data
The same user_data that was passed to
ffi_prep_closure_loc.
ffi_prep_closure_loc will return FFI_OK if everything
went ok, and something else on error.
After calling ffi_prep_closure_loc, you can cast codeloc
to the appropriate pointer-to-function type.
You may see old code referring to ffi_prep_closure. This
function is deprecated, as it cannot handle the need for separate
writable and executable addresses.
