The C interface

We call all the pieces of program devoted to the interactions between Scheme and another language a foreign interface. In Bigloo, the foreign interface allows Scheme's functions and variables to be exported to a foreign language and foreign functions and variables to be imported into the Scheme code. Using the foreign interface requires two kind of operations.

• Declarations --- type declarations,
import declarations or export declarations.
• Foreign reference in the Scheme code.

Declarations take place in a special module clause, see Module Declaration, and reference to foreign variables within Scheme code requires no special construction. The current release of Bigloo includes a C and a Java interface. The Java connection is specified by the means of a java clause (see Java Interface). The C interface is active (that is the extern module clauses are read) only when compiling to C. So, when compiling to Jvm the binding declared in an extern clause are not bound.

Connecting Bigloo code with C is generally straightforward. To illustrate this simplicity, let us consider a simple example involving two source files. First a simple C file sum.c containing a single declaration:

int sum(int x, int y) { return x + y; }

Then, let us assume a Bigloo source code main.scm that makes uses of that C function:

(module foo
   (extern (sum::int (::int ::int) "sum"))
   (main main))

(define (main x)
   (print (sum (length x) 10)))

With a Unix installation of Bigloo, this program can be compiled and executed with the following commands:

  $ gcc sum.c -c
  $ bigloo main.scm sum.o -o main
  $ ./main 1 2 3

The connection between Scheme and C is made particularly easy by Bigloo because the programmer is free from inserting conversion between Scheme values and C values. When needed, these are automatically inserted by the compiler.

The syntax of the foreign declarations

The syntax of foreign clauses is defined by:

<extern> ⇒ <variable-clause>
     | <function-clause>
     | <include-clause>
     | <export-clause>
     | <type-clause>

Foreign clauses are automatically ``transmitted'' by the importation process. That is, if module module1 imports a module module2, module treats the extern clauses of module2 as though they were included in its own module declaration. Redefinition of a variable or a function already defined in an foreign clause is an error.

Automatic extern clauses generation

Extern clauses can be automatically generated using the Cigloo program which is distributed in the same package as Bigloo. Using Cigloo may be a good way to understand how C prototypes (and types) have to be declared in Bigloo. Cigloo reads C files and generates the Bigloo extern clauses for that files.

Importing an extern variable

The <variable-clause> denotes importation of variables.

<variable-clause> ⇒ ( <typed-ident> <c-name>)
     | (macro <typed-ident> <string>)
     | (macro <typed-ident> (<typed-ident>+) <string>)
     | (infix macro <typed-ident> (<typed-ident>+) <string>)

Only extern ``non-macro'' variables are mutable (that is mutable using the set! construction). Bigloo does not emit ``extern C prototype'' for variables introduced by a macro clause. <string> is the C name of variable. The Scheme name of that variable is extracted from the <typed-ident>.

Here is an example of variable importations:

(module example
   (extern (c-var::double "c_var")
           (macro bufsiz::long "BUFSIZ")))

(print "c-var: " c-var)
(set! c-var (+ 1.0 c-var))
(print "c-var: " c-var)
(print "bufsize: " BUFSIZ)

Importing an extern function

Function are imported using the <function-clause>.

<function-clause> ⇒ (<typed-ident> (<typed-ident>*) <string>)
     | (<typed-ident> (<typed-ident>+ . <typed-ident>) <string>)
     | (macro <typed-ident> (<typed-ident>*) <string>)
     | (macro <typed-ident> (<typed-ident>+ . <typed-ident>) <string>)

The function result type and Scheme name are extracted from the <typed-ident>; the <typed-ident> denotes the type of the function arguments and <string> is the C name of the function. Bigloo does not produce ``C extern prototype'' for macro functions (those introduced by macro clauses). If the typed identifier of the function does not contain any type information. Bigloo will emit a warning message when compiling and it will use a default C type (e.g. the int C type) as the return type of the function.

(module example
   (extern (macro prn::int (::string . ::long) "printf")))

