def-foreign-call

$Revision: 5.0.2.2 $

Macro

Package: FOREIGN-FUNCTIONS

Arguments: (name-and-options arglist &key call-direct callback convention returning method-index release-heap arg-checking optimize-for-space)

This macro creates the specification which allows lisp to correctly call non-lisp code. Like other defining forms, its macroexpansion clearly shows what will occur and at what eval-when times. The execution of the expanded form always returns the lisp name being defined. The definition that is installed is a lisp function that serves as a wrapper and initiates the foreign call.

The following table shows the argument. The first two entries are the required arguments and the remainder are keyword arguments.

Argument	Value	Notes
name-and-options	A required argument. Symbol or a list of a symbol and an external-name specification.	The symbol represents the lisp-name for which the foreign-call definition will be installed. The external name specification can be either a string specifying a literal external name, or it can be a symbol, which represents the name of a conversion function. That conversion function must take one required argument and at least the language keyword argument, and must be defined at the time the macro expansion is executed. At that time this conversion function will be called and will receive the lisp-name specified, as well as the arguments :language lang where lang is the value of the convention keyword argument to def-foreign-call.
arglist	A required argument. A possibly empty list or argument specifications. nil and (:void) have special meanings.	nil implies much the same as it does in C, that arguments are not checked for type or number. (:void) means 0 arguments are explicitly required (also as in C). Otherwise a list of argument specifications. See Note 1: argument specifications after the table. See 4.1.1 A note on foreign addresses in foreign_functions.htm for a discussion of foreign addresses and what is expected when :foreign-address is specified.
returning	Keyword argument. Default: the foreign type :int, with a conversion to lisp type integer (with a possible overflow to a bignum). Or can be: A foreign type (defined by def-foreign-type) A list of a foreign type and a lisp type (and an optional third element which is not used but may be in a later release). :lisp, meaning a Lisp object. No conversion is done. If not actually a Lisp object, gc failure is possible. :foreign-address :single-float-from-double, a double is returned and it is converted to a single. :void, nothing is returned, the Lisp function returns nil (:void is actually a foreign type).	This argument specifies how the value returned from the foreign function will be interpreted. If both foreign and lisp types are chosen, they will be checked for consistency and a warning might be given. A common idiom is to use :returning (:int fixnum) to specify that the foreign value returned is to be simply shifted into a fixnum value, with no consing and simple truncation of the top two bits on overflow. If :foreign-address is specified, the return value will be interpreted as an unsigned integer and converted to a poistive Lisp integer. The system will not store this value into a foreign-pointer object. The discussion in 4.1.1 A note on foreign addresses in foreign_functions.htm does not specifcally apply to returning values. Programmers can add code to store the returned value as desired.
convention	Keyword argument. Default :c Other possibilities listed in Note 2: Possible Values for Convention after the table.	This argument allows the specialization of calling conventions due to language or operating-system distinctions. The default convention is :c, and is adequate for most situations. (Note that on NT and Windows95 the c/stdcall convention distinction is required for callbacks using defun-foreign-callable, but is not required in def-foreign-call).
arg-checking	t or nil (default is t)	If true, this argument causes the lisp wrapper function to first check the lisp types against the lisp argument type specifications. When nil, no argument checking is done (although the number of arguments might still be checked). If non-nil, the lisp-types specified or implied in the argument specification (provided with the arglist argument) is used to check the actual arguments to the wrapper; if a mismatch occurs, error is called. The default value is t, unless arglist is nil.
call-direct	t or nil (default is nil)	The argument causes no changes to the lisp wrapper itself, but, when specified true, allows for other lisp functions to call the foreign function directly when compiled after the def-foreign-call form is in effect. In order for the compilation of a direct-call to be successful, the argument and return types must imply simple type conversions which the compiler can handle. That list of direct-callable conversions on a platform is constantly changing, but can be examined by calling the function comp:list-call-direct-possibilities. If for any reason a call to the foreign function cannot be compiled into a direct-call, a warning is issued and a call to the wrapper is generated.
method-index	nil (the default) or an index into C++ table, as described at right.	This argument allows for calling of C++ style member-methods. The value, if specified, must be an integer index into the virtual table of the C++ class. Symbolic index specifications are not directly supported.
callback	t (the default and only allowed value)	The callback keyword is non-operative, but is retained in the hopes that its functionality can be revived in future versions. A null value indicates a promise by the programmer that the foreign function will never call-back into lisp. Unfortunately, due to the nature of OS threads implementations, this promise is currently impossible to keep. The value of this keyword is always taken as t, and a warning is issued if specified to nil.
release-heap	Only used on platforms that use the :os-threads model for multiprocessing. See Note 3: the release-heap keyword argument below the table.	The release-heap keyword allows the foreign function to operate in native-OS threads (so :os-threads is on the features list), without causing conflicting demands on the lisp heap. The values for this keyword are discussed in See Note 3: the release-heap keyword argument below the table.
optimize-for-space	t or nil (default is nil)	The optimize-for-space keyword provides for minimal space requirement for foreign-call wrappers. This option is best used in conjunction with the call-direct option. If non-nil, optimize-for-space will ensure that the wrapper definition takes up very little room, usually as a closure. This usually comes at a cost of speed, and so only makes sense when call-direct is used to compile all actual calls to the foreign function directly, so that the lisp wrapper is not called normally at all.

