|Allegro CL version 10.1|
Moderately revised from 10.0.
Arguments: name arglist &rest body
This macro creates a function that can be called from non-lisp code. It is intended that such a function be callable from lisp as well, but such functionality has not yet been provided. (This macro replaces the obsolete defun-c-callable.)
name must be a symbol representing the name of the new function to install.
arglist is an argument list specification. Each
argument is either a symbol representing the name of an argument of
:long, or it is a list of two elements
containing the argument name and foreign-type, respectively. See
The Syntax for
Foreign Types in ftype.htm for
information on pre-defined foreign types. Other foreign types can be
defined with def-foreign-type.
ftype)) is not supported though
:aligned) is. The
:lisp type is also
supported (meaning a Lisp object is passed from the foreign code to
Lisp) but see the warning below.
If the foreign type represents
:class, it creates possible pass-by-value
semantics, based on the current value of
*pass-structs-by-value* or the value given to the
If you specify an argument to be of type :lisp --
(arg-name :lisp) -- a warning will be signaled
because doing so casually is dangerous. Unless the Lisp value is an
immediate (for example, a fixnum or a character), it is actually a
pointer which is passed to Lisp. If that pointer happens to be to an
object which has been moved by the garbage collector, then it will be
invlaid and may cause Lisp to fail with a gc error.
The warning can be suppressed with the :lisp-args-will-not-move declaration:
cl-user(3): (ff:defun-foreign-callable foo ((x :double) (y :lisp))) Warning: While defining foo: for foreign callback-arg named y, specifying :lisp as a foreign type for a transition from foreign to lisp space is dangerous because the object may move due to an intervening garbage collection. If the object is an aligned address consider instead using the :aligned specification. Otherwise, if the object is static or if careful analysis shows that no movement can possibly occur, then add the :lisp-args-will-not-move option in the definition in order to remove this warning. foo cl-user(4): (ff:defun-foreign-callable foo ((x :double) (y :lisp)) (declare (:lisp-args-will-not-move t))) foo cl-user(5):
Specifying the type as
:aligned will not signal a
:aligned values (which look
like fixnums to Lisp) is complicated and aligned pointers can also be
moved, but that is uncommon. See Aligned Pointers and the :aligned
type in ftype.htm.
The first form in the body can be a declaration
form, whose valid options are
(defun-foreign-callable my-callback () (declare (:convention :c)) ...)
The possible values of the options are:
:convention: the convention provides for the specialization of calling conventions due to language or operating-system distinctions. The default convention is
:c, and is adequate for most situations.
:fastcallis also accepted. Other values are distinguished by MS Windows-based systems including
:fastcallis not supported and should not be specified. See Note 2: Possible Values for Convention on the page for def-foreign-call.
:unwind: on MS Windows based systems, defaults to 0, and to
nilon all other systems. May be
nilor an integer.
:pass-structs-by-value. This causes the
*pass-structs-by-value*variable to be set (after it has been bound to its own value at the beginning of the macro call) to the value given. The valid values are
:returning: this specifies the type of what is returned by the called function. It is ignored except when the declared value includes a foreign struct type (either a
:union, or a
:class). Those can be passed by reference or by value depending on the value of
*pass-structs-by-value*and the value given to the
:pass-structs-by-valueoption. If passing is by reference, a hidden argument is provided and the structure is arranged to be copied back to the caller, according to the calling convention of the architecture. The general form is
(ff:defun-foreign-callable foo (...) (declare (:returning <type>)) ...)
<type> is a foreign type or its name
specifying a structure. This declaration is intended to eventually
replace the convert-to-c-types argument in
cannot be used with it.
New C++ and other language based systems tend to establish exception handlers, and set up their own equivalent of unwind-protects in their own langage. Lisp knows nothing about such exception handlers, and thus tends to trash the handler chains that have been built up whenever lisp code throws over non-lisp code to a catch form in lisp code deeper in the stack. The non-lisp code had been expecting either its own exception handling system to remove the exception from the chain on the stack, or else normal functional returns to unwind the stack in a normal fashion.
:unwind value is
nil, then no special unwinding takes place. When the
argument is non-
nil (e.g. 0), then a special
"throw-by-returning-to-c" style of unwinding occurs; a throw occurs,
not by removing the stack (including the foreign code which might have
established handlers), but instead by returning the unwind-value to
that code, which should then remove its own handler and return. When
the foreign code returns, the lisp throw is again resumed until it is
completed, or until the next lisp-to-nonlisp transition is
In order to use a function defined by defun-foreign-callable, the function must first be registered using register-foreign-callable.
What the foreign-callable function returns as a foreign value is
controlled by the call to register-foreign-callable (which
actually enables the foreign callable function). If the third
(optional) argument to register-foreign-callable is
nil, an unconverted Lisp value is returned in
the foreign return register. Programmers must use the specifications
directory]/misc/lisp.h to interpret this value. If the
third argument is
t, then the Lisp value of
the function is converted to a foreign value according to the default
conversion rules, and the resulting value is returned as the foreign
value returned by the Lisp function.
The body of the foreign callable Lisp function must be carefully coded to return a Lisp value that will trigger an appropriate conversion so that the desired foreign value will actually appear at the interface.
Consider this call to defun-foreign-callable:
(defun-foreign-callable gdbm-error-handler ((string (* :char))) (error "gdbm error: ~a." (native-to-string string)))
The call native-to-string is necessary because the string argument in the callback to Lisp is done with no string conversion at callback time. The value of the string argument as passed will be an integer representing a C address. native-to-string does the necessary conversion.
See ftype.htm for information on foreign types in Allegro CL and foreign-functions.htm for general information on foreign functions in Allegro CL.
Copyright (c) 1998-2017, Franz Inc. Oakland, CA., USA. All rights reserved.
This page has had moderate revisions compared to the 10.0 page.
|Allegro CL version 10.1|
Moderately revised from 10.0.