HCoop / hcoop / debian / mlton.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
Import Upstream version 20180207
[hcoop/debian/mlton.git] / doc / guide / localhost / ForeignFunctionInterfaceSyntax
CommitLineData
7f918cf1
CE		 1<!DOCTYPE html>\r
2<html lang="en">\r
3<head>\r
4<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">\r
5<meta name="generator" content="AsciiDoc 8.6.9">\r
6<title>ForeignFunctionInterfaceSyntax</title>\r
7<link rel="stylesheet" href="./asciidoc.css" type="text/css">\r
8<link rel="stylesheet" href="./pygments.css" type="text/css">\r
9\r
10\r
11<script type="text/javascript" src="./asciidoc.js"></script>\r
12<script type="text/javascript">\r
13/*<![CDATA[*/\r
14asciidoc.install();\r
15/*]]>*/\r
16</script>\r
17<link rel="stylesheet" href="./mlton.css" type="text/css">\r
18</head>\r
19<body class="article">\r
20<div id="banner">\r
21<div id="banner-home">\r
22<a href="./Home">MLton 20180207</a>\r
23</div>\r
24</div>\r
25<div id="header">\r
26<h1>ForeignFunctionInterfaceSyntax</h1>\r
27</div>\r
28<div id="content">\r
29<div id="preamble">\r
30<div class="sectionbody">\r
31<div class="paragraph"><p>MLton extends the syntax of SML with expressions that enable a\r
32<a href="ForeignFunctionInterface">ForeignFunctionInterface</a> to C. The following description of the\r
33syntax uses some abbreviations.</p></div>\r
34<table class="tableblock frame-all grid-all"\r
35style="\r
36width:100%;\r
37">\r
38<col style="width:33%;">\r
39<col style="width:33%;">\r
40<col style="width:33%;">\r
41<thead>\r
42<tr>\r
43<th class="tableblock halign-left valign-top" > C base type </th>\r
44<th class="tableblock halign-left valign-top" > <em>cBaseTy</em> </th>\r
45<th class="tableblock halign-left valign-top" > <a href="ForeignFunctionInterfaceTypes"> Foreign Function Interface types</a></th>\r
46</tr>\r
47</thead>\r
48<tbody>\r
49<tr>\r
50<td class="tableblock halign-left valign-top" ><p class="tableblock">C argument type</p></td>\r
51<td class="tableblock halign-left valign-top" ><p class="tableblock"><em>cArgTy</em></p></td>\r
52<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>\r
53</tr>\r
54<tr>\r
55<td class="tableblock halign-left valign-top" ><p class="tableblock">C return type</p></td>\r
56<td class="tableblock halign-left valign-top" ><p class="tableblock"><em>cRetTy</em></p></td>\r
57<td class="tableblock halign-left valign-top" ><p class="tableblock"><em>cBaseTy</em> or <span class="monospaced">unit</span></p></td>\r
58</tr>\r
59<tr>\r
60<td class="tableblock halign-left valign-top" ><p class="tableblock">C function type</p></td>\r
61<td class="tableblock halign-left valign-top" ><p class="tableblock"><em>cFuncTy</em></p></td>\r
62<td class="tableblock halign-left valign-top" ><p class="tableblock"><em>cArgTy</em> <span class="monospaced">-&gt;</span> <em>cRetTy</em></p></td>\r
63</tr>\r
64<tr>\r
65<td class="tableblock halign-left valign-top" ><p class="tableblock">C pointer type</p></td>\r
66<td class="tableblock halign-left valign-top" ><p class="tableblock"><em>cPtrTy</em></p></td>\r
67<td class="tableblock halign-left valign-top" ><p class="tableblock"><span class="monospaced">MLton.Pointer.t</span></p></td>\r
68</tr>\r
69</tbody>\r
70</table>\r
71<div class="paragraph"><p>The type annotation and the semicolon are not optional in the syntax\r
72of <a href="ForeignFunctionInterface">ForeignFunctionInterface</a> expressions. However, the type is\r
73lexed, parsed, and elaborated as an SML type, so any type (including\r
74type abbreviations) may be used, so long as it elaborates to a type of\r
75the correct form.</p></div>\r
76</div>\r
77</div>\r
78<div class="sect1">\r
79<h2 id="_address">Address</h2>\r
80<div class="sectionbody">\r
81<div class="listingblock">\r
82<div class="content monospaced">\r
83<pre>_address "CFunctionOrVariableName" attr... : cPtrTy;</pre>\r
84</div></div>\r
85<div class="paragraph"><p>Denotes the address of the C function or variable.</p></div>\r
86<div class="paragraph"><p><span class="monospaced">attr...</span> denotes a (possibly empty) sequence of attributes. The following attributes are recognized:</p></div>\r
87<div class="ulist"><ul>\r
88<li>\r
89<p>\r
90<span class="monospaced">external</span> : import with external symbol scope (see <a href="LibrarySupport">LibrarySupport</a>) (default).\r
91</p>\r
92</li>\r
93<li>\r
94<p>\r
95<span class="monospaced">private</span> : import with private symbol scope (see <a href="LibrarySupport">LibrarySupport</a>).\r
96</p>\r
97</li>\r
98<li>\r
99<p>\r
100<span class="monospaced">public</span> : import with public symbol scope (see <a href="LibrarySupport">LibrarySupport</a>).\r
101</p>\r
102</li>\r
103</ul></div>\r
104<div class="paragraph"><p>See <a href="MLtonPointer"> MLtonPointer</a> for functions that manipulate C pointers.</p></div>\r
105</div>\r
106</div>\r
107<div class="sect1">\r
108<h2 id="_symbol">Symbol</h2>\r
109<div class="sectionbody">\r
110<div class="listingblock">\r
111<div class="content monospaced">\r
112<pre>_symbol "CVariableName" attr... : (unit -&gt; cBaseTy) * (cBaseTy -&gt; unit);</pre>\r
113</div></div>\r
114<div class="paragraph"><p>Denotes the <em>getter</em> and <em>setter</em> for a C variable. The <em>cBaseTy</em>s\r
115must be identical.</p></div>\r
116<div class="paragraph"><p><span class="monospaced">attr...</span> denotes a (possibly empty) sequence of attributes. The following attributes are recognized:</p></div>\r
117<div class="ulist"><ul>\r
118<li>\r
119<p>\r
120<span class="monospaced">alloc</span> : allocate storage (and export a symbol) for the C variable.\r
121</p>\r
122</li>\r
123<li>\r
124<p>\r
125<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>).\r
126</p>\r
127</li>\r
128<li>\r
129<p>\r
130<span class="monospaced">private</span> : import or export with private symbol scope (see <a href="LibrarySupport">LibrarySupport</a>).\r
131</p>\r
132</li>\r
133<li>\r
134<p>\r
135<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>).\r
136</p>\r
137</li>\r
138</ul></div>\r
139<div class="listingblock">\r
140<div class="content monospaced">\r
141<pre>_symbol * : cPtrTy -&gt; (unit -&gt; cBaseTy) * (cBaseTy -&gt; unit);</pre>\r
142</div></div>\r
143<div class="paragraph"><p>Denotes the <em>getter</em> and <em>setter</em> for a C pointer to a variable.\r
144The <em>cBaseTy</em>s must be identical.</p></div>\r
145</div>\r
146</div>\r
147<div class="sect1">\r
148<h2 id="_import">Import</h2>\r
149<div class="sectionbody">\r
150<div class="listingblock">\r
151<div class="content monospaced">\r
152<pre>_import "CFunctionName" attr... : cFuncTy;</pre>\r
153</div></div>\r
154<div class="paragraph"><p>Denotes an SML function whose behavior is implemented by calling the C\r
155function. See <a href="CallingFromSMLToC"> Calling from SML to C</a> for more\r
156details.</p></div>\r
157<div class="paragraph"><p><span class="monospaced">attr...</span> denotes a (possibly empty) sequence of attributes. The following attributes are recognized:</p></div>\r
158<div class="ulist"><ul>\r
159<li>\r
160<p>\r
161<span class="monospaced">cdecl</span> : call with the <span class="monospaced">cdecl</span> calling convention (default).\r
162</p>\r
163</li>\r
164<li>\r
165<p>\r
166<span class="monospaced">external</span> : import with external symbol scope (see <a href="LibrarySupport">LibrarySupport</a>) (default).\r
167</p>\r
168</li>\r
169<li>\r
170<p>\r
171<span class="monospaced">impure</span>: assert that the function depends upon state and/or performs side effects (default).\r
172</p>\r
173</li>\r
174<li>\r
175<p>\r
176<span class="monospaced">private</span> : import with private symbol scope (see <a href="LibrarySupport">LibrarySupport</a>).\r
177</p>\r
178</li>\r
179<li>\r
180<p>\r
181<span class="monospaced">public</span> : import with public symbol scope (see <a href="LibrarySupport">LibrarySupport</a>).\r
182</p>\r
183</li>\r
184<li>\r
185<p>\r
186<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>)\r
187</p>\r
188</li>\r
189<li>\r
190<p>\r
191<span class="monospaced">reentrant</span>: assert that the function (directly or indirectly) calls an <span class="monospaced">_export</span>-ed SML function.\r
192</p>\r
193</li>\r
194<li>\r
195<p>\r
196<span class="monospaced">stdcall</span> : call with the <span class="monospaced">stdcall</span> calling convention (ignored except on Cygwin and MinGW).\r
197</p>\r
198</li>\r
199</ul></div>\r
200<div class="listingblock">\r
201<div class="content monospaced">\r
202<pre>_import * attr... : cPtrTy -&gt; cFuncTy;</pre>\r
203</div></div>\r
204<div class="paragraph"><p>Denotes an SML function whose behavior is implemented by calling a C\r
205function through a C function pointer.</p></div>\r
206<div class="paragraph"><p><span class="monospaced">attr...</span> denotes a (possibly empty) sequence of attributes. The following attributes are recognized:</p></div>\r
207<div class="ulist"><ul>\r
208<li>\r
209<p>\r
210<span class="monospaced">cdecl</span> : call with the <span class="monospaced">cdecl</span> calling convention (default).\r
211</p>\r
212</li>\r
213<li>\r
214<p>\r
215<span class="monospaced">impure</span>: assert that the function depends upon state and/or performs side effects (default).\r
216</p>\r
217</li>\r
218<li>\r
219<p>\r
220<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>)\r
221</p>\r
222</li>\r
223<li>\r
224<p>\r
225<span class="monospaced">reentrant</span>: assert that the function (directly or indirectly) calls an <span class="monospaced">_export</span>-ed SML function.\r
226</p>\r
227</li>\r
228<li>\r
229<p>\r
230<span class="monospaced">stdcall</span> : call with the <span class="monospaced">stdcall</span> calling convention (ignored except on Cygwin and MinGW).\r
231</p>\r
232</li>\r
233</ul></div>\r
234<div class="paragraph"><p>See\r
235<a href="CallingFromSMLToCFunctionPointer"> Calling from SML to C function pointer</a>\r
236for more details.</p></div>\r
237</div>\r
238</div>\r
239<div class="sect1">\r
240<h2 id="_export">Export</h2>\r
241<div class="sectionbody">\r
242<div class="listingblock">\r
243<div class="content monospaced">\r
244<pre>_export "CFunctionName" attr... : cFuncTy -&gt; unit;</pre>\r
245</div></div>\r
246<div class="paragraph"><p>Exports a C function with the name <span class="monospaced">CFunctionName</span> that can be used to\r
247call an SML function of the type <em>cFuncTy</em>. When the function denoted\r
248by the export expression is applied to an SML function <span class="monospaced">f</span>, subsequent\r
249C calls to <span class="monospaced">CFunctionName</span> will call <span class="monospaced">f</span>. It is an error to call\r
250<span class="monospaced">CFunctionName</span> before the export has been applied. The export may be\r
251applied more than once, with each application replacing any previous\r
252definition of <span class="monospaced">CFunctionName</span>.</p></div>\r
253<div class="paragraph"><p><span class="monospaced">attr...</span> denotes a (possibly empty) sequence of attributes. The following attributes are recognized:</p></div>\r
254<div class="ulist"><ul>\r
255<li>\r
256<p>\r
257<span class="monospaced">cdecl</span> : call with the <span class="monospaced">cdecl</span> calling convention (default).\r
258</p>\r
259</li>\r
260<li>\r
261<p>\r
262<span class="monospaced">private</span> : export with private symbol scope (see <a href="LibrarySupport">LibrarySupport</a>).\r
263</p>\r
264</li>\r
265<li>\r
266<p>\r
267<span class="monospaced">public</span> : export with public symbol scope (see <a href="LibrarySupport">LibrarySupport</a>) (default).\r
268</p>\r
269</li>\r
270<li>\r
271<p>\r
272<span class="monospaced">stdcall</span> : call with the <span class="monospaced">stdcall</span> calling convention (ignored except on Cygwin and MinGW).\r
273</p>\r
274</li>\r
275</ul></div>\r
276<div class="paragraph"><p>See <a href="CallingFromCToSML"> Calling from C to SML</a> for more details.</p></div>\r
277</div>\r
278</div>\r
279</div>\r
280<div id="footnotes"><hr></div>\r
281<div id="footer">\r
282<div id="footer-text">\r
283</div>\r
284<div id="footer-badges">\r
285</div>\r
286</div>\r
287</body>\r
288</html>\r
mlton packaging