samsonium/libffi
1
0
Fork 0
mirror of https://github.com/partic2/libffi synced 2026-11-11 10:37:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #221 from tromey/document-closure-ffi_arg

Browse Source 
Document closure ffi arg
This commit is contained in:
Anthony Green
2015-12-18 10:24:38 -05:00
parent 88deacdd42 6affad7911
commit 70594f7f8d
1 changed files with 31 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/libffi.texi
+31 -19
View File
@@ -776,36 +776,47 @@ the closure function:
@findex ffi_prep_closure_loc @findex ffi_prep_closure_loc
@defun ffi_status ffi_prep_closure_loc (ffi_closure *@var{closure}, ffi_cif *@var{cif}, void (*@var{fun}) (ffi_cif *@var{cif}, void *@var{ret}, void **@var{args}, void *@var{user_data}), void *@var{user_data}, void *@var{codeloc}) @defun ffi_status ffi_prep_closure_loc (ffi_closure *@var{closure}, ffi_cif *@var{cif}, void (*@var{fun}) (ffi_cif *@var{cif}, void *@var{ret}, void **@var{args}, void *@var{user_data}), void *@var{user_data}, void *@var{codeloc})
Prepare a closure function. Prepare a closure function. The arguments to
@code{ffi_prep_closure_loc} are:
@var{closure} is the address of a @code{ffi_closure} object; this is @table @var
the writable address returned by @code{ffi_closure_alloc}. @item closure
The address of a @code{ffi_closure} object; this is the writable
address returned by @code{ffi_closure_alloc}.
@var{cif} is the @code{ffi_cif} describing the function parameters. @item cif
Note that this object, and the types to which it refers, must be kept The @code{ffi_cif} describing the function parameters. Note that this
alive until the closure itself is freed. object, and the types to which it refers, must be kept alive until the
closure itself is freed.
@var{user_data} is an arbitrary datum that is passed, uninterpreted, @item user_data
to your closure function. An arbitrary datum that is passed, uninterpreted, to your closure
function.
@var{codeloc} is the executable address returned by @item codeloc
@code{ffi_closure_alloc}. The executable address returned by @code{ffi_closure_alloc}.
@item fun
The function which will be called when the closure is invoked. It is
called with the arguments:
@var{fun} is the function which will be called when the closure is
invoked. It is called with the arguments:
@table @var @table @var
@item cif @item cif
The @code{ffi_cif} passed to @code{ffi_prep_closure_loc}. The @code{ffi_cif} passed to @code{ffi_prep_closure_loc}.
@item ret @item ret
A pointer to the memory used for the function's return value. A pointer to the memory used for the function's return value.
@var{fun} must fill this, unless the function is declared as returning
@code{void}. Note that this points to memory that is exactly the size If the function is declared as returning @code{void}, then this value
of the type given as the return type when initializing the CIF. In is garbage and should not be used.
particular, closures do not have the special promotion behavior of
@code{ffi_call}. Otherwise, @var{fun} must fill the object to which this points,
@c FIXME: is this NULL for void-returning functions? following the same special promotion behavior as @code{ffi_call}.
@c (experimentally it is not, but it seems like a good idea) That is, in most cases, @var{ret} points to an object of exactly the
size of the type specified when @var{cif} was constructed. However,
integral types narrower than the system register size are widened. In
these cases your program may assume that @var{ret} points to an
@code{ffi_arg} object.
@item args @item args
A vector of pointers to memory holding the arguments to the function. A vector of pointers to memory holding the arguments to the function.
@@ -814,6 +825,7 @@ A vector of pointers to memory holding the arguments to the function.
The same @var{user_data} that was passed to The same @var{user_data} that was passed to
@code{ffi_prep_closure_loc}. @code{ffi_prep_closure_loc}.
@end table @end table
@end table
@code{ffi_prep_closure_loc} will return @code{FFI_OK} if everything @code{ffi_prep_closure_loc} will return @code{FFI_OK} if everything
went ok, and one of the other @code{ffi_status} values on error. went ok, and one of the other @code{ffi_status} values on error.