1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207
|
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="generator" content="AsciiDoc 8.6.8">
<title>CallingFromCToSML</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 20130715</a>
</div>
</div>
<div id="header">
<h1>CallingFromCToSML</h1>
</div>
<div id="content">
<div id="preamble">
<div class="sectionbody">
<div class="paragraph"><p>MLton’s <a href="ForeignFunctionInterface">ForeignFunctionInterface</a> allows programs to <em>export</em> SML
functions to be called from C. Suppose you would like export from SML
a function of type <span class="monospaced">real * char -> int</span> as the C function <span class="monospaced">foo</span>.
MLton extends the syntax of SML to allow expressions like the
following:</p></div>
<div class="listingblock">
<div class="content monospaced">
<pre>_export "foo": (real * char -> int) -> unit;</pre>
</div></div>
<div class="paragraph"><p>The above expression exports a C function named <span class="monospaced">foo</span>, with
prototype</p></div>
<div class="listingblock">
<div class="content"><div class="highlight"><pre><span class="n">Int32</span> <span class="n">foo</span> <span class="p">(</span><span class="n">Real64</span> <span class="n">x0</span><span class="p">,</span> <span class="n">Char</span> <span class="n">x1</span><span class="p">);</span>
</pre></div></div></div>
<div class="paragraph"><p>The <span class="monospaced">_export</span> expression denotes a function of type
<span class="monospaced">(real * char -> int) -> unit</span> that when called with a function
<span class="monospaced">f</span>, arranges for the exported <span class="monospaced">foo</span> function to call <span class="monospaced">f</span>
when <span class="monospaced">foo</span> is called. So, for example, the following exports and
defines <span class="monospaced">foo</span>.</p></div>
<div class="listingblock">
<div class="content"><div class="highlight"><pre><span class="k">val</span><span class="w"> </span><span class="n">e</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">_</span><span class="n">export</span><span class="w"> </span><span class="s">"foo"</span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="n">real</span><span class="w"> </span><span class="n">*</span><span class="w"> </span><span class="n">char</span><span class="w"> </span><span class="p">-></span><span class="w"> </span><span class="n">int</span><span class="p">)</span><span class="w"> </span><span class="p">-></span><span class="w"> </span><span class="n">unit</span><span class="p">;</span><span class="w"></span>
<span class="k">val</span><span class="w"> </span><span class="p">_</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">e</span><span class="w"> </span><span class="p">(</span><span class="k">fn</span><span class="w"> </span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="n">c</span><span class="p">)</span><span class="w"> </span><span class="p">=></span><span class="w"> </span><span class="mi">13</span><span class="w"> </span><span class="n">+</span><span class="w"> </span><span class="n">Real</span><span class="p">.</span><span class="n">floor</span><span class="w"> </span><span class="n">x</span><span class="w"> </span><span class="n">+</span><span class="w"> </span><span class="n">Char</span><span class="p">.</span><span class="n">ord</span><span class="w"> </span><span class="n">c</span><span class="p">)</span><span class="w"></span>
</pre></div></div></div>
<div class="paragraph"><p>The general form of an <span class="monospaced">_export</span> expression is</p></div>
<div class="listingblock">
<div class="content monospaced">
<pre>_export "C function name" attr... : cFuncTy -> unit;</pre>
</div></div>
<div class="paragraph"><p>The type and the semicolon are not optional. As with <span class="monospaced">_import</span>, a
sequence of attributes may follow the function name.</p></div>
<div class="paragraph"><p>MLton’s <span class="monospaced">-export-header</span> 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 <span class="monospaced">typedef</span>s for the
<a href="ForeignFunctionInterfaceTypes"> types that can be passed between SML and C</a>.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_example">Example</h2>
<div class="sectionbody">
<div class="paragraph"><p>Suppose that <span class="monospaced">export.sml</span> is</p></div>
<div class="listingblock">
<div class="content"><div class="highlight"><pre><span class="k">val</span><span class="w"> </span><span class="n">e</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">_</span><span class="n">export</span><span class="w"> </span><span class="s">"f"</span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="n">int</span><span class="w"> </span><span class="n">*</span><span class="w"> </span><span class="n">real</span><span class="w"> </span><span class="n">*</span><span class="w"> </span><span class="n">char</span><span class="w"> </span><span class="p">-></span><span class="w"> </span><span class="n">char</span><span class="p">)</span><span class="w"> </span><span class="p">-></span><span class="w"> </span><span class="n">unit</span><span class="p">;</span><span class="w"></span>
<span class="k">val</span><span class="w"> </span><span class="p">_</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">e</span><span class="w"> </span><span class="p">(</span><span class="k">fn</span><span class="w"> </span><span class="p">(</span><span class="n">i</span><span class="p">,</span><span class="w"> </span><span class="n">r</span><span class="p">,</span><span class="w"> </span><span class="p">_)</span><span class="w"> </span><span class="p">=></span><span class="w"></span>
<span class="w"> </span><span class="p">(</span><span class="n">print</span><span class="w"> </span><span class="p">(</span><span class="n">concat</span><span class="w"> </span><span class="p">[</span><span class="s">"i = "</span><span class="p">,</span><span class="w"> </span><span class="n">Int</span><span class="p">.</span><span class="n">toString</span><span class="w"> </span><span class="n">i</span><span class="p">,</span><span class="w"></span>
<span class="w"> </span><span class="s">" r = "</span><span class="p">,</span><span class="w"> </span><span class="n">Real</span><span class="p">.</span><span class="n">toString</span><span class="w"> </span><span class="n">r</span><span class="p">,</span><span class="w"> </span><span class="s">"</span><span class="se">\n</span><span class="s">"</span><span class="p">])</span><span class="w"></span>
<span class="w"> </span><span class="p">;</span><span class="w"> </span><span class="p">#</span><span class="s">"g"</span><span class="p">))</span><span class="w"></span>
<span class="k">val</span><span class="w"> </span><span class="n">g</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">_</span><span class="n">import</span><span class="w"> </span><span class="s">"g"</span><span class="w"> </span><span class="n">public</span><span class="p">:</span><span class="w"> </span><span class="n">unit</span><span class="w"> </span><span class="p">-></span><span class="w"> </span><span class="n">unit</span><span class="p">;</span><span class="w"></span>
<span class="k">val</span><span class="w"> </span><span class="p">_</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">g</span><span class="w"> </span><span class="p">()</span><span class="w"></span>
<span class="k">val</span><span class="w"> </span><span class="p">_</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">g</span><span class="w"> </span><span class="p">()</span><span class="w"></span>
<span class="k">val</span><span class="w"> </span><span class="n">e</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">_</span><span class="n">export</span><span class="w"> </span><span class="s">"f2"</span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="n">Word8</span><span class="p">.</span><span class="n">word</span><span class="w"> </span><span class="p">-></span><span class="w"> </span><span class="n">word</span><span class="w"> </span><span class="n">array</span><span class="p">)</span><span class="w"> </span><span class="p">-></span><span class="w"> </span><span class="n">unit</span><span class="p">;</span><span class="w"></span>
<span class="k">val</span><span class="w"> </span><span class="p">_</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">e</span><span class="w"> </span><span class="p">(</span><span class="k">fn</span><span class="w"> </span><span class="n">w</span><span class="w"> </span><span class="p">=></span><span class="w"></span>
<span class="w"> </span><span class="n">Array</span><span class="p">.</span><span class="n">tabulate</span><span class="w"> </span><span class="p">(</span><span class="mi">10</span><span class="p">,</span><span class="w"> </span><span class="k">fn</span><span class="w"> </span><span class="p">_</span><span class="w"> </span><span class="p">=></span><span class="w"> </span><span class="n">Word</span><span class="p">.</span><span class="n">fromLargeWord</span><span class="w"> </span><span class="p">(</span><span class="n">Word8</span><span class="p">.</span><span class="n">toLargeWord</span><span class="w"> </span><span class="n">w</span><span class="p">)))</span><span class="w"></span>
<span class="k">val</span><span class="w"> </span><span class="n">g2</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">_</span><span class="n">import</span><span class="w"> </span><span class="s">"g2"</span><span class="w"> </span><span class="n">public</span><span class="p">:</span><span class="w"> </span><span class="n">unit</span><span class="w"> </span><span class="p">-></span><span class="w"> </span><span class="n">word</span><span class="w"> </span><span class="n">array</span><span class="p">;</span><span class="w"></span>
<span class="k">val</span><span class="w"> </span><span class="n">a</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">g2</span><span class="w"> </span><span class="p">()</span><span class="w"></span>
<span class="k">val</span><span class="w"> </span><span class="p">_</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">print</span><span class="w"> </span><span class="p">(</span><span class="n">concat</span><span class="w"> </span><span class="p">[</span><span class="s">"0wx"</span><span class="p">,</span><span class="w"> </span><span class="n">Word</span><span class="p">.</span><span class="n">toString</span><span class="w"> </span><span class="p">(</span><span class="n">Array</span><span class="p">.</span><span class="n">sub</span><span class="w"> </span><span class="p">(</span><span class="n">a</span><span class="p">,</span><span class="w"> </span><span class="mi">0</span><span class="p">)),</span><span class="w"> </span><span class="s">"</span><span class="se">\n</span><span class="s">"</span><span class="p">])</span><span class="w"></span>
<span class="k">val</span><span class="w"> </span><span class="n">e</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">_</span><span class="n">export</span><span class="w"> </span><span class="s">"f3"</span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="n">unit</span><span class="w"> </span><span class="p">-></span><span class="w"> </span><span class="n">unit</span><span class="p">)</span><span class="w"> </span><span class="p">-></span><span class="w"> </span><span class="n">unit</span><span class="p">;</span><span class="w"></span>
<span class="k">val</span><span class="w"> </span><span class="p">_</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">e</span><span class="w"> </span><span class="p">(</span><span class="k">fn</span><span class="w"> </span><span class="p">()</span><span class="w"> </span><span class="p">=></span><span class="w"> </span><span class="n">print</span><span class="w"> </span><span class="s">"hello</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span><span class="w"></span>
<span class="k">val</span><span class="w"> </span><span class="n">g3</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">_</span><span class="n">import</span><span class="w"> </span><span class="s">"g3"</span><span class="w"> </span><span class="n">public</span><span class="p">:</span><span class="w"> </span><span class="n">unit</span><span class="w"> </span><span class="p">-></span><span class="w"> </span><span class="n">unit</span><span class="p">;</span><span class="w"></span>
<span class="k">val</span><span class="w"> </span><span class="p">_</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">g3</span><span class="w"> </span><span class="p">()</span><span class="w"></span>
<span class="cm">(* This example demonstrates mutual recursion between C and SML. *)</span><span class="w"></span>
<span class="k">val</span><span class="w"> </span><span class="n">e</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">_</span><span class="n">export</span><span class="w"> </span><span class="s">"f4"</span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="n">int</span><span class="w"> </span><span class="p">-></span><span class="w"> </span><span class="n">unit</span><span class="p">)</span><span class="w"> </span><span class="p">-></span><span class="w"> </span><span class="n">unit</span><span class="p">;</span><span class="w"></span>
<span class="k">val</span><span class="w"> </span><span class="n">g4</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">_</span><span class="n">import</span><span class="w"> </span><span class="s">"g4"</span><span class="w"> </span><span class="n">public</span><span class="p">:</span><span class="w"> </span><span class="n">int</span><span class="w"> </span><span class="p">-></span><span class="w"> </span><span class="n">unit</span><span class="p">;</span><span class="w"></span>
<span class="k">val</span><span class="w"> </span><span class="p">_</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">e</span><span class="w"> </span><span class="p">(</span><span class="k">fn</span><span class="w"> </span><span class="n">i</span><span class="w"> </span><span class="p">=></span><span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="n">i</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mi">0</span><span class="w"> </span><span class="k">then</span><span class="w"> </span><span class="p">()</span><span class="w"> </span><span class="k">else</span><span class="w"> </span><span class="n">g4</span><span class="w"> </span><span class="p">(</span><span class="n">i</span><span class="w"> </span><span class="n">-</span><span class="w"> </span><span class="mi">1</span><span class="p">))</span><span class="w"></span>
<span class="k">val</span><span class="w"> </span><span class="p">_</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">g4</span><span class="w"> </span><span class="mi">13</span><span class="w"></span>
<span class="k">val</span><span class="w"> </span><span class="p">(_,</span><span class="w"> </span><span class="n">zzzSet</span><span class="p">)</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">_</span><span class="n">symbol</span><span class="w"> </span><span class="s">"zzz"</span><span class="w"> </span><span class="n">alloc</span><span class="p">:</span><span class="w"> </span><span class="p">(</span><span class="n">unit</span><span class="w"> </span><span class="p">-></span><span class="w"> </span><span class="n">int</span><span class="p">)</span><span class="w"> </span><span class="n">*</span><span class="w"> </span><span class="p">(</span><span class="n">int</span><span class="w"> </span><span class="p">-></span><span class="w"> </span><span class="n">unit</span><span class="p">);</span><span class="w"></span>
<span class="k">val</span><span class="w"> </span><span class="p">()</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">zzzSet</span><span class="w"> </span><span class="mi">42</span><span class="w"></span>
<span class="k">val</span><span class="w"> </span><span class="n">g5</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">_</span><span class="n">import</span><span class="w"> </span><span class="s">"g5"</span><span class="w"> </span><span class="n">public</span><span class="p">:</span><span class="w"> </span><span class="n">unit</span><span class="w"> </span><span class="p">-></span><span class="w"> </span><span class="n">unit</span><span class="p">;</span><span class="w"></span>
<span class="k">val</span><span class="w"> </span><span class="p">_</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">g5</span><span class="w"> </span><span class="p">()</span><span class="w"></span>
<span class="k">val</span><span class="w"> </span><span class="p">_</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">print</span><span class="w"> </span><span class="s">"success</span><span class="se">\n</span><span class="s">"</span><span class="w"></span>
</pre></div></div></div>
<div class="paragraph"><p>Create the header file with <span class="monospaced">-export-header</span>.</p></div>
<div class="listingblock">
<div class="content monospaced">
<pre>% mlton -default-ann 'allowFFI true' \
-export-header export.h \
-stop tc \
export.sml</pre>
</div></div>
<div class="paragraph"><p><span class="monospaced">export.h</span> now contains the following C prototypes.</p></div>
<div class="listingblock">
<div class="content monospaced">
<pre>Int8 f (Int32 x0, Real64 x1, Int8 x2);
Pointer f2 (Word8 x0);
void f3 ();
void f4 (Int32 x0);
extern Int32 zzz;</pre>
</div></div>
<div class="paragraph"><p>Use <span class="monospaced">export.h</span> in a C program, <span class="monospaced">ffi-export.c</span>, as follows.</p></div>
<div class="listingblock">
<div class="content"><div class="highlight"><pre><span class="cp">#include <stdio.h></span>
<span class="cp">#include "export.h"</span>
<span class="cm">/* Functions in C are by default PUBLIC symbols */</span>
<span class="kt">void</span> <span class="nf">g</span> <span class="p">()</span> <span class="p">{</span>
<span class="n">Char8</span> <span class="n">c</span><span class="p">;</span>
<span class="n">fprintf</span> <span class="p">(</span><span class="n">stderr</span><span class="p">,</span> <span class="s">"g starting</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span>
<span class="n">c</span> <span class="o">=</span> <span class="n">f</span> <span class="p">(</span><span class="mi">13</span><span class="p">,</span> <span class="mf">17.15</span><span class="p">,</span> <span class="sc">'a'</span><span class="p">);</span>
<span class="n">fprintf</span> <span class="p">(</span><span class="n">stderr</span><span class="p">,</span> <span class="s">"g done char = %c</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="n">c</span><span class="p">);</span>
<span class="p">}</span>
<span class="n">Pointer</span> <span class="nf">g2</span> <span class="p">()</span> <span class="p">{</span>
<span class="n">Pointer</span> <span class="n">res</span><span class="p">;</span>
<span class="n">fprintf</span> <span class="p">(</span><span class="n">stderr</span><span class="p">,</span> <span class="s">"g2 starting</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span>
<span class="n">res</span> <span class="o">=</span> <span class="n">f2</span> <span class="p">(</span><span class="mh">0xFF</span><span class="p">);</span>
<span class="n">fprintf</span> <span class="p">(</span><span class="n">stderr</span><span class="p">,</span> <span class="s">"g2 done</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span>
<span class="k">return</span> <span class="n">res</span><span class="p">;</span>
<span class="p">}</span>
<span class="kt">void</span> <span class="nf">g3</span> <span class="p">()</span> <span class="p">{</span>
<span class="n">fprintf</span> <span class="p">(</span><span class="n">stderr</span><span class="p">,</span> <span class="s">"g3 starting</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span>
<span class="n">f3</span> <span class="p">();</span>
<span class="n">fprintf</span> <span class="p">(</span><span class="n">stderr</span><span class="p">,</span> <span class="s">"g3 done</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span>
<span class="p">}</span>
<span class="kt">void</span> <span class="nf">g4</span> <span class="p">(</span><span class="n">Int32</span> <span class="n">i</span><span class="p">)</span> <span class="p">{</span>
<span class="n">fprintf</span> <span class="p">(</span><span class="n">stderr</span><span class="p">,</span> <span class="s">"g4 (%d)</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="n">i</span><span class="p">);</span>
<span class="n">f4</span> <span class="p">(</span><span class="n">i</span><span class="p">);</span>
<span class="p">}</span>
<span class="kt">void</span> <span class="nf">g5</span> <span class="p">()</span> <span class="p">{</span>
<span class="n">fprintf</span> <span class="p">(</span><span class="n">stderr</span><span class="p">,</span> <span class="s">"g5 ()</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span>
<span class="n">fprintf</span> <span class="p">(</span><span class="n">stderr</span><span class="p">,</span> <span class="s">"zzz = %i</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="n">zzz</span><span class="p">);</span>
<span class="n">fprintf</span> <span class="p">(</span><span class="n">stderr</span><span class="p">,</span> <span class="s">"g5 done</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span>
<span class="p">}</span>
</pre></div></div></div>
<div class="paragraph"><p>Compile <span class="monospaced">ffi-export.c</span> and <span class="monospaced">export.sml</span>.</p></div>
<div class="listingblock">
<div class="content monospaced">
<pre>% gcc -c ffi-export.c
% mlton -default-ann 'allowFFI true' \
export.sml ffi-export.o</pre>
</div></div>
<div class="paragraph"><p>Finally, run <span class="monospaced">export</span>.</p></div>
<div class="listingblock">
<div class="content monospaced">
<pre>% ./export
g starting
...
g4 (0)
success</pre>
</div></div>
</div>
</div>
<div class="sect1">
<h2 id="_download">Download</h2>
<div class="sectionbody">
<div class="ulist"><ul>
<li>
<p>
<a href="https://raw.github.com/MLton/mlton/master/doc/examples/ffi/export.sml"><span class="monospaced">export.sml</span></a>
</p>
</li>
<li>
<p>
<a href="https://raw.github.com/MLton/mlton/master/doc/examples/ffi/ffi-export.c"><span class="monospaced">ffi-export.c</span></a>
</p>
</li>
</ul></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>
|