<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="generator" content="AsciiDoc 8.6.10">
<title>ForeignFunctionInterfaceSyntax</title>
<link rel="stylesheet" href="./asciidoc.css" type="text/css">
<link rel="stylesheet" href="./pygments.css" type="text/css">


<script type="text/javascript" src="./asciidoc.js"></script>
<script type="text/javascript">
/*<![CDATA[*/
asciidoc.install();
/*]]>*/
</script>
<link rel="stylesheet" href="./mlton.css" type="text/css">
</head>
<body class="article">
<div id="banner">
<div id="banner-home">
<a href="./Home">MLton 20201002</a>
</div>
</div>
<div id="header">
<h1>ForeignFunctionInterfaceSyntax</h1>
</div>
<div id="content">
<div id="preamble">
<div class="sectionbody">
<div class="paragraph"><p>MLton extends the syntax of SML with expressions that enable a
<a href="ForeignFunctionInterface">ForeignFunctionInterface</a> to C.  The following description of the
syntax uses some abbreviations.</p></div>
<table class="tableblock frame-all grid-all"
style="
width:100%;
">
<col style="width:33%;">
<col style="width:33%;">
<col style="width:33%;">
<thead>
<tr>
<th class="tableblock halign-left valign-top" > C base type </th>
<th class="tableblock halign-left valign-top" > <em>cBaseTy</em> </th>
<th class="tableblock halign-left valign-top" > <a href="ForeignFunctionInterfaceTypes"> Foreign Function Interface types</a></th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top" ><p class="tableblock">C argument type</p></td>
<td class="tableblock halign-left valign-top" ><p class="tableblock"><em>cArgTy</em></p></td>
<td class="tableblock halign-left valign-top" ><p class="tableblock"><em>cBaseTy</em><sub>1</sub> <span class="monospaced">*</span> &#8230; <span class="monospaced">*</span> <em>cBaseTy</em><sub>n</sub> or <span class="monospaced">unit</span></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top" ><p class="tableblock">C return type</p></td>
<td class="tableblock halign-left valign-top" ><p class="tableblock"><em>cRetTy</em></p></td>
<td class="tableblock halign-left valign-top" ><p class="tableblock"><em>cBaseTy</em> or <span class="monospaced">unit</span></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top" ><p class="tableblock">C function type</p></td>
<td class="tableblock halign-left valign-top" ><p class="tableblock"><em>cFuncTy</em></p></td>
<td class="tableblock halign-left valign-top" ><p class="tableblock"><em>cArgTy</em> <span class="monospaced">-&gt;</span> <em>cRetTy</em></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top" ><p class="tableblock">C pointer type</p></td>
<td class="tableblock halign-left valign-top" ><p class="tableblock"><em>cPtrTy</em></p></td>
<td class="tableblock halign-left valign-top" ><p class="tableblock"><span class="monospaced">MLton.Pointer.t</span></p></td>
</tr>
</tbody>
</table>
<div class="paragraph"><p>The type annotation and the semicolon are not optional in the syntax
of <a href="ForeignFunctionInterface">ForeignFunctionInterface</a> 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.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_address">Address</h2>
<div class="sectionbody">
<div class="listingblock">
<div class="content monospaced">
<pre>_address "CFunctionOrVariableName" attr... : cPtrTy;</pre>
</div></div>
<div class="paragraph"><p>Denotes the address of the C function or variable.</p></div>
<div class="paragraph"><p><span class="monospaced">attr...</span> denotes a (possibly empty) sequence of attributes.  The following attributes are recognized:</p></div>
<div class="ulist"><ul>
<li>
<p>
<span class="monospaced">external</span> : import with external symbol scope (see <a href="LibrarySupport">LibrarySupport</a>) (default).
</p>
</li>
<li>
<p>
<span class="monospaced">private</span> : import with private symbol scope (see <a href="LibrarySupport">LibrarySupport</a>).
</p>
</li>
<li>
<p>
<span class="monospaced">public</span> : import with public symbol scope (see <a href="LibrarySupport">LibrarySupport</a>).
</p>
</li>
</ul></div>
<div class="paragraph"><p>See <a href="MLtonPointer"> MLtonPointer</a> for functions that manipulate C pointers.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_symbol">Symbol</h2>
<div class="sectionbody">
<div class="listingblock">
<div class="content monospaced">
<pre>_symbol "CVariableName" attr... : (unit -&gt; cBaseTy) * (cBaseTy -&gt; unit);</pre>
</div></div>
<div class="paragraph"><p>Denotes the <em>getter</em> and <em>setter</em> for a C variable.  The <em>cBaseTy</em>s
must be identical.</p></div>
<div class="paragraph"><p><span class="monospaced">attr...</span> denotes a (possibly empty) sequence of attributes.  The following attributes are recognized:</p></div>
<div class="ulist"><ul>
<li>
<p>
<span class="monospaced">alloc</span> : allocate storage (and export a symbol) for the C variable.
</p>
</li>
<li>
<p>
<span class="monospaced">external</span> : import or export with external symbol scope (see <a href="LibrarySupport">LibrarySupport</a>) (default if not <span class="monospaced">alloc</span>).
</p>
</li>
<li>
<p>
<span class="monospaced">private</span> : import or export with private symbol scope (see <a href="LibrarySupport">LibrarySupport</a>).
</p>
</li>
<li>
<p>
<span class="monospaced">public</span> : import or export with public symbol scope (see <a href="LibrarySupport">LibrarySupport</a>) (default if <span class="monospaced">alloc</span>).
</p>
</li>
</ul></div>
<div class="listingblock">
<div class="content monospaced">
<pre>_symbol * : cPtrTy -&gt; (unit -&gt; cBaseTy) * (cBaseTy -&gt; unit);</pre>
</div></div>
<div class="paragraph"><p>Denotes the <em>getter</em> and <em>setter</em> for a C pointer to a variable.
The <em>cBaseTy</em>s must be identical.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_import">Import</h2>
<div class="sectionbody">
<div class="listingblock">
<div class="content monospaced">
<pre>_import "CFunctionName" attr... : cFuncTy;</pre>
</div></div>
<div class="paragraph"><p>Denotes an SML function whose behavior is implemented by calling the C
function.  See <a href="CallingFromSMLToC"> Calling from SML to C</a> for more
details.</p></div>
<div class="paragraph"><p><span class="monospaced">attr...</span> denotes a (possibly empty) sequence of attributes.  The following attributes are recognized:</p></div>
<div class="ulist"><ul>
<li>
<p>
<span class="monospaced">cdecl</span> : call with the <span class="monospaced">cdecl</span> calling convention (default).
</p>
</li>
<li>
<p>
<span class="monospaced">external</span> : import with external symbol scope (see <a href="LibrarySupport">LibrarySupport</a>) (default).
</p>
</li>
<li>
<p>
<span class="monospaced">impure</span>: assert that the function depends upon state and/or performs side effects (default).
</p>
</li>
<li>
<p>
<span class="monospaced">private</span> : import with private symbol scope (see <a href="LibrarySupport">LibrarySupport</a>).
</p>
</li>
<li>
<p>
<span class="monospaced">public</span> : import with public symbol scope (see <a href="LibrarySupport">LibrarySupport</a>).
</p>
</li>
<li>
<p>
<span class="monospaced">pure</span>: assert that the function does not depend upon state or perform any side effects; such functions are subject to various optimizations (e.g., <a href="CommonSubexp">CommonSubexp</a>, <a href="RemoveUnused">RemoveUnused</a>)
</p>
</li>
<li>
<p>
<span class="monospaced">reentrant</span>: assert that the function (directly or indirectly) calls an <span class="monospaced">_export</span>-ed SML function.
</p>
</li>
<li>
<p>
<span class="monospaced">stdcall</span> : call with the <span class="monospaced">stdcall</span> calling convention (ignored except on Cygwin and MinGW).
</p>
</li>
</ul></div>
<div class="listingblock">
<div class="content monospaced">
<pre>_import * attr... : cPtrTy -&gt; cFuncTy;</pre>
</div></div>
<div class="paragraph"><p>Denotes an SML function whose behavior is implemented by calling a C
function through a C function pointer.</p></div>
<div class="paragraph"><p><span class="monospaced">attr...</span> denotes a (possibly empty) sequence of attributes.  The following attributes are recognized:</p></div>
<div class="ulist"><ul>
<li>
<p>
<span class="monospaced">cdecl</span> : call with the <span class="monospaced">cdecl</span> calling convention (default).
</p>
</li>
<li>
<p>
<span class="monospaced">impure</span>: assert that the function depends upon state and/or performs side effects (default).
</p>
</li>
<li>
<p>
<span class="monospaced">pure</span>: assert that the function does not depend upon state or perform any side effects; such functions are subject to various optimizations (e.g., <a href="CommonSubexp">CommonSubexp</a>, <a href="RemoveUnused">RemoveUnused</a>)
</p>
</li>
<li>
<p>
<span class="monospaced">reentrant</span>: assert that the function (directly or indirectly) calls an <span class="monospaced">_export</span>-ed SML function.
</p>
</li>
<li>
<p>
<span class="monospaced">stdcall</span> : call with the <span class="monospaced">stdcall</span> calling convention (ignored except on Cygwin and MinGW).
</p>
</li>
</ul></div>
<div class="paragraph"><p>See
<a href="CallingFromSMLToCFunctionPointer"> Calling from SML to C function pointer</a>
for more details.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_export">Export</h2>
<div class="sectionbody">
<div class="listingblock">
<div class="content monospaced">
<pre>_export "CFunctionName" attr... : cFuncTy -&gt; unit;</pre>
</div></div>
<div class="paragraph"><p>Exports a C function with the name <span class="monospaced">CFunctionName</span> that can be used to
call an SML function of the type <em>cFuncTy</em>. When the function denoted
by the export expression is applied to an SML function <span class="monospaced">f</span>, subsequent
C calls to <span class="monospaced">CFunctionName</span> will call <span class="monospaced">f</span>.  It is an error to call
<span class="monospaced">CFunctionName</span> before the export has been applied.  The export may be
applied more than once, with each application replacing any previous
definition of <span class="monospaced">CFunctionName</span>.</p></div>
<div class="paragraph"><p><span class="monospaced">attr...</span> denotes a (possibly empty) sequence of attributes.  The following attributes are recognized:</p></div>
<div class="ulist"><ul>
<li>
<p>
<span class="monospaced">cdecl</span> : call with the <span class="monospaced">cdecl</span> calling convention (default).
</p>
</li>
<li>
<p>
<span class="monospaced">private</span> : export with private symbol scope (see <a href="LibrarySupport">LibrarySupport</a>).
</p>
</li>
<li>
<p>
<span class="monospaced">public</span> : export with public symbol scope (see <a href="LibrarySupport">LibrarySupport</a>) (default).
</p>
</li>
<li>
<p>
<span class="monospaced">stdcall</span> : call with the <span class="monospaced">stdcall</span> calling convention (ignored except on Cygwin and MinGW).
</p>
</li>
</ul></div>
<div class="paragraph"><p>See <a href="CallingFromCToSML"> Calling from C to SML</a> for more details.</p></div>
</div>
</div>
</div>
<div id="footnotes"><hr></div>
<div id="footer">
<div id="footer-text">
</div>
<div id="footer-badges">
</div>
</div>
</body>
</html>
