Scieneer Common Lisp 1.3.9 online documentation

Alien interface

Introduction

The alien interface to foreign functions and variables is largely compatible with the CMU CL implementation. Support is also provided for the portable UFFIi and CFFI foreign function interface libraries which are available in the freeware collection.

Some notable extensions in the Scieneer Common Lisp are noted below.

Loading

ext:load-dynamic-object file &rest args &key verbose reload[Function]

Load a dynamic object from the given file. If reload is true then the file is noted in a saved lisp core and reloaded when restarted.

ext:close-dynamic-object file[Function]

ext:load-foreign files &rest args &key libraries env verbose reload[Function]

Load-foreign loads a list of C object files into a running Lisp. The files argument may be a single file or a list of files. The files may be specified as namestrings or as pathnames. The libraries argument should be a list of library files as would be specified to ld. They will be searched in the order given. The default is just "-lc", i.e., the C library. The env argument is the Unix environment variable definitions for the invocation of the linker - the default is the environment passed to Lisp.

If reload is true then the files and other arguments are noted in a saved lisp core and are relinked and reloaded when restarted. Since ext:load-foreign firstly calls the system linker to create a dynamic library, it is recommened that foreign code to be loaded upon the restart of a save lisp core file be pre-linked and saved in a dynamic library file and loaded using ext:load-dynamic-object.

Callbacks

alien:defcallback name (result-type &rest arg-specs) &parse-body (body decls doc)[Macro]

(defcallback name (result-type {(arg-name arg-type)}*) {doc-string} {decls}* {form}*)

Defined a named callback lisp function of the specified name. The namespace of callback functions is separate from the lisp function namespace.

If the callback is already defined then the callback function is redefined but the callback SAP remains the same so that foreign code calling the callback calls the new function. If the arguments are not compatible then a continuable error is signaled with a range of restart options.

The address of the callback is returned by alien:callback-sap, and this address may be passed to foreign code to call back into lisp. The arg-name is a symbol that names the argument, and the arg-type is the C-Type of the argument. The result-type is the C-Type for the function return value and c-call:void may be used to specify a function with no result.

The callback SAP may change when lisp is restarted so care needs to be taken not to store and use stale addresses.

alien:callback-sap name[Function]

Return the system-area-pointer for the named callback name. The pointer may be passed to foreign code to call back into lisp. The pointer may change when lisp is restarted so it is recommended to call alien:callback-sap to obtain the pointer when needed. This function compiles to fast inline code. See also: alien:defcallback.

Pinning objects

ext:with-pinned-object (object &key :inhibit-write-protection) &body body[Macro]

Pin the address of the object in the lisp heap while the body executes. This prevents the garbage collector moving the object while the body executes.

When the inhibit-write-protection argument is true, which is the default, all pages touched by the object have their write protection cleared. This is necessary if foreign code will be writing to the object to avoid foreign code clashing with the garbage collector. The garbage collector will not set page write protection of pinned objects once cleared. If a pinned object is only accessed from lisp code, or only read by foreign code then it is not necessary to clear write protection.

Miscellaneous

sys:foreign-symbol-address name[Function]

Return the foreign address of the symbol with the given name. If the symbol is not yet defined then the returned address is zero.

c-call:*foreign-encoding*[Variable]

The default character format encoding to use when converting to or from an alien c-call:c-string. The default encoding is :iso-8859-1.

alien:with-bytes (var size) &body body[Macro]

Allocate an array of bytes, on the local stack if possible, binding var to a system area pointer pointing to the start of the alien array.