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
|
<!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>CallingFromSMLToC</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>CallingFromSMLToC</h1>
</div>
<div id="content">
<div id="preamble">
<div class="sectionbody">
<div class="paragraph"><p>MLton’s <a href="ForeignFunctionInterface">ForeignFunctionInterface</a> allows an SML program to <em>import</em>
C functions. Suppose you would like to import from C a function with
the following prototype:</p></div>
<div class="listingblock">
<div class="content"><div class="highlight"><pre><span class="kt">int</span> <span class="n">foo</span> <span class="p">(</span><span class="kt">double</span> <span class="n">d</span><span class="p">,</span> <span class="kt">char</span> <span class="n">c</span><span class="p">);</span>
</pre></div></div></div>
<div class="paragraph"><p>MLton extends the syntax of SML to allow expressions like the following:</p></div>
<div class="listingblock">
<div class="content monospaced">
<pre>_import "foo": real * char -> int;</pre>
</div></div>
<div class="paragraph"><p>This expression denotes a function of type <span class="monospaced">real * char -> int</span> whose
behavior is implemented by calling the C function whose name is <span class="monospaced">foo</span>.
Thinking in terms of C, imagine that there are C variables <span class="monospaced">d</span> of type
<span class="monospaced">double</span>, <span class="monospaced">c</span> of type <span class="monospaced">unsigned char</span>, and <span class="monospaced">i</span> of type <span class="monospaced">int</span>. Then,
the C statement <span class="monospaced">i = foo (d, c)</span> is executed and <span class="monospaced">i</span> is returned.</p></div>
<div class="paragraph"><p>The general form of an <span class="monospaced">_import</span> expression is:</p></div>
<div class="listingblock">
<div class="content monospaced">
<pre>_import "C function name" attr... : cFuncTy;</pre>
</div></div>
<div class="paragraph"><p>The type and the semicolon are not optional.</p></div>
<div class="paragraph"><p>The function name is followed by a (possibly empty) sequence of
attributes, analogous to C <span class="monospaced">__attribute__</span> specifiers. For now, the
only attributes supported are <span class="monospaced">cdecl</span> and <span class="monospaced">stdcall</span>. These specify
the calling convention of the C function on Cygwin/Windows, and are
ignored on all other platforms. The default is <span class="monospaced">cdecl</span>. You must use
<span class="monospaced">stdcall</span> in order to correctly call Windows API functions.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_example">Example</h2>
<div class="sectionbody">
<div class="paragraph"><p><span class="monospaced">import.sml</span> imports the C function <span class="monospaced">ffi</span> and the C variable <span class="monospaced">FFI_INT</span>
as follows.</p></div>
<div class="listingblock">
<div class="content"><div class="highlight"><pre><span class="cm">(* main.sml *)</span><span class="w"></span>
<span class="cm">(* Declare ffi to be implemented by calling the C function ffi. *)</span><span class="w"></span>
<span class="k">val</span><span class="w"> </span><span class="n">ffi</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">"ffi"</span><span class="w"> </span><span class="n">public</span><span class="p">:</span><span class="w"> </span><span class="n">real</span><span class="w"> </span><span class="n">array</span><span class="w"> </span><span class="n">*</span><span class="w"> </span><span class="n">int</span><span class="w"> </span><span class="n">*</span><span class="w"> </span><span class="n">int</span><span class="w"> </span><span class="n">ref</span><span class="w"> </span><span class="n">*</span><span class="w"> </span><span class="n">char</span><span class="w"> </span><span class="n">ref</span><span class="w"> </span><span class="n">*</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">char</span><span class="p">;</span><span class="w"></span>
<span class="k">open</span><span class="w"> </span><span class="n">Array</span><span class="w"></span>
<span class="k">val</span><span class="w"> </span><span class="n">size</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mi">10</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">tabulate</span><span class="w"> </span><span class="p">(</span><span class="n">size</span><span class="p">,</span><span class="w"> </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="n">real</span><span class="w"> </span><span class="n">i</span><span class="p">)</span><span class="w"></span>
<span class="k">val</span><span class="w"> </span><span class="n">ri</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">ref</span><span class="w"> </span><span class="mi">0</span><span class="w"></span>
<span class="k">val</span><span class="w"> </span><span class="n">rc</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">ref</span><span class="w"> </span><span class="p">#</span><span class="s">"0"</span><span class="w"></span>
<span class="k">val</span><span class="w"> </span><span class="n">n</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mi">17</span><span class="w"></span>
<span class="cm">(* Call the C function *)</span><span class="w"></span>
<span class="k">val</span><span class="w"> </span><span class="n">c</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">ffi</span><span class="w"> </span><span class="p">(</span><span class="n">a</span><span class="p">,</span><span class="w"> </span><span class="n">Array</span><span class="p">.</span><span class="n">length</span><span class="w"> </span><span class="n">a</span><span class="p">,</span><span class="w"> </span><span class="n">ri</span><span class="p">,</span><span class="w"> </span><span class="n">rc</span><span class="p">,</span><span class="w"> </span><span class="n">n</span><span class="p">)</span><span class="w"></span>
<span class="cm">(* FFI_INT is declared as public in ffi-import.c *)</span><span class="w"></span>
<span class="k">val</span><span class="w"> </span><span class="p">(</span><span class="n">nGet</span><span class="p">,</span><span class="w"> </span><span class="n">nSet</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">"FFI_INT"</span><span class="w"> </span><span class="n">public</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">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="n">Int</span><span class="p">.</span><span class="n">toString</span><span class="w"> </span><span class="p">(</span><span class="n">nGet</span><span class="w"> </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="p">_</span><span class="w"> </span><span class="p">=</span><span class="w"></span>
<span class="w"> </span><span class="n">print</span><span class="w"> </span><span class="p">(</span><span class="k">if</span><span class="w"> </span><span class="n">c</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="p">#</span><span class="s">"c"</span><span class="w"> </span><span class="k">andalso</span><span class="w"> </span><span class="n">!ri</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="mi">45</span><span class="w"> </span><span class="k">andalso</span><span class="w"> </span><span class="n">!rc</span><span class="w"> </span><span class="p">=</span><span class="w"> </span><span class="n">c</span><span class="w"></span>
<span class="w"> </span><span class="k">then</span><span class="w"> </span><span class="s">"success</span><span class="se">\n</span><span class="s">"</span><span class="w"></span>
<span class="w"> </span><span class="k">else</span><span class="w"> </span><span class="s">"fail</span><span class="se">\n</span><span class="s">"</span><span class="p">)</span><span class="w"></span>
</pre></div></div></div>
<div class="paragraph"><p><span class="monospaced">ffi-import.c</span> is</p></div>
<div class="listingblock">
<div class="content"><div class="highlight"><pre><span class="cp">#include "export.h"</span>
<span class="n">Int32</span> <span class="n">FFI_INT</span> <span class="o">=</span> <span class="mi">13</span><span class="p">;</span>
<span class="n">Word32</span> <span class="n">FFI_WORD</span> <span class="o">=</span> <span class="mh">0xFF</span><span class="p">;</span>
<span class="n">Bool</span> <span class="n">FFI_BOOL</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span>
<span class="n">Real64</span> <span class="n">FFI_REAL</span> <span class="o">=</span> <span class="mf">3.14159</span><span class="p">;</span>
<span class="n">Char8</span> <span class="nf">ffi</span> <span class="p">(</span><span class="n">Pointer</span> <span class="n">a1</span><span class="p">,</span> <span class="n">Int32</span> <span class="n">a1len</span><span class="p">,</span> <span class="n">Pointer</span> <span class="n">a2</span><span class="p">,</span> <span class="n">Pointer</span> <span class="n">a3</span><span class="p">,</span> <span class="n">Int32</span> <span class="n">n</span><span class="p">)</span> <span class="p">{</span>
<span class="kt">double</span> <span class="o">*</span><span class="n">ds</span> <span class="o">=</span> <span class="p">(</span><span class="kt">double</span><span class="o">*</span><span class="p">)</span><span class="n">a1</span><span class="p">;</span>
<span class="kt">int</span> <span class="o">*</span><span class="n">pi</span> <span class="o">=</span> <span class="p">(</span><span class="kt">int</span><span class="o">*</span><span class="p">)</span><span class="n">a2</span><span class="p">;</span>
<span class="kt">char</span> <span class="o">*</span><span class="n">pc</span> <span class="o">=</span> <span class="p">(</span><span class="kt">char</span><span class="o">*</span><span class="p">)</span><span class="n">a3</span><span class="p">;</span>
<span class="kt">int</span> <span class="n">i</span><span class="p">;</span>
<span class="kt">double</span> <span class="n">sum</span><span class="p">;</span>
<span class="n">sum</span> <span class="o">=</span> <span class="mf">0.0</span><span class="p">;</span>
<span class="k">for</span> <span class="p">(</span><span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">a1len</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span> <span class="p">{</span>
<span class="n">sum</span> <span class="o">+=</span> <span class="n">ds</span><span class="p">[</span><span class="n">i</span><span class="p">];</span>
<span class="n">ds</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">+=</span> <span class="n">n</span><span class="p">;</span>
<span class="p">}</span>
<span class="o">*</span><span class="n">pi</span> <span class="o">=</span> <span class="p">(</span><span class="kt">int</span><span class="p">)</span><span class="n">sum</span><span class="p">;</span>
<span class="o">*</span><span class="n">pc</span> <span class="o">=</span> <span class="sc">'c'</span><span class="p">;</span>
<span class="k">return</span> <span class="sc">'c'</span><span class="p">;</span>
<span class="p">}</span>
</pre></div></div></div>
<div class="paragraph"><p>Compile and run the program.</p></div>
<div class="listingblock">
<div class="content monospaced">
<pre>% mlton -default-ann 'allowFFI true' import.sml ffi-import.c
% ./import
13
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/import.sml"><span class="monospaced">import.sml</span></a>
</p>
</li>
<li>
<p>
<a href="https://raw.github.com/MLton/mlton/master/doc/examples/ffi/ffi-import.c"><span class="monospaced">ffi-import.c</span></a>
</p>
</li>
</ul></div>
</div>
</div>
<div class="sect1">
<h2 id="_next_steps">Next Steps</h2>
<div class="sectionbody">
<div class="ulist"><ul>
<li>
<p>
<a href="CallingFromSMLToCFunctionPointer">CallingFromSMLToCFunctionPointer</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>
|