Note 1: Argument Specifications

Argument specifications are available with a rich set of syntax and defaults which allow for a C "feel" while still retaining the lisp semantics and power. The basic argument list is simply a list of names, e.g. (a b c d), whose types default to C int types converted in the usual manner from lisp integer types. Any one argument can be specified more fully, as a list of the name followed optionally followed by the foreign type optionally followed by the lisp type (optionally followed by a translation specification, which has not been implemented). The foreign type can either be a built-in foreign type or a type defined by def-foreign-type, or it can be one of the keywords :lisp, :foreign-address, or :single-float-no-proto. The lisp type can be any valid lisp type. If the foreign type is not specified, it defaults to :int (and the lisp type thus defaults to integer). If the foreign type is specified but the lisp type is not, a reasonable lisp type is chosen to correspond to the foreign type. If both foreign and lisp types are chosen, they will be checked for consistency and a warning might be given. A foreign type specification that includes a reference spec such as (& :int) will be interpreted as a pass-by-reference argument.

The special lisp type specification :no-proto is provided for use with a :float foreign type; it is equivalent to the :single-float-no-proto.

See 4.1.1 A note on foreign addresses in foreign_functions.htm for a discussion of foreign addresses and what is expected when :foreign-address is specified.

Note 2: Possible Values for Convention

Other than :c, (the default and suitable for most purposes). the current conventions defined are:

:fortran - This convention generally causes a conversion of most atomic arguments to pass-by-reference
:fastcall - This is a special convention used by NT and Windows95 to speed up some calls, by passing two arguments in registers. Note that in Allegro CL on X86 architectures, the first two arguments are usually passed in registers anyway in lisp, but they are different registers than used in fastcall. Also, since the calling sequence itself overshadows the speed that would be gained by saving a couple of push instructions, the foreign call to a fastcall function is not going to be very fast at all; we recommend that this option not be used unless necessary.

Note 3: the release-heap keyword argument

The native-threads implementation of Allegro CL changes some basic assumptions of the foreign functions user interface. There is always exactly one native thread per Lisp Process, but there is not necessarily a Lisp process for every thread. Threads are free to run whenever they want; however, only one thread at a time can access the Lisp heap (for read or write); a thread cannot access the Lisp heap unless it has "acquired" the heap, which is only possible after another thread has "released" the heap.

def-foreign-call allows for the specification of whether to release the heap or not during a call. The possibilities for the release-heap keyword argument are:

:never - This is the default and is compatible to the original defforeign interface; the caller necessarily has the lisp heap, this call will not release it. Note that if the foreign code being called spawns any new threads, or if it allows another thread to run, and the other thread attempts to call back into lisp, it will have to wait for the lisp heap. The danger is that the original thread may be waiting for results from its partner thread, but it has not yet given up the heap (this constitutes a deadlock situation).
:always - The foreign call always gives up the heap before making the transition into non-lisp execution. If the form is being called within the dynamic context of a excl:without-interrupts form, an error is signaled.
:when-ok - The current dynamic context is examined, and if without-interrupts is in effect, the heap is not released; otherwise the heap is released.

See foreign_functions.htm for general information on foreign functions in Allegro CL. See ftype.htm for information on foreign types.

The general documentation description is in introduction.htm. The index is in index.htm.