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 -default-ann 'allowExport true, allowImport true' -stop o ffi-import.c
mlton -default-ann 'allowExport true, allowImport true' import.sml ffi-import.o
% import
13
success
6.1.1 Indirect function calls
It is also possibe to make indirect function calls; that is, function
calls through a function pointer. Suppose that you would like to
indirectly call the C function foo described above; MLton
extends the syntax of SML to allow expressions like the following:
_import * : MLton.Pointer.t -> real * char -> int;
This expression denotes a function of type MLton.Pointer.t -> real
* char -> int whose behavior is implemented by calling the C function
at the address denoted by the MLton.Pointer.t argument.
The general form of an indirect _import
expresion is:
_import * attribute ...: ty;
The semicolon is not optional. ty must be a function type of the form
MLton.Pointer.t -> ty1 * ... * tyn -> tyr
n can be zero, in which case the expression denotes the indirect
call of an argumentless C function.
An example in the examples/ffi directory demonstrates the use of
indirect _import expressions. The example demonstrates how to call
functions from a dynamic library.
% make iimport
mlton -default-ann 'allowExport true' -default-ann 'allowImport true' -link-opt '-ldl' iimport.sml
% iimport
Math.cos(2.0) = ~0.416146836547
libm.so::cos(2.0) = ~0.416146836547
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, which are 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 -default-ann 'allowExport true' -default-ann 'allowImport true' -export-header export.h -stop tc export.sml
gcc -c ffi-export.c
mlton -default-ann 'allowExport true' -default-ann 'allowImport true' 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 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 10.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 |
Int8 |
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.