doc/guide/localhost/ForeignFunctionInterfaceSyntax

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