(let ((n (read)))
   (prn #"fib(%d): %d\n" n (fib n)))

Including an extern file

C files can be included in the C code produced by using <include-clause>.

<include-clause> ⇒ (include <string>)

Exporting a Scheme variable

A Scheme variable (or function) can be exported to the foreign world if and only if it is also exported using an export clause. Type information is given in the Scheme exportation, thus, the only requirement for a variable to be extern exported is to be given a foreign name. The foreign <export-clause> does this:

<export-clause> ⇒ (export <ident> <string>)

Here is an example of exportation:

(module example
   (export (fib::long ::long))
   (extern (export fib "scheme_fib")))

(define (fib x) (if (< x 2) 1 ...))

Defining an extern type

New Bigloo types can be defined using extern <type-clause>. These newly introduced types can be used in any declaration (that is in any extern or Scheme module clause and in any Scheme variable or function definition). The syntax of <type-clause> is:

<type-clause> ⇒ (type <ident> <type-def> <string>)
<type-def> ⇒ <atomic-type>
     | <ident>
     | <struct-type>
     | <union-type>
     | <function-type>
     | <array-type>
     | <pointer-type>
     | <enum-type>
     | <opaque-type>

The symbol <ident> is the Scheme name of the introduced type and <string> is the C name of the type. When Bigloo produces the definition of a variable v of type s, it produces the following C code: s v;. This rules applies unless s is a pointer or an array and then, to produce a C definition, the name of the elements of the array or the elements pointed by the pointer type are used. Hence, if v is for instance foo and s is (array int) the produced C code will be: int *foo.

Atomic types

The atomic types are the pre-existing ones, defined in the standard Bigloo's library.

<atomic-type> ⇒ <bigloo-type> 
     | <c-type>                                   
<bigloo-type> ⇒ obj procedure 
     | pair | nil | pair-nil 
     | bint | blong | belong | bllong
     | bignum  |real | bbool | cnst          
     | bstring | ucs2string | bchar | bucs2
     | vector | tvector | struct        
     | tstruct | output-port | input-port    
     | binary-port | unspecified | symbol | keyword
     | cell | date | process | exit 
     | mutex | condvar | mmap
     | s8vector | u8vector | s16vector | u16vector
     | s32vector | u32vector | s64vector | u64vector
     | f32vector | f64vector
     | dynamic-env | opaque | foreign       
<c-type> ⇒ cobj char 
     | uchar | short    
     | ushort | int | uint | long
     | ulong | slong | elong | llong
     | bool | string 
     | file | double | float | void 
     | function

The type obj denotes the super type of all Bigloo types (i.e., all Bigloo types, such as procedure, pair, ...) is an obj. The type cobj denotes the super of all C types (i.e., all preexisting C types such as char, uchar, schar, short, ...). The type pair-nil denotes values that are either pairs or the () value.

Struct and Union types

C struct and Union types can be declared in Bigloo using <struct-type> clauses:

<struct-type> ⇒ (struct (<typed-ident> <string>)^+)   
<union-type> ⇒ (union (<typed-ident> <string>)^+)

This clause declared a C struct but C structure values cannot be handled by Bigloo. Instead Bigloo is able to handle pointers to C structure. Thus, in order to help the definition of extern types, when a struct named struct is defined, if it does not exists yet, Bigloo automatically defines a type pointer to the structure. This type is named struct*.

When a pointer to a structure type is defined, Bigloo automatically produces functions to manipulate objects of this type. Let us suppose the type definition of struct*:

(type struct
   (struct (id1::type1 name1)
           ...
           (idn::typen namen))

The following functions are created:

• A creator:

(struct*::struct* ::type_1 ... ::type_n)

This function allocates a fresh struct* (in the same heap as any Scheme value) and fills the fields of the C structure with the proper values provided in the call.
• A type checker:

(struct*?::bool obj::obj)

This function returns #t if and only if the argument obj is of type struct*.
• A null checker:

(struct*-null?::bool ::struct*)

This function returns #t if and only if its argument is Null.
• A null creator:

(make-null-struct::struct*)

This function creates a NULL value of type struct*.
• An equality checker:

(=struct*?::bool ::struct* ::struct*)

This function returns #t if and only if its arguments are equal.
• Accessors and mutators:

(struct*-id_1::type_1 ::struct*)
(struct*-id_1-set!::obj ::struct* ::type_1)
...

These functions read and store field values.

Here is an example of structure usage:

(module foo 
   (extern 
     (include "named_point_declaration.h")
     (type named-point 
           (struct (x::double "x")
                   (y::double "y")
                   (name::string "name"))
           "struct named_point")
     (c-print-point::int (named-point*) "ppoint")))

(define (scheme-print-point point)
   (print "point*-name: " point
          " x: " (named-point*-x point)
          " y: " (named-point*-y point)))

(let ((orig (named-point* 0.0 0.0 "orig")))
   (if (named-point*-null? orig)
       (error "bigloo" "cannot allocate point" orig)
       (begin
          (c-print-point orig)
          (scheme-print-point orig))))

C pointers

C pointers are defined by the <pointer-type>

<pointer-type> ⇒ (pointer <ident>)

<ident> is the name of a previously defined type. Let us suppose the pointer type declaration:

(type ptr (pointer ident) ...)

If ident is the name of a structure type, Bigloo automatically creates structure accessors (see C structures and unions). Otherwise, it creates the following functions:

• A creator:

(make-ptr::ptr nb::long)

This function allocates memory for nb elements of type ident and returns a ptr to this zone. The memory is filled with the C Null value.
• A type checker:

(ptr?::bool obj::obj)

This function returns #t the argument obj is of type ptr and #f otherwise.
• A null checker:

(ptr-null?::bool ::ptr)

This function returns #t if its argument is Null and #f otherwise.
• A null creator:

(make-null-ptr::ptr*)

This function creates a NULL value of type ptr*.
• An equality checker:

(=ptr*?::bool ::ptr* ::ptr*)

This function returns #t if its arguments are equal and #f otherwise.
• Accessors and mutators:

(ptr-ref::ident ::ptr ::long)
(ptr-set!::obj ::ptr ::long ::ident)

These functions read and store field values.

Here is an example of a program using pointer types:

(module foo 
   (extern 
    (type double* (pointer double) "double *")))

(define (make-vect::double* x y z)
   (let ((vect (make-double* 3)))
      (double*-set! vect 0 x)
      (double*-set! vect 1 y)
      (double*-set! vect 2 z)
      vect))

(define (vect-norm vect::double*)
   (sqrt (+ (expt (double*-ref vect 0) 2)
            (expt (double*-ref vect 1) 2)
            (expt (double*-ref vect 2) 2))))

(print (vect-norm (make-vect 1.2 4.5 -4.5)))

C null pointers

It may be convenient to build C null pointers. Several means can be used. In particular, foreign structures and pointers are provided with Null creators. For other foreign types, the easiest one is likely to be a pragma form. For instance, in order to create a null pointer to a double* type, one may use:

(pragma::double* "((double *)0L)")

string-ptr-null? stringbigloo procedure

void*-null? void*bigloo procedure

These two predicates checks if there argument is the C NULL value.

make-string-ptr-nullbigloo procedure

make-void*-nullbigloo procedure

These two constructors creates null foreign values.

C arrays

C arrays are defined by the <array-type>

<array-type> ⇒ (array <ident>)

<ident> is the name of a previously defined type. Array types are similar to pointer types except that they include their size in their type definition string. Let us suppose the array type declaration:

(type array (array ident) ...)

If ident is the name of a structure type, Bigloo automatically creates structures accessors (see C structures and unions). Otherwise, it creates the following functions:

• A creator:

(make-array::array)

This function allocates memory for the array array. The memory is filled with the C Null value.
• A type checker:

(array?::bool obj::obj)

This function returns #t if the argument obj is of type array and #f otherwise.
• A null checker:

(null-array?::bool ::array)

This function returns #t if the argument obj is Null and #f otherwise.
• An equality checker:

(=array*?::bool ::array* ::array*)

This function returns #t if its arguments are equal and #f otherwise.
• Accessors and mutators:

(array-ref::ident ::array ::long)
(array-set!::obj ::array ::long ::ident)

These functions read and store field values.

Here is an example of a program using array types:

(module foo 
   (extern 
    (type double* (array double) "double [ 10 ]")))

(define (make-vect::double* x y z)
   (let ((vect (make-double*)))
      (double*-set! vect 0 x)
      (double*-set! vect 1 y)
      (double*-set! vect 2 z)
      vect))

(define (vect-norm vect::double*)
   (sqrt (+ (expt (double*-ref vect 0) 2)
            (expt (double*-ref vect 1) 2)
            (expt (double*-ref vect 2) 2))))


(print (vect-norm (make-vect 1.2 4.5 -4.5)))

C functions

C function types are introduced by the <function-type> clause:

<function-type> ⇒ (function <ident> (<ident>*))

Let us suppose the array type declaration:

(type fun (function res (arg*)) ...)

Bigloo creates the following functions:

• A type checker:

(fun?::bool obj::obj)

This function returns #t if the argument obj is of type fun and #f otherwise.
• An equality checker:

(=fun*?::bool ::fun* ::fun*)

This function returns #t if and only if its arguments are equal.
• Caller:

(fun-call::res f::fun a::ta ...)

This function invokes f with the arguments a ... an.

Suppose we have to use in Scheme the following C variable:

double (*convert)(char *);

It can be done as in:

(module foo 
   (extern
    (type *string->double
          (function double (string)) 
                    "double (*)(char *)")
    (macro cv::*string->double "convert")))

(print (*string->double-call cv "3.14"))

C enums

This form defines enum types.

<enum-type> ⇒ (enum (<ident> <string>)... ...)

Let us suppose the type:

(type enum
   (enum (id_1 name_1)
         ...
         (id_n name_n)))

Bigloo creates the following functions:

• Creators:

(enum-id_1::enum)
...
(enum-id_n::enum)

These functions create enum values.
• A type checker:

(enum?::bool obj::obj)

This function returns #t if the argument obj is of type enum and #f otherwise.
• An equality checker:

(=enum?::bool ::enum ::enum)

This function returns #t if the arguments are equal and #f otherwise.

Here is an example of Scheme code using enum type.

(module foo
   (extern
    (type gizmo
          (enum (titi "titi")
                (tutu "tutu")
                (tata "tata"))
          "enum toto")))

(let ((v1 (gizmo-titi))
      (v2 (gizmo-tutu)))
   (print (=gizmo? v1 v2)))

C opaques

This form defines opaque types.

<opaque-type> ⇒ (opaque)

Let us suppose the type:

(type opa (opaque) ...)

Bigloo creates the following functions:

• A type checker:

(opa?::bool obj::obj)

This function returns #t if the argument obj is of type opa and #f otherwise.
• An equality checker:

(=opa?::bool ::opa ::opa)

This function returns #t if the arguments are equal and #f otherwise.

Opaque types are relevant when a C value must transit via a Scheme function from a C function to another C function. The value can't be used in Scheme because no accessors are defined over that type it can only be send back to a C function.

Here is an example of Scheme code using opaque type.

(module foo
   (extern (type filedes (opaque) "FILE *")
           (macro _fopen::filedes (::string ::string) "fopen")
           (_fgetc::int (::filedes) "fgetc")
           (_fclose (::filedes) "fclose"))
   (export (fopen::filedes ::bstring ::bstring)
           (fclose ::filedes)
           (fgetc::char ::filedes)))

(define (fopen fname mode)
   (_fopen fname mode))

(define (fclose filedes)
   (_fclose filedes))

(define (fgetc filedes)
   (integer->char (_fgetc filedes)))

Note: To illustrate the default type compilation of extern function, we have voluntary introduced an incomplete declaration for the fclose function. This will make Bigloo to produce a warning when compiling that module.

The very dangerous ``pragma'' Bigloo special forms

Bigloo has a special form which allows the inclusion of C text into the produced code. It is only applicable to the C back-end. In particular, the JVM back-end (see Chapter Java Interface) does not support it.

pragma::ident string [args]bigloo syntax

free-pragma::ident string [args]bigloo syntax

pragma::ident identbigloo syntax

This force Bigloo to include string in the produced C code as a regular C fragment of code. This form must not be used without an in depth understanding of Bigloo C code production; with unskilled use, the produced C file may be unacceptable to the C compiler.

Values can be passed to a pragma form, being referenced in string by expressions of the form $number. Such expression are replaced by the corresponding values, the number of referenced values in string being exactly the number of values provided. Here is an example of pragma usage:

(define (fibo x::long)
   (pragma "printf( \"fib(%d):%d\\n\", $1, $2 );" 
           x 
           (fib x)))

Arguments provided to a pragma form are not converted during compilation. Hence, pragma arguments can be of any types, including, foreign types.

A pragma result type can be specified using the notation pragma::name where the default type is unspecified. Then, for instance, the expression (pragma::bool "$1 == 0" x) will be considered to be returning a object of type bool (C boolean) while the expression (pragma "$1 == 0" x) will be considered by Bigloo to be returning the unspecified typed object.

The compiler assumes that a pragma forms operates a side effects and that it writes into its parameters. This assumption no long holds with free-pragma. This is the only difference between the two forms.

The last form pragma ident enables ``injecting'' a Scheme mangled identifier into the generated C code. Example:

(let ((x/y 3))
  (pragma "$1 = BINT( 24 )" (pragma x/y))
  (print x/y))

Name mangling

In order to avoid name clashes, Bigloo uses name mangling when compiling to C or to Jvm. The name mangling for a Scheme identifier may be overridden by the means of an extern export clause (see Section Exporting a Scheme variable).

Four public functions may be used to mangle and to demangle Scheme identifiers:

bigloo-mangle stringbigloo procedure

Mangle the identifier string.

bigloo-module-mangle string1 string2bigloo procedure

Mangle the identifier string1 that belongs to module string2.

bigloo-mangled? stringbigloo procedure

Returns #t if string has been computed by the bigloo-mangle or bigloo-module-mangle function.

bigloo-class-mangled? stringbigloo procedure

Returns #t if string is a mangled name of a Bigloo class.

bigloo-need-mangling stringbigloo procedure

Returns #t if string requires name mangling because it is not a C or Jvm valid identifier.

bigloo-demangle stringbigloo procedure

Demangle previously mangled identifiers:

(let ((id "foo!")
      (module "a-module"))
   (let ((mangled (bigloo-module-mangle id module)))
      (multiple-value-bind (new-id new-module)
         (bigloo-demangle mangled)
         (and (string=? id new-id) (string=? module new-module)))))
   ⇒ #t

bigloo-class-demangle stringbigloo procedure

Demangle previously mangled class identifier.

Embedded Bigloo applications

It is possible to design and realize embedded Bigloo applications. This facility is useful for adding a new Scheme part to an already existing C program. The C part of the program has only to enter the Bigloo initialization, hence, it can call any Bigloo function.

Normally, Bigloo creates an initialization function called main when it reads a main module clause. To use an embedded Bigloo program, such an initialization function would have to be created but with a different name. Changing the name can be be done using the following Bigloo option: -copt "-DBIGLOO_MAIN=<new-name>". To prevent exit from the program after <new-name> is executed, the following Bigloo option must be used: -copt "-DBIGLOO_EXIT='BUNSPEC,'".

A very important part of designing embedded Bigloo programs is being sure that all used Bigloo modules are correctly initialized and the normal way to initialize them is to use with clauses in the module which contains the main clause.

An example of an embedded program can be found in the distribution's examples directory.

Using C bindings within the interpreter

To be able to get access to foreign functions within the Bigloo interpreter, some extra measurements have to be taken. The foreign functions have to be present in the interpreter binary, which means you have to compile a custom interpreter. Fortunately, this is easy. What has to be done is to wrap the foreign functions within Scheme and make an interpreter module.

Let us consider an example where a C function get_system_time returning and int is used in an interpreter. (When linking, be sure to add the .o file containing the get_system_time.)

The ffi-interpreter.scm file:

(module ExtendendInterpreter
   (import (wrapper "wrapper.scm"))
   (main main))

(define (main argv)
   (repl))

The wrapper.scm file:

(module wrapper
   (extern (macro %get-system-time::int () "get_system_time"))
   (export (get-system-time))
   (eval (export-exports))

(define (get-system-time)
  (%get-system-time))

Compile and link your application with something like:

cc gettime.c -c gettime.o
bigloo wrapper.scm -c
bigloo ffi-interpreter.scm wrapper.o gettime.o