The "Easy" Foreign Function Interface

Note: see bind for a newer version of this extension that provides a simplified interface and better coops integration.

This extension provides a parser for a restricted subset of C and C++ that allows the easy generation of foreign variable declarations, procedure bindings and C++ class wrappers. The parser is invoked via the foreign-parse form, which extracts binding information and generates the necessary code. An example:

Usage

To use this facility, you can either run it in the interpreter and generate files with wrapper code and interact using an API, or you can load it as a compiler extension. To do the latter, pass -X easyffi to csc (or -extend easyffi to chicken). -R easyffi works also, but will not make the special read-syntax available.

This extension defines the easyffi module.

To see the expanded code generated during compilation, compile with -debug F.

A command-line tool named chicken-wrap is also available that translates C source or header files into Scheme code. Enter

% chicken-wrap -help

for more information.

The API provides the following procedures:

parse-easy-ffi

[procedure](parse-easy-ffi STRING)

Parses the C/C++ code in STRING and returns a list of top-level expressions representing compilable bindings to the defintions contained.

register-ffi-macro

check-c-syntax

Perform a superficial C/C++ syntax check and signal an error if any lexical or syntactic errors are detected.

foreign-parse

[syntax](foreign-parse STRING ...)

Parse given strings and generate foreign-interface bindings.

foreign-parse/declare

[syntax](foreign-parse/declare STRING ...)

Parse and include strings into the generated code.

foreign-include-path

[syntax](foreign-include-path STRING ...)

Appends the paths given in STRING ... to the list of available include paths to be searched when an #include ... form is processed by foreign-parse.

#> ... <# Syntax

Occurrences of the special read syntax #>[SPEC ...] ...<# will be handled according to SPEC:

If SPEC is the ? character, the text following up to the next <# will be processed as a (declare (foreign-parse "...")) declaration (the code will be processed by the FFI parser described in this section).

If SPEC is the ! character, the text will be embedded as (foreign-parse/declare "..."). It will be both included verbatim in the declaration section of the generated C/C++ file and processed by the FFI parser.

If SPEC is the : character, the text will be so it will be executed at the location where it appears.

If SPEC is a list of the form (TAG ...), then each TAG (which should be a symbol) specifies what should be done with the text:

Basic token-substitution of macros defined via #define is performed. The preprocessor commands #ifdef, #ifndef, #else, #endif, #undef and #error are handled. The preprocessor commands #if and #elif are not supported and will signal an error when encountered by the parser, because C expressions (even if constant) are not parsed. The preprocessor command #pragma is allowed but will be ignored.

During processing of foreign-parse declarations the macro CHICKEN is defined (similar to the C compiler option -DCHICKEN).

Macro- and type-definitions are available in subsequent foreign-parse declarations. C variables declared generate a procedure with zero or one argument with the same name as the variable. When called with no arguments, the procedure returns the current value of the variable. When called with an argument, then the variable is set to the value of that argument. C and C++ style comments are supported. Variables declared as const will generate normal Scheme variables, bound to the initial value of the variable.

Function-, member-function and constructor/destructor definitions may be preceded by the ___safe qualifier, which marks the function as (possibly) performing a callback into Scheme. If a wrapped function calls back into Scheme code, and ___safe has not been given very strange and hard to debug problems will occur.

Functions and member functions prefixed with ___discard and a result type that maps to a Scheme string (c-string), will have their result type changed to c-string* instead.

