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.
| 28.1 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.
| 28.1.1 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.
 
| 28.1.2 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)
 | 
 
| 28.1.3 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)))
 | 
 
| 28.1.4 Including an extern file
 | 
C files can be included in the C code produced by using
<include-clause>.
| <include-clause> ==> (include<string>) | 
 
| 28.1.5 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 ...))
 | 
 
| 28.1.6 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.
28.1.6.1 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> ==> objprocedure|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> ==>cobjchar|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.
 
28.1.6.2 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::type1name1)
           ...
           (idn::typennamen)) | 
The following functions are created:
- A creator: 
| (struct*::struct* ::type_1... ::type_n) |  
 This function allocates a freshstruct*(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*?::boolobj::obj) |  
 This function returns#tif and only if the argumentobjis of typestruct*.
 
 
- A null checker: 
| (struct*-null?::bool ::struct*) |  
 This function returns#tif and only if its argument isNull.
 
 
- A null creator: 
| (make-null-struct::struct*) |  
 This function creates aNULLvalue of typestruct*.
 
 
- An equality checker: 
| (=struct*?::bool ::struct* ::struct*) |  
 This function returns#tif 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))))
 | 
 
28.1.6.3 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(pointerident) ...) | 
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: 
This function allocates memory for nbelements of typeidentand returns aptrto this zone. The memory is filled with
the CNullvalue.
 
 
- A type checker: 
This function returns #tthe argumentobjis of typeptrand#fotherwise.
 
 
- A null checker: 
This function returns #tif its argument isNulland#fotherwise.
 
 
- A null creator: 
This function creates a NULLvalue of typeptr*.
 
 
- An equality checker: 
| (=ptr*?::bool ::ptr* ::ptr*) |  
 This function returns#tif its arguments are equal and#fotherwise.
 
 
- 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)))
 | 
 
28.1.6.4 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? string | bigloo procedure |  
These two predicates checks if there argument is the C| void*-null? void* | bigloo procedure |  NULLvalue. | 
| 
| make-string-ptr-null | bigloo procedure |  
These two constructors creates null foreign values.| make-void*-null | bigloo procedure |  | 
 
28.1.6.5 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(arrayident) ...) | 
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: 
This function allocates memory for the array array.
The memory is filled with the CNullvalue.
 
 
- A type checker: 
This function returns #tif the argumentobjis of type 
array and#fotherwise.
 
 
- A null checker: 
| (null-array?::bool ::array) |  
 This function returns#tif the argumentobjisNulland#fotherwise.
 
 
- An equality checker: 
| (=array*?::bool ::array* ::array*) |  
 This function returns#tif its arguments are equal and#fotherwise.
 
 
- 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)))
 | 
 
28.1.6.6 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(functionres(arg*)) ...) | 
Bigloo creates the following functions:
- A type checker: 
This function returns #tif the argumentobjis of typefunand#fotherwise.
 
 
- An equality checker: 
| (=fun*?::bool ::fun* ::fun*) |  
 This function returns#tif and only if its arguments are equal.
 
 
- Caller: 
| (fun-call::resf::funa::ta...) |  
 This function invokesfwith the argumentsa...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"))
 | 
 
28.1.6.7 C enums
This form defines 
enum types.
| <enum-type> ==> (enum (<ident> <string>)......) | 
Let us suppose the type: 
| (type enum(enum (id_1name_1)
         ...
         (id_nname_n))) | 
Bigloo creates the following functions:
- Creators: 
| (enum-id_1::enum)
...
(enum-id_n::enum) |  
 These functions createenumvalues.
 
 
- A type checker: 
This function returns #tif the argumentobjis of typeenumand#fotherwise.
 
 
- An equality checker: 
| (=enum?::bool ::enum::enum) |  
 This function returns#tif the arguments are equal and#fotherwise.
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)))
 | 
 
28.1.6.8 C opaques
This form defines 
opaque types.
| <opaque-type> ==> (opaque) | 
Let us suppose the type:
Bigloo creates the following functions:
- A type checker: 
This function returns #tif the argumentobjis of typeopaand#fotherwise.
 
 
- An equality checker: 
| (=opa?::bool ::opa::opa) |  
 This function returns#tif the arguments 
are equal and#fotherwise.
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.
 
 
 
| 28.2 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:: identstring [args] | bigloo syntax |  
| free-pragma:: identstring [args] | bigloo syntax |  
This force Bigloo to include| pragma:: identident | bigloo syntax |  stringin 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
 pragmaform, being
referenced instringby expressions of the form$.
Such expression are replaced by the corresponding
values, the number of referenced values innumberstringbeing exactly the number of values provided. Here is an example
ofpragmausage:
 
 
Arguments provided to a pragma form are not converted during compilation.
Hence, pragma arguments can be of any types, including, foreign types.| (define (fibo x::long)
   (pragma "printf( \"fib(%d):%d\\n\", $1, $2 );" 
           x 
           (fib x)))
 |  
 A pragma result type can be specified using the notation
 pragma::where the default type isnameunspecified. Then,
for instance, the expression(pragma::bool "$1 == 0" x)will
be considered to be returning a object of typebool(C boolean) while
the expression(pragma "$1 == 0" x)will be considered by
Bigloo to be returning theunspecifiedtyped object.
 The compiler assumes that a
 pragmaforms operates a side effects
and that it writes into its parameters. This assumption no long holds
withfree-pragma. This is the only difference between the two
forms.
 The last form
 pragma enables ``injecting'' a Scheme
mangled identifier into the generated C code. Example:ident
 
 
| (let ((x/y 3))
  (pragma "$1 = BINT( 24 )" (pragma x/y))
  (print x/y))
 |  | 
 
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:
| 
Mangle the identifier| bigloo-mangle string | bigloo procedure |  string. | 
| 
Mangle the identifier| bigloo-module-mangle string1 string2 | bigloo procedure |  string1that belongs to modulestring2. | 
| 
Returns| bigloo-mangled? string | bigloo procedure |  #tifstringhas been computed by thebigloo-mangleorbigloo-module-manglefunction. | 
| 
Returns| bigloo-class-mangled? string | bigloo procedure |  #tifstringis a mangled name of a Bigloo class. | 
| 
Returns| bigloo-need-mangling string | bigloo procedure |  #tifstringrequires name mangling because it
is not a C or Jvm valid identifier. | 
| 
Demangle previously mangled identifiers:| bigloo-demangle string | bigloo procedure |  
 
 
| (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
 |  | 
| 
Demangle previously mangled class identifier.| bigloo-class-demangle string | bigloo procedure |  | 
 
| 28.4 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.
 
| 28.5 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
 |