From 8a7cdeb0412f9ef8bbe0a7833d662dbec40b472f Mon Sep 17 00:00:00 2001 From: Tom Tromey Date: Thu, 17 Dec 2015 16:51:32 -0700 Subject: [PATCH 1/2] fix formatting of ffi_prep_closure_loc arguments --- doc/libffi.texi | 32 ++++++++++++++++++++------------ 1 file changed, 20 insertions(+), 12 deletions(-) diff --git a/doc/libffi.texi b/doc/libffi.texi index 0459899..4f6512f 100644 --- a/doc/libffi.texi +++ b/doc/libffi.texi @@ -776,23 +776,30 @@ the closure function: @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}) -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 -the writable address returned by @code{ffi_closure_alloc}. +@table @var +@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. -Note that this object, and the types to which it refers, must be kept -alive until the closure itself is freed. +@item cif +The @code{ffi_cif} describing the function parameters. Note that this +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, -to your closure function. +@item user_data +An arbitrary datum that is passed, uninterpreted, to your closure +function. -@var{codeloc} is the executable address returned by -@code{ffi_closure_alloc}. +@item codeloc +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 @item cif The @code{ffi_cif} passed to @code{ffi_prep_closure_loc}. @@ -814,6 +821,7 @@ A vector of pointers to memory holding the arguments to the function. The same @var{user_data} that was passed to @code{ffi_prep_closure_loc}. @end table +@end table @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. From 6affad79111c45982fd29637a46bc756abb128a3 Mon Sep 17 00:00:00 2001 From: Tom Tromey Date: Thu, 17 Dec 2015 16:58:10 -0700 Subject: [PATCH 2/2] correctly document closure return promotion --- doc/libffi.texi | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/doc/libffi.texi b/doc/libffi.texi index 4f6512f..87a4f50 100644 --- a/doc/libffi.texi +++ b/doc/libffi.texi @@ -806,13 +806,17 @@ The @code{ffi_cif} passed to @code{ffi_prep_closure_loc}. @item ret 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 -of the type given as the return type when initializing the CIF. In -particular, closures do not have the special promotion behavior of -@code{ffi_call}. -@c FIXME: is this NULL for void-returning functions? -@c (experimentally it is not, but it seems like a good idea) + +If the function is declared as returning @code{void}, then this value +is garbage and should not be used. + +Otherwise, @var{fun} must fill the object to which this points, +following the same special promotion behavior as @code{ffi_call}. +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 A vector of pointers to memory holding the arguments to the function.