Constants (as declared by #define or enum) are not visible outside of the current Compilation units unless the export_constants pseudo declaration has been used. Only numeric or character constants are directly supported.

Function-arguments may be preceded by ___in, ___out and ___inout qualifiers to specify values that are passed by reference to a function, or returned by reference. Only basic types (booleans, numbers and characters) can be passed using this method. During the call a pointer to a temporary piece of storage containing the initial value (or a random value, for ___out parameters) will be allocated and passed to the wrapped function. This piece of storage is subject to garbage collection and will move, should a callback into Scheme occur that triggers a garbage collection. Multiple __out and ___inout parameters will be returned as multiple values, preceded by the normal return value of thhe function (if not void). Here is a simple example:

#>!
#ifndef CHICKEN
#include <math.h>
#endif

double modf(double x, ___out double *iptr);
<#

(let-values ([(frac int) (modf 33.44)])
...)

Function-arguments may be preceded by ___length(ID), where ID designates the name of another argument that must refer to a number vector or string argument. The value of the former argument will be computed at run-time and thus can be omitted:

The length variable may be positioned anywhere in the argument list. Length markers may only be specified for arguments passed as SRFI-4 byte-vectors, byte-vectors (as provided by the lolevel library unit) or strings.

Structure and union definitions containing actual field declarations generate getter procedures (and SRFI-17 setters when declared ___mutable or the mutable_fields pseudo declaration has been used) The names of these procedures are computed by concatenating the struct (or union) name, a hyphen ("-") and the field name. Structure definitions with fields may not be used in positions where a type specifier is normally expected. The field accessors operate on struct/union pointers only. Additionally a zero-argument procedure named make-<structname> will be generated that allocates enough storage to hold an instance of the structure (or union). Prefixing the definition with ___abstract will omit the creation procedure.

Nested structs or unions are not supported (but pointers to nested structs/unions are).

All specially handled tokens preceded with ___ are defined as C macros in the headerfile chicken.h and will usually expand into nothing, so they don't invalidate the processed source code.

C++ namespace declarations of the form namespace NAME @{ ... @} recognized but will be completely ignored.

Keep in mind that this is not a fully general C/C++ parser. Taking an arbitrary headerfile and feeding it to CHICKEN will in most cases not work or generate riduculuous amounts of code. This FFI facility is for carefully written headerfiles, and for declarations directly embedded into Scheme code.

Pseudo declarations

Using the ___declare(DECL, VALUE) form, pseudo declarations can be embedded into processed C/C++ code to provide additional control over the wrapper generation. Pseudo declarations will be ignored when processed by the system's C/C++ compiler.

abstract [values: <string>]

Marks the C++ class given in <string> as being abstract, i.e. no constructor will be defined. Alternatively, a class definition may be prefixed with ___abstract.

class_finalizers [values: yes, no]

Automatically generates calls to set-finalizer! so that any unused references to instances of subsequently defined C++ class wrappers will be destroyed. This should be used with care: if the embedded C++ object which is represented by the reclaimed TinyCLOS instance is still in use in foreign code, then unpredictable things will happen.

mutable_fields [values: yes, no]

Specifies that all struct or union fields should generate setter procedures (the default is to generate only setter procedures for fields declared ___mutable).

destructor_name [values: <string>]

Specifies an alternative name for destructor methods (the default is destroy.

export_constants [values: yes (default), no]

Define a global variable for constant-declarations (as with #define or enum), making the constant available outside the current compilation unit. Use the values yes/1 for switching constant export on, or no/0 for switching it off.

exception_handler [values: <string>]

Defines C++ code to be executed when an exception is triggered inside a C++ class member function. The code should be one or more catch forms that perform any actions that should be taken in case an exception is thrown by the wrapped member function:

Enables full specialization mode. In this mode all wrappers for functions, member functions and static member functions are created as fully specialized TinyCLOS methods. This can be used to handle overloaded C++ functions properly. Only a certain set of foreign argument types can be mapped to TinyCLOS classes, as listed in the following table:

Alternatively, member function definitions may be prefixed by ___specialize for specializing only specific members.

prefix [values: <string>]

Sets a prefix that should be be added to all generated Scheme identifiers. For example

___declare(prefix, "mylib:")
#define SOME_CONST 42

would generate the following code:

(define-constant mylib:SOME_CONST 42)

To switch prefixing off, use the values no or 0. Prefixes are not applied to Class names.

rename [value: <string>]

Defines to what a certain C/C++ name should be renamed. The value for this declaration should have the form "<c-name>;<scheme-name>", where <c-name> specifies the C/C++ identifier occurring in the parsed text and <scheme-name> gives the name used in generated wrapper code.

scheme [value: <string>]

Embeds the Scheme expression <string> in the generated Scheme code.

substitute [value: <string>]

Declares a name-substitution for all generated Scheme identifiers. The value for this declaration should be a string containing a regular expression and a replacement string (separated by the ; character):

___declare(substitute, "^SDL_;sdl:")

extern void SDL_Quit();

generates

(define sdl:Quit
(foreign-lambda integer "SDL_Quit") )

transform [values: <string>]

Defines an arbitrary transformation procedure for names that match a given regular expression. The value should be a string containing a regular expression and a Scheme expression that evaluates to a procedure of one argument. If the regex matches, the procedure will be called at compile time with the match-result (as returned by string-match) and should return a string with the desired transformations applied:

Chooses a standard name-transformation, converting underscores (_) to hyphens (-) and transforming CamelCase into camel-case. All uppercase characters are also converted to lowercase. The result is prefixed with the argument string (equivalent to the prefix pseudo declaration).

type [value: <string>]

Declares a foreign type transformation, similar to define-foreign-type. The value should be a list of two to four items, separated by the ; character: a C typename, a Scheme foreign type specifier and optional argument- and result-value conversion procedures.

;;;; foreign type that converts to unicode (assumes 4-byte wchar_t):
;
; - Note: this is rather kludgy and is only meant to demonstrate the `type'
; pseudo-declaration

Similar to type, but provides automatic argument- and result conversions to wrap a value into a structure:

#>?
___declare(opaque, "myfile;(pointer \"FILE\")")

myfile fopen(char *, char *);
<#

(fopen "somefile" "r") ==> <myfile>

___declare(opaque, "TYPENAME;TYPE") is basically equivalent to ___declare(type, "TYPENAME;TYPE;TYPE->RECORD;RECORD->TYPE") where TYPE->RECORD and RECORD->TYPE are compiler-generated conversion functions that wrap objects of type TYPE into a record and back.

The ___pointer argument marker disables automatic simplification of pointers to numbers: normally arguments of type int * are handled as SRFI-4 s32vector number vectors. To force treatment as a pointer argument, precede the argument type with ___pointer.

C notes

Foreign variable definitions for macros are not exported from the current compilation unit, but definitions for C variables and functions are.

foreign-parse does not embed the text into the generated C file, use foreign-declare for that (or even better, use the #>! ... <# syntax which does both).

Functions with variable number of arguments are not supported.

C++ notes

Each C++ class defines a TinyCLOS class, which is a subclass of <c++-object>. Instances of this class contain a single slot named this, which holds a pointer to a heap-allocated C++ instance. The name of the TinyCLOS class is obtained by putting the C++ classname between angled brackets (<...>). TinyCLOS classes are not seen by C++ code.

The C++ constructor is invoked by the initialize generic, which accepts as many arguments as the constructor. If no constructor is defined, a default-constructor will be provided taking no arguments. To allow creating class instances from pointers created in foreign code, the initialize generic will optionally accept an arguments list of the form 'this POINTER, where POINTER is a foreign pointer object. This will create a TinyCLOS instance for the given C++ object.

To release the storage allocated for a C++ instance invoke the destroy generic (the name can be changed by using the destructor_name pseudo declaration).

Static member functions are wrapped in a Scheme procedure named <class>::<member>.

Member variables and non-public member functions are ignored.

Virtual member functions are not seen by C++ code. Overriding a virtual member function with a TinyCLOS method will not work when the member function is called by C++.

Operator functions and default arguments are not supported.

Exceptions must be explicitly handled by user code and may not be thrown beyond an invocation of C++ by Scheme code.

Authors

License

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following
conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following
disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of the author nor the names of its contributors may be used to endorse or promote
products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS
OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.