5 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.
5.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
5.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 expression both exports and
defines foo.
_export "foo": real * char -> int;
(fn (x, c) => 13 + Real.floor x + Char.ord c)
MLton's -export-header true 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 true export.sml >export.h
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.
5.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.
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 true 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 |
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.