ForeignFunctionInterfaceSyntax
==============================

MLton extends the syntax of SML with expressions that enable a
<:ForeignFunctionInterface:> to C.  The following description of the
syntax uses some abbreviations.

[options="header"]
|====
| C base type | _cBaseTy_ | <:ForeignFunctionInterfaceTypes: Foreign Function Interface types>
| C argument type | _cArgTy_ | _cBaseTy_~1~ `*` ... `*` _cBaseTy_~n~ or `unit`
| C return type | _cRetTy_ | _cBaseTy_ or `unit`
| C function type | _cFuncTy_ | _cArgTy_ `->` _cRetTy_
| C pointer type | _cPtrTy_ | `MLton.Pointer.t`
|====

The type annotation and the semicolon are not optional in the syntax
of <:ForeignFunctionInterface:> expressions.  However, the type is
lexed, parsed, and elaborated as an SML type, so any type (including
type abbreviations) may be used, so long as it elaborates to a type of
the correct form.


== Address ==

----
_address "CFunctionOrVariableName" attr... : cPtrTy;
----

Denotes the address of the C function or variable.

`attr...` denotes a (possibly empty) sequence of attributes.  The following attributes are recognized:

* `external` : import with external symbol scope (see <:LibrarySupport:>) (default).
* `private` : import with private symbol scope (see <:LibrarySupport:>).
* `public` : import with public symbol scope (see <:LibrarySupport:>).

See <:MLtonPointer: MLtonPointer> for functions that manipulate C pointers.


== Symbol ==

----
_symbol "CVariableName" attr... : (unit -> cBaseTy) * (cBaseTy -> unit);
----

Denotes the _getter_ and _setter_ for a C variable.  The __cBaseTy__s
must be identical.

`attr...` denotes a (possibly empty) sequence of attributes.  The following attributes are recognized:

* `alloc` : allocate storage (and export a symbol) for the C variable.
* `external` : import or export with external symbol scope (see <:LibrarySupport:>) (default if not `alloc`).
* `private` : import or export with private symbol scope (see <:LibrarySupport:>).
* `public` : import or export with public symbol scope (see <:LibrarySupport:>) (default if `alloc`).


----
_symbol * : cPtrTy -> (unit -> cBaseTy) * (cBaseTy -> unit);
----

Denotes the _getter_ and _setter_ for a C pointer to a variable.
The __cBaseTy__s must be identical.


== Import ==

----
_import "CFunctionName" attr... : cFuncTy;
----

Denotes an SML function whose behavior is implemented by calling the C
function.  See <:CallingFromSMLToC: Calling from SML to C> for more
details.

`attr...` denotes a (possibly empty) sequence of attributes.  The following attributes are recognized:

* `cdecl` : call with the `cdecl` calling convention (default).
* `external` : import with external symbol scope (see <:LibrarySupport:>) (default).
* `impure`: assert that the function depends upon state and/or performs side effects (default).
* `private` : import with private symbol scope (see <:LibrarySupport:>).
* `public` : import with public symbol scope (see <:LibrarySupport:>).
* `pure`: assert that the function does not depend upon state or perform any side effects; such functions are subject to various optimizations (e.g., <:CommonSubexp:>, <:RemoveUnused:>)
* `reentrant`: assert that the function (directly or indirectly) calls an `_export`-ed SML function.
* `stdcall` : call with the `stdcall` calling convention (ignored except on Cygwin and MinGW).


----
_import * attr... : cPtrTy -> cFuncTy;
----

Denotes an SML function whose behavior is implemented by calling a C
function through a C function pointer.

`attr...` denotes a (possibly empty) sequence of attributes.  The following attributes are recognized:

* `cdecl` : call with the `cdecl` calling convention (default).
* `impure`: assert that the function depends upon state and/or performs side effects (default).
* `pure`: assert that the function does not depend upon state or perform any side effects; such functions are subject to various optimizations (e.g., <:CommonSubexp:>, <:RemoveUnused:>)
* `reentrant`: assert that the function (directly or indirectly) calls an `_export`-ed SML function.
* `stdcall` : call with the `stdcall` calling convention (ignored except on Cygwin and MinGW).

See
<:CallingFromSMLToCFunctionPointer: Calling from SML to C function pointer>
for more details.


== Export ==

----
_export "CFunctionName" attr... : cFuncTy -> unit;
----

Exports a C function with the name `CFunctionName` that can be used to
call an SML function of the type _cFuncTy_. When the function denoted
by the export expression is applied to an SML function `f`, subsequent
C calls to `CFunctionName` will call `f`.  It is an error to call
`CFunctionName` before the export has been applied.  The export may be
applied more than once, with each application replacing any previous
definition of `CFunctionName`.

`attr...` denotes a (possibly empty) sequence of attributes.  The following attributes are recognized:

* `cdecl` : call with the `cdecl` calling convention (default).
* `private` : export with private symbol scope (see <:LibrarySupport:>).
* `public` : export with public symbol scope (see <:LibrarySupport:>) (default).
* `stdcall` : call with the `stdcall` calling convention (ignored except on Cygwin and MinGW).

See <:CallingFromCToSML: Calling from C to SML> for more details.
