Next: def-alien-routine Example, Previous: The alien-funcall Primitive, Up: Alien Function Calls [Contents][Index]
This macro is a convenience for automatically generating Lisp interfaces to simple foreign functions. The primary feature is the parameter style specification, which translates the C pass-by-reference idiom into additional return values.
name is usually a string external symbol, but may also be a symbol Lisp name or a list of the foreign name and the Lisp name. If only one name is specified, the other is automatically derived, (see external-aliens.)
result-type is the Alien type of the return value. Each
remaining subform specifies an argument to the foreign function.
aname is the symbol name of the argument to the constructed
function (for documentation) and atype is the Alien type of
corresponding foreign argument. The semantics of the actual call
are the same as for alien-funcall
. style should be
one of the following:
:in
specifies that the argument is passed by value.
This is the default. :in
arguments have no corresponding
return value from the Lisp function.
:out
specifies a pass-by-reference output value. The
type of the argument must be a pointer to a fixed sized object
(such as an integer or pointer). :out
and :in-out
cannot be used with pointers to arrays, records or functions. An
object of the correct size is allocated, and its address is passed
to the foreign function. When the function returns, the contents
of this location are returned as one of the values of the Lisp
function.
:copy
is similar to :in
, but the argument is copied
to a pre-allocated object and a pointer to this object is passed
to the foreign routine.
:in-out
is a combination of :copy
and :out
.
The argument is copied to a pre-allocated object and a pointer to
this object is passed to the foreign routine. On return, the
contents of this location is returned as an additional value.
Any efficiency-critical foreign interface function should be inline
expanded by preceding def-alien-routine
with:
(declaim (inline lisp-name))
In addition to avoiding the Lisp call overhead, this allows pointers, word-integers and floats to be passed using non-descriptor representations, avoiding consing (see non-descriptor.)
Next: def-alien-routine Example, Previous: The alien-funcall Primitive, Up: Alien Function Calls [Contents][Index]