Previous Up Next

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 typedefs 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 typedefs 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.
Previous Up Next