## 6 Foreign function interface (FFI)

MLton's FFI is not part of Standard ML and it is quite possible that this interface will change. That having been said, with MLton it is easy to access C global variables and to make calls from SML to C and from C to SML, at least when dealing with simple types like `char`, `int`, `real`, and `word`.

### 6.1 Calling from SML to C

Suppose you would like to import from C a function with the following prototype:

    int foo (double d, unsigned char c);

MLton extends the syntax of SML to allow expressions like the following:

    _import "foo": real * char -> int;

This expression denotes a function of type `real * char -> int` whose behavior is implemented by calling the C function whose name is `foo`. Thinking in terms of C, imagine that there are C variables `d` of type `double`, `c` of type `unsigned char`, and `i` of type `int`. Then, the C statement `i = foo (d, c)` is executed and `i` is returned.
The general form of an `_import` expresion is:
`_import "`C global variable or function name`"` attribute ...`:` ty`;`
The semicolon is not optional.
The function name is followed by a (possibly empty) sequence of attributes, analogous to C `__attribute__` specifiers. For now, the only attributes supported are `cdecl` and `stdcall`. These specify the calling convention of the C function on Cygwin/Windows, and are ignored on all other platforms. The default is `cdecl`. You must use `stdcall` in order to correctly call Windows API functions.
An example in the `examples/ffi` directory demonstrates the use of `_import` expressions. The `Makefile` demonstrates how to call MLton to include and link with the appropriate files. Running `make import` will produce an executable, `import`, that should output `success` when run.

    % make import
    mlton -stop o ffi-import.c
    mlton import.sml ffi-import.o
    % import
    13
    success

### 6.2 Calling from C to SML

Suppose you would like export from SML a function of type `real * char -> int` as the C function `foo`. MLton extends the syntax of SML to allow expressions like the following:

    _export "foo": real * char -> int;

As with `_import`, a sequence of attributes may follow the function name. The above expression exports a C function named `foo`, with prototype

    Int32 foo (Real64 x0, Char x1);

The `_export` expression denotes a function of type `(real * char -> int) -> unit`, that when called with a function `f` arranges for the exported `foo` function to call `f` when `foo` is called. So, for example, the following exports and defines `foo`.

    val e = _export "foo": real * char -> int;
    val _ = e (fn (x, c) => 13 + Real.floor x + Char.ord c)

MLton's `-export-header` option generates a C header file with prototypes for all of the functions exported from SML. Include this header file in your C files to type check calls to functions exported from SML. This header file includes `typedef`s for the types that can be passed between SML and C, as described in the next section. An example in the `examples/ffi` directory demonstrates the use of `_export` expressions and generating the header file. Running `make export` will produce an executable, `export`, that should output `success` when run.

    % make export
    mlton -export-header export.h -stop tc export.sml
    gcc -c ffi-export.c
    mlton export.sml ffi-export.o
    % ./export
    g starting
    ...
    g4 (0)
    success

Notice that `ffi-export.c` includes `export.h`, the header file generated by MLton.

### 6.3 FFI types

MLton only allows a values of certain SML types to be passed between SML and C. The following types are allowed: `bool`, `char`, `int`, `real`, `string`, `word`. Strings are not null terminated, unless you manually do so from the SML side. All of the different sizes of (fixed-sized) integers, reals, and words are supported as well: `Int8.int`, `Int16.int`, `Int32.int`, `Int64.int`, `Real32.real`, `Real64.real`, `Word8.word`, `Word16.word`, `Word32.word`, `Word64.word`. There is a special type, `MLton.Pointer.t`, for passing C pointers -- see Section 9.2.12 for details.
Arrays, refs, and vectors of the above types are also allowed. Because in MLton monomorphic arrays and vectors are exactly the same as their polymorphic counterpart, these are also allowed. Unfortunately, passing tuples or datatypes is not allowed because that would interfere with representation optimizations.
The C header file that `-export-header` generates includes `typedef`s for the C types corresponding to the SML types. Here is the mapping between SML types and C types.

SML type | C typedef | C type
`array` | `Pointer` | `char *`
`bool` | `Int32` | `long`
`char` | `Word8` | `unsigned char`
`Int8.int` | `Int8` | `char`
`Int16.int` | `Int16` | `short`
`Int32.int` | `Int32` | `long`
`Int64.int` | `Int64` | `long long`
`int` | `Int32` | `long`
`MLton.Pointer.t` | `Pointer` | `char *`
`Real32.real` | `Real32` | `float`
`Real64.real` | `Real64` | `double`
`real` | `Real64` | `double`
`ref` | `Pointer` | `char *`
`string` | `Pointer` | `char *`
`vector` | `Pointer` | `char *`
`Word8.word` | `Word8` | `unsigned char`
`Word16.word` | `Word16` | `unsigned short`
`Word32.word` | `Word32` | `unsigned long`
`Word64.word` | `Word64` | `unsigned long long`
`word` | `Word32` | `unsigned int`

Although the C type of an array, ref, or vector is always `Pointer`, in reality, the object is layed out in the natural C representation. Your C code should cast to the appropriate C type if you want to keep the C compiler from complaining.