doc/ext_ffi_semantics.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
   2 <html>
   3 <head>
   4 <title>FFI Semantics</title>
   5 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   6 <meta name="Author" content="Mike Pall">
   7 <meta name="Copyright" content="Copyright (C) 2005-2017, Mike Pall">
   8 <meta name="Language" content="en">
   9 <link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
  10 <link rel="stylesheet" type="text/css" href="bluequad-print.css" media="print">
  11 <style type="text/css">
  12 table.convtable { line-height: 1.2; }
  13 tr.convhead td { font-weight: bold; }
  14 td.convop { font-style: italic; width: 40%; }
  15 </style>
  16 </head>
  17 <body>
  18 <div id="site">
  19 <a href="http://luajit.org"><span>Lua<span id="logo">JIT</span></span></a>
  20 </div>
  21 <div id="head">
  22 <h1>FFI Semantics</h1>
  23 </div>
  24 <div id="nav">
  25 <ul><li>
  26 <a href="luajit.html">LuaJIT</a>
  27 <ul><li>
  28 <a href="http://luajit.org/download.html">Download <span class="ext">&raquo;</span></a>
  29 </li><li>
  30 <a href="install.html">Installation</a>
  31 </li><li>
  32 <a href="running.html">Running</a>
  33 </li></ul>
  34 </li><li>
  35 <a href="extensions.html">Extensions</a>
  36 <ul><li>
  37 <a href="ext_ffi.html">FFI Library</a>
  38 <ul><li>
  39 <a href="ext_ffi_tutorial.html">FFI Tutorial</a>
  40 </li><li>
  41 <a href="ext_ffi_api.html">ffi.* API</a>
  42 </li><li>
  43 <a class="current" href="ext_ffi_semantics.html">FFI Semantics</a>
  44 </li></ul>
  45 </li><li>
  46 <a href="ext_jit.html">jit.* Library</a>
  47 </li><li>
  48 <a href="ext_c_api.html">Lua/C API</a>
  49 </li></ul>
  50 </li><li>
  51 <a href="status.html">Status</a>
  52 <ul><li>
  53 <a href="changes.html">Changes</a>
  54 </li></ul>
  55 </li><li>
  56 <a href="faq.html">FAQ</a>
  57 </li><li>
  58 <a href="http://luajit.org/performance.html">Performance <span class="ext">&raquo;</span></a>
  59 </li><li>
  60 <a href="http://wiki.luajit.org/">Wiki <span class="ext">&raquo;</span></a>
  61 </li><li>
  62 <a href="http://luajit.org/list.html">Mailing List <span class="ext">&raquo;</span></a>
  63 </li></ul>
  64 </div>
  65 <div id="main">
  66 <p>
  67 This page describes the detailed semantics underlying the FFI library
  68 and its interaction with both Lua and C&nbsp;code.
  69 </p>
  70 <p>
  71 Given that the FFI library is designed to interface with C&nbsp;code
  72 and that declarations can be written in plain C&nbsp;syntax, <b>it
  73 closely follows the C&nbsp;language semantics</b>, wherever possible.
  74 Some minor concessions are needed for smoother interoperation with Lua
  75 language semantics.
  76 </p>
  77 <p>
  78 Please don't be overwhelmed by the contents of this page &mdash; this
  79 is a reference and you may need to consult it, if in doubt. It doesn't
  80 hurt to skim this page, but most of the semantics "just work" as you'd
  81 expect them to work. It should be straightforward to write
  82 applications using the LuaJIT FFI for developers with a C or C++
  83 background.
  84 </p>
  85
  86 <h2 id="clang">C Language Support</h2>
  87 <p>
  88 The FFI library has a built-in C&nbsp;parser with a minimal memory
  89 footprint. It's used by the <a href="ext_ffi_api.html">ffi.* library
  90 functions</a> to declare C&nbsp;types or external symbols.
  91 </p>
  92 <p>
  93 It's only purpose is to parse C&nbsp;declarations, as found e.g. in
  94 C&nbsp;header files. Although it does evaluate constant expressions,
  95 it's <em>not</em> a C&nbsp;compiler. The body of <tt>inline</tt>
  96 C&nbsp;function definitions is simply ignored.
  97 </p>
  98 <p>
  99 Also, this is <em>not</em> a validating C&nbsp;parser. It expects and
 100 accepts correctly formed C&nbsp;declarations, but it may choose to
 101 ignore bad declarations or show rather generic error messages. If in
 102 doubt, please check the input against your favorite C&nbsp;compiler.
 103 </p>
 104 <p>
 105 The C&nbsp;parser complies to the <b>C99 language standard</b> plus
 106 the following extensions:
 107 </p>
 108 <ul>
 109
 110 <li>The <tt>'\e'</tt> escape in character and string literals.</li>
 111
 112 <li>The C99/C++ boolean type, declared with the keywords <tt>bool</tt>
 113 or <tt>_Bool</tt>.</li>
 114
 115 <li>Complex numbers, declared with the keywords <tt>complex</tt> or
 116 <tt>_Complex</tt>.</li>
 117
 118 <li>Two complex number types: <tt>complex</tt> (aka
 119 <tt>complex&nbsp;double</tt>) and <tt>complex&nbsp;float</tt>.</li>
 120
 121 <li>Vector types, declared with the GCC <tt>mode</tt> or
 122 <tt>vector_size</tt> attribute.</li>
 123
 124 <li>Unnamed ('transparent') <tt>struct</tt>/<tt>union</tt> fields
 125 inside a <tt>struct</tt>/<tt>union</tt>.</li>
 126
 127 <li>Incomplete <tt>enum</tt> declarations, handled like incomplete
 128 <tt>struct</tt> declarations.</li>
 129
 130 <li>Unnamed <tt>enum</tt> fields inside a
 131 <tt>struct</tt>/<tt>union</tt>. This is similar to a scoped C++
 132 <tt>enum</tt>, except that declared constants are visible in the
 133 global namespace, too.</li>
 134
 135 <li>Scoped <tt>static&nbsp;const</tt> declarations inside a
 136 <tt>struct</tt>/<tt>union</tt> (from C++).</li>
 137
 138 <li>Zero-length arrays (<tt>[0]</tt>), empty
 139 <tt>struct</tt>/<tt>union</tt>, variable-length arrays (VLA,
 140 <tt>[?]</tt>) and variable-length structs (VLS, with a trailing
 141 VLA).</li>
 142
 143 <li>C++ reference types (<tt>int&nbsp;&amp;x</tt>).</li>
 144
 145 <li>Alternate GCC keywords with '<tt>__</tt>', e.g.
 146 <tt>__const__</tt>.</li>
 147
 148 <li>GCC <tt>__attribute__</tt> with the following attributes:
 149 <tt>aligned</tt>, <tt>packed</tt>, <tt>mode</tt>,
 150 <tt>vector_size</tt>, <tt>cdecl</tt>, <tt>fastcall</tt>,
 151 <tt>stdcall</tt>, <tt>thiscall</tt>.</li>
 152
 153 <li>The GCC <tt>__extension__</tt> keyword and the GCC
 154 <tt>__alignof__</tt> operator.</li>
 155
 156 <li>GCC <tt>__asm__("symname")</tt> symbol name redirection for
 157 function declarations.</li>
 158
 159 <li>MSVC keywords for fixed-length types: <tt>__int8</tt>,
 160 <tt>__int16</tt>, <tt>__int32</tt> and <tt>__int64</tt>.</li>
 161
 162 <li>MSVC <tt>__cdecl</tt>, <tt>__fastcall</tt>, <tt>__stdcall</tt>,
 163 <tt>__thiscall</tt>, <tt>__ptr32</tt>, <tt>__ptr64</tt>,
 164 <tt>__declspec(align(n))</tt> and <tt>#pragma&nbsp;pack</tt>.</li>
 165
 166 <li>All other GCC/MSVC-specific attributes are ignored.</li>
 167
 168 </ul>
 169 <p>
 170 The following C&nbsp;types are pre-defined by the C&nbsp;parser (like
 171 a <tt>typedef</tt>, except re-declarations will be ignored):
 172 </p>
 173 <ul>
 174
 175 <li>Vararg handling: <tt>va_list</tt>, <tt>__builtin_va_list</tt>,
 176 <tt>__gnuc_va_list</tt>.</li>
 177
 178 <li>From <tt>&lt;stddef.h&gt;</tt>: <tt>ptrdiff_t</tt>,
 179 <tt>size_t</tt>, <tt>wchar_t</tt>.</li>
 180
 181 <li>From <tt>&lt;stdint.h&gt;</tt>: <tt>int8_t</tt>, <tt>int16_t</tt>,
 182 <tt>int32_t</tt>, <tt>int64_t</tt>, <tt>uint8_t</tt>,
 183 <tt>uint16_t</tt>, <tt>uint32_t</tt>, <tt>uint64_t</tt>,
 184 <tt>intptr_t</tt>, <tt>uintptr_t</tt>.</li>
 185
 186 </ul>
 187 <p>
 188 You're encouraged to use these types in preference to
 189 compiler-specific extensions or target-dependent standard types.
 190 E.g. <tt>char</tt> differs in signedness and <tt>long</tt> differs in
 191 size, depending on the target architecture and platform ABI.
 192 </p>
 193 <p>
 194 The following C&nbsp;features are <b>not</b> supported:
 195 </p>
 196 <ul>
 197
 198 <li>A declaration must always have a type specifier; it doesn't
 199 default to an <tt>int</tt> type.</li>
 200
 201 <li>Old-style empty function declarations (K&amp;R) are not allowed.
 202 All C&nbsp;functions must have a proper prototype declaration. A
 203 function declared without parameters (<tt>int&nbsp;foo();</tt>) is
 204 treated as a function taking zero arguments, like in C++.</li>
 205
 206 <li>The <tt>long double</tt> C&nbsp;type is parsed correctly, but
 207 there's no support for the related conversions, accesses or arithmetic
 208 operations.</li>
 209
 210 <li>Wide character strings and character literals are not
 211 supported.</li>
 212
 213 <li><a href="#status">See below</a> for features that are currently
 214 not implemented.</li>
 215
 216 </ul>
 217
 218 <h2 id="convert">C Type Conversion Rules</h2>
 219
 220 <h3 id="convert_tolua">Conversions from C&nbsp;types to Lua objects</h3>
 221 <p>
 222 These conversion rules apply for <em>read accesses</em> to
 223 C&nbsp;types: indexing pointers, arrays or
 224 <tt>struct</tt>/<tt>union</tt> types; reading external variables or
 225 constant values; retrieving return values from C&nbsp;calls:
 226 </p>
 227 <table class="convtable">
 228 <tr class="convhead">
 229 <td class="convin">Input</td>
 230 <td class="convop">Conversion</td>
 231 <td class="convout">Output</td>
 232 </tr>
 233 <tr class="odd separate">
 234 <td class="convin"><tt>int8_t</tt>, <tt>int16_t</tt></td><td class="convop">&rarr;<sup>sign-ext</sup> <tt>int32_t</tt> &rarr; <tt>double</tt></td><td class="convout">number</td></tr>
 235 <tr class="even">
 236 <td class="convin"><tt>uint8_t</tt>, <tt>uint16_t</tt></td><td class="convop">&rarr;<sup>zero-ext</sup> <tt>int32_t</tt> &rarr; <tt>double</tt></td><td class="convout">number</td></tr>
 237 <tr class="odd">
 238 <td class="convin"><tt>int32_t</tt>, <tt>uint32_t</tt></td><td class="convop">&rarr; <tt>double</tt></td><td class="convout">number</td></tr>
 239 <tr class="even">
 240 <td class="convin"><tt>int64_t</tt>, <tt>uint64_t</tt></td><td class="convop">boxed value</td><td class="convout">64 bit int cdata</td></tr>
 241 <tr class="odd separate">
 242 <td class="convin"><tt>double</tt>, <tt>float</tt></td><td class="convop">&rarr; <tt>double</tt></td><td class="convout">number</td></tr>
 243 <tr class="even separate">
 244 <td class="convin"><tt>bool</tt></td><td class="convop">0 &rarr; <tt>false</tt>, otherwise <tt>true</tt></td><td class="convout">boolean</td></tr>
 245 <tr class="odd separate">
 246 <td class="convin"><tt>enum</tt></td><td class="convop">boxed value</td><td class="convout">enum cdata</td></tr>
 247 <tr class="even">
 248 <td class="convin">Complex number</td><td class="convop">boxed value</td><td class="convout">complex cdata</td></tr>
 249 <tr class="odd">
 250 <td class="convin">Vector</td><td class="convop">boxed value</td><td class="convout">vector cdata</td></tr>
 251 <tr class="even">
 252 <td class="convin">Pointer</td><td class="convop">boxed value</td><td class="convout">pointer cdata</td></tr>
 253 <tr class="odd separate">
 254 <td class="convin">Array</td><td class="convop">boxed reference</td><td class="convout">reference cdata</td></tr>
 255 <tr class="even">
 256 <td class="convin"><tt>struct</tt>/<tt>union</tt></td><td class="convop">boxed reference</td><td class="convout">reference cdata</td></tr>
 257 </table>
 258 <p>
 259 Bitfields are treated like their underlying type.
 260 </p>
 261 <p>
 262 Reference types are dereferenced <em>before</em> a conversion can take
 263 place &mdash; the conversion is applied to the C&nbsp;type pointed to
 264 by the reference.
 265 </p>
 266
 267 <h3 id="convert_fromlua">Conversions from Lua objects to C&nbsp;types</h3>
 268 <p>
 269 These conversion rules apply for <em>write accesses</em> to
 270 C&nbsp;types: indexing pointers, arrays or
 271 <tt>struct</tt>/<tt>union</tt> types; initializing cdata objects;
 272 casts to C&nbsp;types; writing to external variables; passing
 273 arguments to C&nbsp;calls:
 274 </p>
 275 <table class="convtable">
 276 <tr class="convhead">
 277 <td class="convin">Input</td>
 278 <td class="convop">Conversion</td>
 279 <td class="convout">Output</td>
 280 </tr>
 281 <tr class="odd separate">
 282 <td class="convin">number</td><td class="convop">&rarr;</td><td class="convout"><tt>double</tt></td></tr>
 283 <tr class="even">
 284 <td class="convin">boolean</td><td class="convop"><tt>false</tt> &rarr; 0, <tt>true</tt> &rarr; 1</td><td class="convout"><tt>bool</tt></td></tr>
 285 <tr class="odd separate">
 286 <td class="convin">nil</td><td class="convop"><tt>NULL</tt> &rarr;</td><td class="convout"><tt>(void *)</tt></td></tr>
 287 <tr class="even">
 288 <td class="convin">lightuserdata</td><td class="convop">lightuserdata address &rarr;</td><td class="convout"><tt>(void *)</tt></td></tr>
 289 <tr class="odd">
 290 <td class="convin">userdata</td><td class="convop">userdata payload &rarr;</td><td class="convout"><tt>(void *)</tt></td></tr>
 291 <tr class="even">
 292 <td class="convin">io.* file</td><td class="convop">get FILE * handle &rarr;</td><td class="convout"><tt>(void *)</tt></td></tr>
 293 <tr class="odd separate">
 294 <td class="convin">string</td><td class="convop">match against <tt>enum</tt> constant</td><td class="convout"><tt>enum</tt></td></tr>
 295 <tr class="even">
 296 <td class="convin">string</td><td class="convop">copy string data + zero-byte</td><td class="convout"><tt>int8_t[]</tt>, <tt>uint8_t[]</tt></td></tr>
 297 <tr class="odd">
 298 <td class="convin">string</td><td class="convop">string data &rarr;</td><td class="convout"><tt>const char[]</tt></td></tr>
 299 <tr class="even separate">
 300 <td class="convin">function</td><td class="convop"><a href="#callback">create callback</a> &rarr;</td><td class="convout">C function type</td></tr>
 301 <tr class="odd separate">
 302 <td class="convin">table</td><td class="convop"><a href="#init_table">table initializer</a></td><td class="convout">Array</td></tr>
 303 <tr class="even">
 304 <td class="convin">table</td><td class="convop"><a href="#init_table">table initializer</a></td><td class="convout"><tt>struct</tt>/<tt>union</tt></td></tr>
 305 <tr class="odd separate">
 306 <td class="convin">cdata</td><td class="convop">cdata payload &rarr;</td><td class="convout">C type</td></tr>
 307 </table>
 308 <p>
 309 If the result type of this conversion doesn't match the
 310 C&nbsp;type of the destination, the
 311 <a href="#convert_between">conversion rules between C&nbsp;types</a>
 312 are applied.
 313 </p>
 314 <p>
 315 Reference types are immutable after initialization ("no re-seating of
 316 references"). For initialization purposes or when passing values to
 317 reference parameters, they are treated like pointers. Note that unlike
 318 in C++, there's no way to implement automatic reference generation of
 319 variables under the Lua language semantics. If you want to call a
 320 function with a reference parameter, you need to explicitly pass a
 321 one-element array.
 322 </p>
 323
 324 <h3 id="convert_between">Conversions between C&nbsp;types</h3>
 325 <p>
 326 These conversion rules are more or less the same as the standard
 327 C&nbsp;conversion rules. Some rules only apply to casts, or require
 328 pointer or type compatibility:
 329 </p>
 330 <table class="convtable">
 331 <tr class="convhead">
 332 <td class="convin">Input</td>
 333 <td class="convop">Conversion</td>
 334 <td class="convout">Output</td>
 335 </tr>
 336 <tr class="odd separate">
 337 <td class="convin">Signed integer</td><td class="convop">&rarr;<sup>narrow or sign-extend</sup></td><td class="convout">Integer</td></tr>
 338 <tr class="even">
 339 <td class="convin">Unsigned integer</td><td class="convop">&rarr;<sup>narrow or zero-extend</sup></td><td class="convout">Integer</td></tr>
 340 <tr class="odd">
 341 <td class="convin">Integer</td><td class="convop">&rarr;<sup>round</sup></td><td class="convout"><tt>double</tt>, <tt>float</tt></td></tr>
 342 <tr class="even">
 343 <td class="convin"><tt>double</tt>, <tt>float</tt></td><td class="convop">&rarr;<sup>trunc</sup> <tt>int32_t</tt> &rarr;<sup>narrow</sup></td><td class="convout"><tt>(u)int8_t</tt>, <tt>(u)int16_t</tt></td></tr>
 344 <tr class="odd">
 345 <td class="convin"><tt>double</tt>, <tt>float</tt></td><td class="convop">&rarr;<sup>trunc</sup></td><td class="convout"><tt>(u)int32_t</tt>, <tt>(u)int64_t</tt></td></tr>
 346 <tr class="even">
 347 <td class="convin"><tt>double</tt>, <tt>float</tt></td><td class="convop">&rarr;<sup>round</sup></td><td class="convout"><tt>float</tt>, <tt>double</tt></td></tr>
 348 <tr class="odd separate">
 349 <td class="convin">Number</td><td class="convop">n == 0 &rarr; 0, otherwise 1</td><td class="convout"><tt>bool</tt></td></tr>
 350 <tr class="even">
 351 <td class="convin"><tt>bool</tt></td><td class="convop"><tt>false</tt> &rarr; 0, <tt>true</tt> &rarr; 1</td><td class="convout">Number</td></tr>
 352 <tr class="odd separate">
 353 <td class="convin">Complex number</td><td class="convop">convert real part</td><td class="convout">Number</td></tr>
 354 <tr class="even">
 355 <td class="convin">Number</td><td class="convop">convert real part, imag = 0</td><td class="convout">Complex number</td></tr>
 356 <tr class="odd">
 357 <td class="convin">Complex number</td><td class="convop">convert real and imag part</td><td class="convout">Complex number</td></tr>
 358 <tr class="even separate">
 359 <td class="convin">Number</td><td class="convop">convert scalar and replicate</td><td class="convout">Vector</td></tr>
 360 <tr class="odd">
 361 <td class="convin">Vector</td><td class="convop">copy (same size)</td><td class="convout">Vector</td></tr>
 362 <tr class="even separate">
 363 <td class="convin"><tt>struct</tt>/<tt>union</tt></td><td class="convop">take base address (compat)</td><td class="convout">Pointer</td></tr>
 364 <tr class="odd">
 365 <td class="convin">Array</td><td class="convop">take base address (compat)</td><td class="convout">Pointer</td></tr>
 366 <tr class="even">
 367 <td class="convin">Function</td><td class="convop">take function address</td><td class="convout">Function pointer</td></tr>
 368 <tr class="odd separate">
 369 <td class="convin">Number</td><td class="convop">convert via <tt>uintptr_t</tt> (cast)</td><td class="convout">Pointer</td></tr>
 370 <tr class="even">
 371 <td class="convin">Pointer</td><td class="convop">convert address (compat/cast)</td><td class="convout">Pointer</td></tr>
 372 <tr class="odd">
 373 <td class="convin">Pointer</td><td class="convop">convert address (cast)</td><td class="convout">Integer</td></tr>
 374 <tr class="even">
 375 <td class="convin">Array</td><td class="convop">convert base address (cast)</td><td class="convout">Integer</td></tr>
 376 <tr class="odd separate">
 377 <td class="convin">Array</td><td class="convop">copy (compat)</td><td class="convout">Array</td></tr>
 378 <tr class="even">
 379 <td class="convin"><tt>struct</tt>/<tt>union</tt></td><td class="convop">copy (identical type)</td><td class="convout"><tt>struct</tt>/<tt>union</tt></td></tr>
 380 </table>
 381 <p>
 382 Bitfields or <tt>enum</tt> types are treated like their underlying
 383 type.
 384 </p>
 385 <p>
 386 Conversions not listed above will raise an error. E.g. it's not
 387 possible to convert a pointer to a complex number or vice versa.
 388 </p>
 389
 390 <h3 id="convert_vararg">Conversions for vararg C&nbsp;function arguments</h3>
 391 <p>
 392 The following default conversion rules apply when passing Lua objects
 393 to the variable argument part of vararg C&nbsp;functions:
 394 </p>
 395 <table class="convtable">
 396 <tr class="convhead">
 397 <td class="convin">Input</td>
 398 <td class="convop">Conversion</td>
 399 <td class="convout">Output</td>
 400 </tr>
 401 <tr class="odd separate">
 402 <td class="convin">number</td><td class="convop">&rarr;</td><td class="convout"><tt>double</tt></td></tr>
 403 <tr class="even">
 404 <td class="convin">boolean</td><td class="convop"><tt>false</tt> &rarr; 0, <tt>true</tt> &rarr; 1</td><td class="convout"><tt>bool</tt></td></tr>
 405 <tr class="odd separate">
 406 <td class="convin">nil</td><td class="convop"><tt>NULL</tt> &rarr;</td><td class="convout"><tt>(void *)</tt></td></tr>
 407 <tr class="even">
 408 <td class="convin">userdata</td><td class="convop">userdata payload &rarr;</td><td class="convout"><tt>(void *)</tt></td></tr>
 409 <tr class="odd">
 410 <td class="convin">lightuserdata</td><td class="convop">lightuserdata address &rarr;</td><td class="convout"><tt>(void *)</tt></td></tr>
 411 <tr class="even separate">
 412 <td class="convin">string</td><td class="convop">string data &rarr;</td><td class="convout"><tt>const char *</tt></td></tr>
 413 <tr class="odd separate">
 414 <td class="convin"><tt>float</tt> cdata</td><td class="convop">&rarr;</td><td class="convout"><tt>double</tt></td></tr>
 415 <tr class="even">
 416 <td class="convin">Array cdata</td><td class="convop">take base address</td><td class="convout">Element pointer</td></tr>
 417 <tr class="odd">
 418 <td class="convin"><tt>struct</tt>/<tt>union</tt> cdata</td><td class="convop">take base address</td><td class="convout"><tt>struct</tt>/<tt>union</tt> pointer</td></tr>
 419 <tr class="even">
 420 <td class="convin">Function cdata</td><td class="convop">take function address</td><td class="convout">Function pointer</td></tr>
 421 <tr class="odd">
 422 <td class="convin">Any other cdata</td><td class="convop">no conversion</td><td class="convout">C type</td></tr>
 423 </table>
 424 <p>
 425 To pass a Lua object, other than a cdata object, as a specific type,
 426 you need to override the conversion rules: create a temporary cdata
 427 object with a constructor or a cast and initialize it with the value
 428 to pass:
 429 </p>
 430 <p>
 431 Assuming <tt>x</tt> is a Lua number, here's how to pass it as an
 432 integer to a vararg function:
 433 </p>
 434 <pre class="code">
 435 ffi.cdef[[
 436 int printf(const char *fmt, ...);
 437 ]]
 438 ffi.C.printf("integer value: %d\n", ffi.new("int", x))
 439 </pre>
 440 <p>
 441 If you don't do this, the default Lua number &rarr; <tt>double</tt>
 442 conversion rule applies. A vararg C&nbsp;function expecting an integer
 443 will see a garbled or uninitialized value.
 444 </p>
 445
 446 <h2 id="init">Initializers</h2>
 447 <p>
 448 Creating a cdata object with
 449 <a href="ext_ffi_api.html#ffi_new"><tt>ffi.new()</tt></a> or the
 450 equivalent constructor syntax always initializes its contents, too.
 451 Different rules apply, depending on the number of optional
 452 initializers and the C&nbsp;types involved:
 453 </p>
 454 <ul>
 455 <li>If no initializers are given, the object is filled with zero bytes.</li>
 456
 457 <li>Scalar types (numbers and pointers) accept a single initializer.
 458 The Lua object is <a href="#convert_fromlua">converted to the scalar
 459 C&nbsp;type</a>.</li>
 460
 461 <li>Valarrays (complex numbers and vectors) are treated like scalars
 462 when a single initializer is given. Otherwise they are treated like
 463 regular arrays.</li>
 464
 465 <li>Aggregate types (arrays and structs) accept either a single cdata
 466 initializer of the same type (copy constructor), a single
 467 <a href="#init_table">table initializer</a>, or a flat list of
 468 initializers.</li>
 469
 470 <li>The elements of an array are initialized, starting at index zero.
 471 If a single initializer is given for an array, it's repeated for all
 472 remaining elements. This doesn't happen if two or more initializers
 473 are given: all remaining uninitialized elements are filled with zero
 474 bytes.</li>
 475
 476 <li>Byte arrays may also be initialized with a Lua string. This copies
 477 the whole string plus a terminating zero-byte. The copy stops early only
 478 if the array has a known, fixed size.</li>
 479
 480 <li>The fields of a <tt>struct</tt> are initialized in the order of
 481 their declaration. Uninitialized fields are filled with zero
 482 bytes.</li>
 483
 484 <li>Only the first field of a <tt>union</tt> can be initialized with a
 485 flat initializer.</li>
 486
 487 <li>Elements or fields which are aggregates themselves are initialized
 488 with a <em>single</em> initializer, but this may be a table
 489 initializer or a compatible aggregate.</li>
 490
 491 <li>Excess initializers cause an error.</li>
 492
 493 </ul>
 494
 495 <h2 id="init_table">Table Initializers</h2>
 496 <p>
 497 The following rules apply if a Lua table is used to initialize an
 498 Array or a <tt>struct</tt>/<tt>union</tt>:
 499 </p>
 500 <ul>
 501
 502 <li>If the table index <tt>[0]</tt> is non-<tt>nil</tt>, then the
 503 table is assumed to be zero-based. Otherwise it's assumed to be
 504 one-based.</li>
 505
 506 <li>Array elements, starting at index zero, are initialized one-by-one
 507 with the consecutive table elements, starting at either index
 508 <tt>[0]</tt> or <tt>[1]</tt>. This process stops at the first
 509 <tt>nil</tt> table element.</li>
 510
 511 <li>If exactly one array element was initialized, it's repeated for
 512 all the remaining elements. Otherwise all remaining uninitialized
 513 elements are filled with zero bytes.</li>
 514
 515 <li>The above logic only applies to arrays with a known fixed size.
 516 A VLA is only initialized with the element(s) given in the table.
 517 Depending on the use case, you may need to explicitly add a
 518 <tt>NULL</tt> or <tt>0</tt> terminator to a VLA.</li>
 519
 520 <li>A <tt>struct</tt>/<tt>union</tt> can be initialized in the
 521 order of the declaration of its fields. Each field is initialized with
 522 consecutive table elements, starting at either index <tt>[0]</tt>
 523 or <tt>[1]</tt>. This process stops at the first <tt>nil</tt> table
 524 element.</li>
 525
 526 <li>Otherwise, if neither index <tt>[0]</tt> nor <tt>[1]</tt> is present,
 527 a <tt>struct</tt>/<tt>union</tt> is initialized by looking up each field
 528 name (as a string key) in the table. Each non-<tt>nil</tt> value is
 529 used to initialize the corresponding field.</li>
 530
 531 <li>Uninitialized fields of a <tt>struct</tt> are filled with zero
 532 bytes, except for the trailing VLA of a VLS.</li>
 533
 534 <li>Initialization of a <tt>union</tt> stops after one field has been
 535 initialized. If no field has been initialized, the <tt>union</tt> is
 536 filled with zero bytes.</li>
 537
 538 <li>Elements or fields which are aggregates themselves are initialized
 539 with a <em>single</em> initializer, but this may be a nested table
 540 initializer (or a compatible aggregate).</li>
 541
 542 <li>Excess initializers for an array cause an error. Excess
 543 initializers for a <tt>struct</tt>/<tt>union</tt> are ignored.
 544 Unrelated table entries are ignored, too.</li>
 545
 546 </ul>
 547 <p>
 548 Example:
 549 </p>
 550 <pre class="code">
 551 local ffi = require("ffi")
 552
 553 ffi.cdef[[
 554 struct foo { int a, b; };
 555 union bar { int i; double d; };
 556 struct nested { int x; struct foo y; };
 557 ]]
 558
 559 ffi.new("int[3]", {})            --> 0, 0, 0
 560 ffi.new("int[3]", {1})           --> 1, 1, 1
 561 ffi.new("int[3]", {1,2})         --> 1, 2, 0
 562 ffi.new("int[3]", {1,2,3})       --> 1, 2, 3
 563 ffi.new("int[3]", {[0]=1})       --> 1, 1, 1
 564 ffi.new("int[3]", {[0]=1,2})     --> 1, 2, 0
 565 ffi.new("int[3]", {[0]=1,2,3})   --> 1, 2, 3
 566 ffi.new("int[3]", {[0]=1,2,3,4}) --> error: too many initializers
 567
 568 ffi.new("struct foo", {})            --> a = 0, b = 0
 569 ffi.new("struct foo", {1})           --> a = 1, b = 0
 570 ffi.new("struct foo", {1,2})         --> a = 1, b = 2
 571 ffi.new("struct foo", {[0]=1,2})     --> a = 1, b = 2
 572 ffi.new("struct foo", {b=2})         --> a = 0, b = 2
 573 ffi.new("struct foo", {a=1,b=2,c=3}) --> a = 1, b = 2  'c' is ignored
 574
 575 ffi.new("union bar", {})        --> i = 0, d = 0.0
 576 ffi.new("union bar", {1})       --> i = 1, d = ?
 577 ffi.new("union bar", {[0]=1,2}) --> i = 1, d = ?    '2' is ignored
 578 ffi.new("union bar", {d=2})     --> i = ?, d = 2.0
 579
 580 ffi.new("struct nested", {1,{2,3}})     --> x = 1, y.a = 2, y.b = 3
 581 ffi.new("struct nested", {x=1,y={2,3}}) --> x = 1, y.a = 2, y.b = 3
 582 </pre>
 583
 584 <h2 id="cdata_ops">Operations on cdata Objects</h2>
 585 <p>
 586 All of the standard Lua operators can be applied to cdata objects or a
 587 mix of a cdata object and another Lua object. The following list shows
 588 the pre-defined operations.
 589 </p>
 590 <p>
 591 Reference types are dereferenced <em>before</em> performing each of
 592 the operations below &mdash; the operation is applied to the
 593 C&nbsp;type pointed to by the reference.
 594 </p>
 595 <p>
 596 The pre-defined operations are always tried first before deferring to a
 597 metamethod or index table (if any) for the corresponding ctype (except
 598 for <tt>__new</tt>). An error is raised if the metamethod lookup or
 599 index table lookup fails.
 600 </p>
 601
 602 <h3 id="cdata_array">Indexing a cdata object</h3>
 603 <ul>
 604
 605 <li><b>Indexing a pointer/array</b>: a cdata pointer/array can be
 606 indexed by a cdata number or a Lua number. The element address is
 607 computed as the base address plus the number value multiplied by the
 608 element size in bytes. A read access loads the element value and
 609 <a href="#convert_tolua">converts it to a Lua object</a>. A write
 610 access <a href="#convert_fromlua">converts a Lua object to the element
 611 type</a> and stores the converted value to the element. An error is
 612 raised if the element size is undefined or a write access to a
 613 constant element is attempted.</li>
 614
 615 <li><b>Dereferencing a <tt>struct</tt>/<tt>union</tt> field</b>: a
 616 cdata <tt>struct</tt>/<tt>union</tt> or a pointer to a
 617 <tt>struct</tt>/<tt>union</tt> can be dereferenced by a string key,
 618 giving the field name. The field address is computed as the base
 619 address plus the relative offset of the field. A read access loads the
 620 field value and <a href="#convert_tolua">converts it to a Lua
 621 object</a>. A write access <a href="#convert_fromlua">converts a Lua
 622 object to the field type</a> and stores the converted value to the
 623 field. An error is raised if a write access to a constant
 624 <tt>struct</tt>/<tt>union</tt> or a constant field is attempted.
 625 Scoped enum constants or static constants are treated like a constant
 626 field.</li>
 627
 628 <li><b>Indexing a complex number</b>: a complex number can be indexed
 629 either by a cdata number or a Lua number with the values 0 or 1, or by
 630 the strings <tt>"re"</tt> or <tt>"im"</tt>. A read access loads the
 631 real part (<tt>[0]</tt>, <tt>.re</tt>) or the imaginary part
 632 (<tt>[1]</tt>, <tt>.im</tt>) part of a complex number and
 633 <a href="#convert_tolua">converts it to a Lua number</a>. The
 634 sub-parts of a complex number are immutable &mdash; assigning to an
 635 index of a complex number raises an error. Accessing out-of-bound
 636 indexes returns unspecified results, but is guaranteed not to trigger
 637 memory access violations.</li>
 638
 639 <li><b>Indexing a vector</b>: a vector is treated like an array for
 640 indexing purposes, except the vector elements are immutable &mdash;
 641 assigning to an index of a vector raises an error.</li>
 642
 643 </ul>
 644 <p>
 645 A ctype object can be indexed with a string key, too. The only
 646 pre-defined operation is reading scoped constants of
 647 <tt>struct</tt>/<tt>union</tt> types. All other accesses defer
 648 to the corresponding metamethods or index tables (if any).
 649 </p>
 650 <p>
 651 Note: since there's (deliberately) no address-of operator, a cdata
 652 object holding a value type is effectively immutable after
 653 initialization. The JIT compiler benefits from this fact when applying
 654 certain optimizations.
 655 </p>
 656 <p>
 657 As a consequence, the <em>elements</em> of complex numbers and
 658 vectors are immutable. But the elements of an aggregate holding these
 659 types <em>may</em> be modified of course. I.e. you cannot assign to
 660 <tt>foo.c.im</tt>, but you can assign a (newly created) complex number
 661 to <tt>foo.c</tt>.
 662 </p>
 663 <p>
 664 The JIT compiler implements strict aliasing rules: accesses to different
 665 types do <b>not</b> alias, except for differences in signedness (this
 666 applies even to <tt>char</tt> pointers, unlike C99). Type punning
 667 through unions is explicitly detected and allowed.
 668 </p>
 669
 670 <h3 id="cdata_call">Calling a cdata object</h3>
 671 <ul>
 672
 673 <li><b>Constructor</b>: a ctype object can be called and used as a
 674 <a href="ext_ffi_api.html#ffi_new">constructor</a>. This is equivalent
 675 to <tt>ffi.new(ct, ...)</tt>, unless a <tt>__new</tt> metamethod is
 676 defined. The <tt>__new</tt> metamethod is called with the ctype object
 677 plus any other arguments passed to the contructor. Note that you have to
 678 use <tt>ffi.new</tt> inside of it, since calling <tt>ct(...)</tt> would
 679 cause infinite recursion.</li>
 680
 681 <li><b>C&nbsp;function call</b>: a cdata function or cdata function
 682 pointer can be called. The passed arguments are
 683 <a href="#convert_fromlua">converted to the C&nbsp;types</a> of the
 684 parameters given by the function declaration. Arguments passed to the
 685 variable argument part of vararg C&nbsp;function use
 686 <a href="#convert_vararg">special conversion rules</a>. This
 687 C&nbsp;function is called and the return value (if any) is
 688 <a href="#convert_tolua">converted to a Lua object</a>.<br>
 689 On Windows/x86 systems, <tt>__stdcall</tt> functions are automatically
 690 detected and a function declared as <tt>__cdecl</tt> (the default) is
 691 silently fixed up after the first call.</li>
 692
 693 </ul>
 694
 695 <h3 id="cdata_arith">Arithmetic on cdata objects</h3>
 696 <ul>
 697
 698 <li><b>Pointer arithmetic</b>: a cdata pointer/array and a cdata
 699 number or a Lua number can be added or subtracted. The number must be
 700 on the right hand side for a subtraction. The result is a pointer of
 701 the same type with an address plus or minus the number value
 702 multiplied by the element size in bytes. An error is raised if the
 703 element size is undefined.</li>
 704
 705 <li><b>Pointer difference</b>: two compatible cdata pointers/arrays
 706 can be subtracted. The result is the difference between their
 707 addresses, divided by the element size in bytes. An error is raised if
 708 the element size is undefined or zero.</li>
 709
 710 <li><b>64&nbsp;bit integer arithmetic</b>: the standard arithmetic
 711 operators (<tt>+&nbsp;-&nbsp;*&nbsp;/&nbsp;%&nbsp;^</tt> and unary
 712 minus) can be applied to two cdata numbers, or a cdata number and a
 713 Lua number. If one of them is an <tt>uint64_t</tt>, the other side is
 714 converted to an <tt>uint64_t</tt> and an unsigned arithmetic operation
 715 is performed. Otherwise both sides are converted to an
 716 <tt>int64_t</tt> and a signed arithmetic operation is performed. The
 717 result is a boxed 64&nbsp;bit cdata object.<br>
 718
 719 If one of the operands is an <tt>enum</tt> and the other operand is a
 720 string, the string is converted to the value of a matching <tt>enum</tt>
 721 constant before the above conversion.<br>
 722
 723 These rules ensure that 64&nbsp;bit integers are "sticky". Any
 724 expression involving at least one 64&nbsp;bit integer operand results
 725 in another one. The undefined cases for the division, modulo and power
 726 operators return <tt>2LL&nbsp;^&nbsp;63</tt> or
 727 <tt>2ULL&nbsp;^&nbsp;63</tt>.<br>
 728
 729 You'll have to explicitly convert a 64&nbsp;bit integer to a Lua
 730 number (e.g. for regular floating-point calculations) with
 731 <tt>tonumber()</tt>. But note this may incur a precision loss.</li>
 732
 733 </ul>
 734
 735 <h3 id="cdata_comp">Comparisons of cdata objects</h3>
 736 <ul>
 737
 738 <li><b>Pointer comparison</b>: two compatible cdata pointers/arrays
 739 can be compared. The result is the same as an unsigned comparison of
 740 their addresses. <tt>nil</tt> is treated like a <tt>NULL</tt> pointer,
 741 which is compatible with any other pointer type.</li>
 742
 743 <li><b>64&nbsp;bit integer comparison</b>: two cdata numbers, or a
 744 cdata number and a Lua number can be compared with each other. If one
 745 of them is an <tt>uint64_t</tt>, the other side is converted to an
 746 <tt>uint64_t</tt> and an unsigned comparison is performed. Otherwise
 747 both sides are converted to an <tt>int64_t</tt> and a signed
 748 comparison is performed.<br>
 749
 750 If one of the operands is an <tt>enum</tt> and the other operand is a
 751 string, the string is converted to the value of a matching <tt>enum</tt>
 752 constant before the above conversion.<br>
 753
 754 <li><b>Comparisons for equality/inequality</b> never raise an error.
 755 Even incompatible pointers can be compared for equality by address. Any
 756 other incompatible comparison (also with non-cdata objects) treats the
 757 two sides as unequal.</li>
 758
 759 </ul>
 760
 761 <h3 id="cdata_key">cdata objects as table keys</h3>
 762 <p>
 763 Lua tables may be indexed by cdata objects, but this doesn't provide
 764 any useful semantics &mdash; <b>cdata objects are unsuitable as table
 765 keys!</b>
 766 </p>
 767 <p>
 768 A cdata object is treated like any other garbage-collected object and
 769 is hashed and compared by its address for table indexing. Since
 770 there's no interning for cdata value types, the same value may be
 771 boxed in different cdata objects with different addresses. Thus
 772 <tt>t[1LL+1LL]</tt> and <tt>t[2LL]</tt> usually <b>do not</b> point to
 773 the same hash slot and they certainly <b>do not</b> point to the same
 774 hash slot as <tt>t[2]</tt>.
 775 </p>
 776 <p>
 777 It would seriously drive up implementation complexity and slow down
 778 the common case, if one were to add extra handling for by-value
 779 hashing and comparisons to Lua tables. Given the ubiquity of their use
 780 inside the VM, this is not acceptable.
 781 </p>
 782 <p>
 783 There are three viable alternatives, if you really need to use cdata
 784 objects as keys:
 785 </p>
 786 <ul>
 787
 788 <li>If you can get by with the precision of Lua numbers
 789 (52&nbsp;bits), then use <tt>tonumber()</tt> on a cdata number or
 790 combine multiple fields of a cdata aggregate to a Lua number. Then use
 791 the resulting Lua number as a key when indexing tables.<br>
 792 One obvious benefit: <tt>t[tonumber(2LL)]</tt> <b>does</b> point to
 793 the same slot as <tt>t[2]</tt>.</li>
 794
 795 <li>Otherwise use either <tt>tostring()</tt> on 64&nbsp;bit integers
 796 or complex numbers or combine multiple fields of a cdata aggregate to
 797 a Lua string (e.g. with
 798 <a href="ext_ffi_api.html#ffi_string"><tt>ffi.string()</tt></a>). Then
 799 use the resulting Lua string as a key when indexing tables.</li>
 800
 801 <li>Create your own specialized hash table implementation using the
 802 C&nbsp;types provided by the FFI library, just like you would in
 803 C&nbsp;code. Ultimately this may give much better performance than the
 804 other alternatives or what a generic by-value hash table could
 805 possibly provide.</li>
 806
 807 </ul>
 808
 809 <h2 id="param">Parameterized Types</h2>
 810 <p>
 811 To facilitate some abstractions, the two functions
 812 <a href="ext_ffi_api.html#ffi_typeof"><tt>ffi.typeof</tt></a> and
 813 <a href="ext_ffi_api.html#ffi_cdef"><tt>ffi.cdef</tt></a> support
 814 parameterized types in C&nbsp;declarations. Note: none of the other API
 815 functions taking a cdecl allow this.
 816 </p>
 817 <p>
 818 Any place you can write a <b><tt>typedef</tt> name</b>, an
 819 <b>identifier</b> or a <b>number</b> in a declaration, you can write
 820 <tt>$</tt> (the dollar sign) instead. These placeholders are replaced in
 821 order of appearance with the arguments following the cdecl string:
 822 </p>
 823 <pre class="code">
 824 -- Declare a struct with a parameterized field type and name:
 825 ffi.cdef([[
 826 typedef struct { $ $; } foo_t;
 827 ]], type1, name1)
 828
 829 -- Anonymous struct with dynamic names:
 830 local bar_t = ffi.typeof("struct { int $, $; }", name1, name2)
 831 -- Derived pointer type:
 832 local bar_ptr_t = ffi.typeof("$ *", bar_t)
 833
 834 -- Parameterized dimensions work even where a VLA won't work:
 835 local matrix_t = ffi.typeof("uint8_t[$][$]", width, height)
 836 </pre>
 837 <p>
 838 Caveat: this is <em>not</em> simple text substitution! A passed ctype or
 839 cdata object is treated like the underlying type, a passed string is
 840 considered an identifier and a number is considered a number. You must
 841 not mix this up: e.g. passing <tt>"int"</tt> as a string doesn't work in
 842 place of a type, you'd need to use <tt>ffi.typeof("int")</tt> instead.
 843 </p>
 844 <p>
 845 The main use for parameterized types are libraries implementing abstract
 846 data types
 847 (<a href="https://www.freelists.org/post/luajit/ffi-type-of-pointer-to,8">example</a>),
 848 similar to what can be achieved with C++ template metaprogramming.
 849 Another use case are derived types of anonymous structs, which avoids
 850 pollution of the global struct namespace.
 851 </p>
 852 <p>
 853 Please note that parameterized types are a nice tool and indispensable
 854 for certain use cases. But you'll want to use them sparingly in regular
 855 code, e.g. when all types are actually fixed.
 856 </p>
 857
 858 <h2 id="gc">Garbage Collection of cdata Objects</h2>
 859 <p>
 860 All explicitly (<tt>ffi.new()</tt>, <tt>ffi.cast()</tt> etc.) or
 861 implicitly (accessors) created cdata objects are garbage collected.
 862 You need to ensure to retain valid references to cdata objects
 863 somewhere on a Lua stack, an upvalue or in a Lua table while they are
 864 still in use. Once the last reference to a cdata object is gone, the
 865 garbage collector will automatically free the memory used by it (at
 866 the end of the next GC cycle).
 867 </p>
 868 <p>
 869 Please note that pointers themselves are cdata objects, however they
 870 are <b>not</b> followed by the garbage collector. So e.g. if you
 871 assign a cdata array to a pointer, you must keep the cdata object
 872 holding the array alive as long as the pointer is still in use:
 873 </p>
 874 <pre class="code">
 875 ffi.cdef[[
 876 typedef struct { int *a; } foo_t;
 877 ]]
 878
 879 local s = ffi.new("foo_t", ffi.new("int[10]")) -- <span style="color:#c00000;">WRONG!</span>
 880
 881 local a = ffi.new("int[10]") -- <span style="color:#00a000;">OK</span>
 882 local s = ffi.new("foo_t", a)
 883 -- Now do something with 's', but keep 'a' alive until you're done.
 884 </pre>
 885 <p>
 886 Similar rules apply for Lua strings which are implicitly converted to
 887 <tt>"const&nbsp;char&nbsp;*"</tt>: the string object itself must be
 888 referenced somewhere or it'll be garbage collected eventually. The
 889 pointer will then point to stale data, which may have already been
 890 overwritten. Note that <em>string literals</em> are automatically kept
 891 alive as long as the function containing it (actually its prototype)
 892 is not garbage collected.
 893 </p>
 894 <p>
 895 Objects which are passed as an argument to an external C&nbsp;function
 896 are kept alive until the call returns. So it's generally safe to
 897 create temporary cdata objects in argument lists. This is a common
 898 idiom for <a href="#convert_vararg">passing specific C&nbsp;types to
 899 vararg functions</a>.
 900 </p>
 901 <p>
 902 Memory areas returned by C functions (e.g. from <tt>malloc()</tt>)
 903 must be manually managed, of course (or use
 904 <a href="ext_ffi_api.html#ffi_gc"><tt>ffi.gc()</tt></a>). Pointers to
 905 cdata objects are indistinguishable from pointers returned by C
 906 functions (which is one of the reasons why the GC cannot follow them).
 907 </p>
 908
 909 <h2 id="callback">Callbacks</h2>
 910 <p>
 911 The LuaJIT FFI automatically generates special callback functions
 912 whenever a Lua function is converted to a C&nbsp;function pointer. This
 913 associates the generated callback function pointer with the C&nbsp;type
 914 of the function pointer and the Lua function object (closure).
 915 </p>
 916 <p>
 917 This can happen implicitly due to the usual conversions, e.g. when
 918 passing a Lua function to a function pointer argument. Or you can use
 919 <tt>ffi.cast()</tt> to explicitly cast a Lua function to a
 920 C&nbsp;function pointer.
 921 </p>
 922 <p>
 923 Currently only certain C&nbsp;function types can be used as callback
 924 functions. Neither C&nbsp;vararg functions nor functions with
 925 pass-by-value aggregate argument or result types are supported. There
 926 are no restrictions for the kind of Lua functions that can be called
 927 from the callback &mdash; no checks for the proper number of arguments
 928 are made. The return value of the Lua function will be converted to the
 929 result type and an error will be thrown for invalid conversions.
 930 </p>
 931 <p>
 932 It's allowed to throw errors across a callback invocation, but it's not
 933 advisable in general. Do this only if you know the C&nbsp;function, that
 934 called the callback, copes with the forced stack unwinding and doesn't
 935 leak resources.
 936 </p>
 937 <p>
 938 One thing that's not allowed, is to let an FFI call into a C&nbsp;function
 939 get JIT-compiled, which in turn calls a callback, calling into Lua again.
 940 Usually this attempt is caught by the interpreter first and the
 941 C&nbsp;function is blacklisted for compilation.
 942 </p>
 943 <p>
 944 However, this heuristic may fail under specific circumstances: e.g. a
 945 message polling function might not run Lua callbacks right away and the call
 946 gets JIT-compiled. If it later happens to call back into Lua (e.g. a rarely
 947 invoked error callback), you'll get a VM PANIC with the message
 948 <tt>"bad callback"</tt>. Then you'll need to manually turn off
 949 JIT-compilation with
 950 <a href="ext_jit.html#jit_onoff_func"><tt>jit.off()</tt></a> for the
 951 surrounding Lua function that invokes such a message polling function (or
 952 similar).
 953 </p>
 954
 955 <h3 id="callback_resources">Callback resource handling</h3>
 956 <p>
 957 Callbacks take up resources &mdash; you can only have a limited number
 958 of them at the same time (500&nbsp;-&nbsp;1000, depending on the
 959 architecture). The associated Lua functions are anchored to prevent
 960 garbage collection, too.
 961 </p>
 962 <p>
 963 <b>Callbacks due to implicit conversions are permanent!</b> There is no
 964 way to guess their lifetime, since the C&nbsp;side might store the
 965 function pointer for later use (typical for GUI toolkits). The associated
 966 resources cannot be reclaimed until termination:
 967 </p>
 968 <pre class="code">
 969 ffi.cdef[[
 970 typedef int (__stdcall *WNDENUMPROC)(void *hwnd, intptr_t l);
 971 int EnumWindows(WNDENUMPROC func, intptr_t l);
 972 ]]
 973
 974 -- Implicit conversion to a callback via function pointer argument.
 975 local count = 0
 976 ffi.C.EnumWindows(function(hwnd, l)
 977   count = count + 1
 978   return true
 979 end, 0)
 980 -- The callback is permanent and its resources cannot be reclaimed!
 981 -- Ok, so this may not be a problem, if you do this only once.
 982 </pre>
 983 <p>
 984 Note: this example shows that you <em>must</em> properly declare
 985 <tt>__stdcall</tt> callbacks on Windows/x86 systems. The calling
 986 convention cannot be automatically detected, unlike for
 987 <tt>__stdcall</tt> calls <em>to</em> Windows functions.
 988 </p>
 989 <p>
 990 For some use cases it's necessary to free up the resources or to
 991 dynamically redirect callbacks. Use an explicit cast to a
 992 C&nbsp;function pointer and keep the resulting cdata object. Then use
 993 the <a href="ext_ffi_api.html#callback_free"><tt>cb:free()</tt></a>
 994 or <a href="ext_ffi_api.html#callback_set"><tt>cb:set()</tt></a> methods
 995 on the cdata object:
 996 </p>
 997 <pre class="code">
 998 -- Explicitly convert to a callback via cast.
 999 local count = 0
1000 local cb = ffi.cast("WNDENUMPROC", function(hwnd, l)
1001   count = count + 1
1002   return true
1003 end)
1004
1005 -- Pass it to a C function.
1006 ffi.C.EnumWindows(cb, 0)
1007 -- EnumWindows doesn't need the callback after it returns, so free it.
1008
1009 cb:free()
1010 -- The callback function pointer is no longer valid and its resources
1011 -- will be reclaimed. The created Lua closure will be garbage collected.
1012 </pre>
1013
1014 <h3 id="callback_performance">Callback performance</h3>
1015 <p>
1016 <b>Callbacks are slow!</b> First, the C&nbsp;to Lua transition itself
1017 has an unavoidable cost, similar to a <tt>lua_call()</tt> or
1018 <tt>lua_pcall()</tt>. Argument and result marshalling add to that cost.
1019 And finally, neither the C&nbsp;compiler nor LuaJIT can inline or
1020 optimize across the language barrier and hoist repeated computations out
1021 of a callback function.
1022 </p>
1023 <p>
1024 Do not use callbacks for performance-sensitive work: e.g. consider a
1025 numerical integration routine which takes a user-defined function to
1026 integrate over. It's a bad idea to call a user-defined Lua function from
1027 C&nbsp;code millions of times. The callback overhead will be absolutely
1028 detrimental for performance.
1029 </p>
1030 <p>
1031 It's considerably faster to write the numerical integration routine
1032 itself in Lua &mdash; the JIT compiler will be able to inline the
1033 user-defined function and optimize it together with its calling context,
1034 with very competitive performance.
1035 </p>
1036 <p>
1037 As a general guideline: <b>use callbacks only when you must</b>, because
1038 of existing C&nbsp;APIs. E.g. callback performance is irrelevant for a
1039 GUI application, which waits for user input most of the time, anyway.
1040 </p>
1041 <p>
1042 For new designs <b>avoid push-style APIs</b>: a C&nbsp;function repeatedly
1043 calling a callback for each result. Instead <b>use pull-style APIs</b>:
1044 call a C&nbsp;function repeatedly to get a new result. Calls from Lua
1045 to C via the FFI are much faster than the other way round. Most well-designed
1046 libraries already use pull-style APIs (read/write, get/put).
1047 </p>
1048
1049 <h2 id="clib">C Library Namespaces</h2>
1050 <p>
1051 A C&nbsp;library namespace is a special kind of object which allows
1052 access to the symbols contained in shared libraries or the default
1053 symbol namespace. The default
1054 <a href="ext_ffi_api.html#ffi_C"><tt>ffi.C</tt></a> namespace is
1055 automatically created when the FFI library is loaded. C&nbsp;library
1056 namespaces for specific shared libraries may be created with the
1057 <a href="ext_ffi_api.html#ffi_load"><tt>ffi.load()</tt></a> API
1058 function.
1059 </p>
1060 <p>
1061 Indexing a C&nbsp;library namespace object with a symbol name (a Lua
1062 string) automatically binds it to the library. First the symbol type
1063 is resolved &mdash; it must have been declared with
1064 <a href="ext_ffi_api.html#ffi_cdef"><tt>ffi.cdef</tt></a>. Then the
1065 symbol address is resolved by searching for the symbol name in the
1066 associated shared libraries or the default symbol namespace. Finally,
1067 the resulting binding between the symbol name, the symbol type and its
1068 address is cached. Missing symbol declarations or nonexistent symbol
1069 names cause an error.
1070 </p>
1071 <p>
1072 This is what happens on a <b>read access</b> for the different kinds of
1073 symbols:
1074 </p>
1075 <ul>
1076
1077 <li>External functions: a cdata object with the type of the function
1078 and its address is returned.</li>
1079
1080 <li>External variables: the symbol address is dereferenced and the
1081 loaded value is <a href="#convert_tolua">converted to a Lua object</a>
1082 and returned.</li>
1083
1084 <li>Constant values (<tt>static&nbsp;const</tt> or <tt>enum</tt>
1085 constants): the constant is <a href="#convert_tolua">converted to a
1086 Lua object</a> and returned.</li>
1087
1088 </ul>
1089 <p>
1090 This is what happens on a <b>write access</b>:
1091 </p>
1092 <ul>
1093
1094 <li>External variables: the value to be written is
1095 <a href="#convert_fromlua">converted to the C&nbsp;type</a> of the
1096 variable and then stored at the symbol address.</li>
1097
1098 <li>Writing to constant variables or to any other symbol type causes
1099 an error, like any other attempted write to a constant location.</li>
1100
1101 </ul>
1102 <p>
1103 C&nbsp;library namespaces themselves are garbage collected objects. If
1104 the last reference to the namespace object is gone, the garbage
1105 collector will eventually release the shared library reference and
1106 remove all memory associated with the namespace. Since this may
1107 trigger the removal of the shared library from the memory of the
1108 running process, it's generally <em>not safe</em> to use function
1109 cdata objects obtained from a library if the namespace object may be
1110 unreferenced.
1111 </p>
1112 <p>
1113 Performance notice: the JIT compiler specializes to the identity of
1114 namespace objects and to the strings used to index it. This
1115 effectively turns function cdata objects into constants. It's not
1116 useful and actually counter-productive to explicitly cache these
1117 function objects, e.g. <tt>local strlen = ffi.C.strlen</tt>. OTOH it
1118 <em>is</em> useful to cache the namespace itself, e.g. <tt>local C =
1119 ffi.C</tt>.
1120 </p>
1121
1122 <h2 id="policy">No Hand-holding!</h2>
1123 <p>
1124 The FFI library has been designed as <b>a low-level library</b>. The
1125 goal is to interface with C&nbsp;code and C&nbsp;data types with a
1126 minimum of overhead. This means <b>you can do anything you can do
1127 from&nbsp;C</b>: access all memory, overwrite anything in memory, call
1128 machine code at any memory address and so on.
1129 </p>
1130 <p>
1131 The FFI library provides <b>no memory safety</b>, unlike regular Lua
1132 code. It will happily allow you to dereference a <tt>NULL</tt>
1133 pointer, to access arrays out of bounds or to misdeclare
1134 C&nbsp;functions. If you make a mistake, your application might crash,
1135 just like equivalent C&nbsp;code would.
1136 </p>
1137 <p>
1138 This behavior is inevitable, since the goal is to provide full
1139 interoperability with C&nbsp;code. Adding extra safety measures, like
1140 bounds checks, would be futile. There's no way to detect
1141 misdeclarations of C&nbsp;functions, since shared libraries only
1142 provide symbol names, but no type information. Likewise there's no way
1143 to infer the valid range of indexes for a returned pointer.
1144 </p>
1145 <p>
1146 Again: the FFI library is a low-level library. This implies it needs
1147 to be used with care, but it's flexibility and performance often
1148 outweigh this concern. If you're a C or C++ developer, it'll be easy
1149 to apply your existing knowledge. OTOH writing code for the FFI
1150 library is not for the faint of heart and probably shouldn't be the
1151 first exercise for someone with little experience in Lua, C or C++.
1152 </p>
1153 <p>
1154 As a corollary of the above, the FFI library is <b>not safe for use by
1155 untrusted Lua code</b>. If you're sandboxing untrusted Lua code, you
1156 definitely don't want to give this code access to the FFI library or
1157 to <em>any</em> cdata object (except 64&nbsp;bit integers or complex
1158 numbers). Any properly engineered Lua sandbox needs to provide safety
1159 wrappers for many of the standard Lua library functions &mdash;
1160 similar wrappers need to be written for high-level operations on FFI
1161 data types, too.
1162 </p>
1163
1164 <h2 id="status">Current Status</h2>
1165 <p>
1166 The initial release of the FFI library has some limitations and is
1167 missing some features. Most of these will be fixed in future releases.
1168 </p>
1169 <p>
1170 <a href="#clang">C language support</a> is
1171 currently incomplete:
1172 </p>
1173 <ul>
1174 <li>C&nbsp;declarations are not passed through a C&nbsp;pre-processor,
1175 yet.</li>
1176 <li>The C&nbsp;parser is able to evaluate most constant expressions
1177 commonly found in C&nbsp;header files. However it doesn't handle the
1178 full range of C&nbsp;expression semantics and may fail for some
1179 obscure constructs.</li>
1180 <li><tt>static const</tt> declarations only work for integer types
1181 up to 32&nbsp;bits. Neither declaring string constants nor
1182 floating-point constants is supported.</li>
1183 <li>Packed <tt>struct</tt> bitfields that cross container boundaries
1184 are not implemented.</li>
1185 <li>Native vector types may be defined with the GCC <tt>mode</tt> or
1186 <tt>vector_size</tt> attribute. But no operations other than loading,
1187 storing and initializing them are supported, yet.</li>
1188 <li>The <tt>volatile</tt> type qualifier is currently ignored by
1189 compiled code.</li>
1190 <li><a href="ext_ffi_api.html#ffi_cdef"><tt>ffi.cdef</tt></a> silently
1191 ignores most re-declarations. Note: avoid re-declarations which do not
1192 conform to C99. The implementation will eventually be changed to
1193 perform strict checks.</li>
1194 </ul>
1195 <p>
1196 The JIT compiler already handles a large subset of all FFI operations.
1197 It automatically falls back to the interpreter for unimplemented
1198 operations (you can check for this with the
1199 <a href="running.html#opt_j"><tt>-jv</tt></a> command line option).
1200 The following operations are currently not compiled and may exhibit
1201 suboptimal performance, especially when used in inner loops:
1202 </p>
1203 <ul>
1204 <li>Bitfield accesses and initializations.</li>
1205 <li>Vector operations.</li>
1206 <li>Table initializers.</li>
1207 <li>Initialization of nested <tt>struct</tt>/<tt>union</tt> types.</li>
1208 <li>Allocations of variable-length arrays or structs.</li>
1209 <li>Allocations of C&nbsp;types with a size &gt; 128&nbsp;bytes or an
1210 alignment &gt; 8&nbsp;bytes.</li>
1211 <li>Conversions from lightuserdata to <tt>void&nbsp;*</tt>.</li>
1212 <li>Pointer differences for element sizes that are not a power of
1213 two.</li>
1214 <li>Calls to C&nbsp;functions with aggregates passed or returned by
1215 value.</li>
1216 <li>Calls to ctype metamethods which are not plain functions.</li>
1217 <li>ctype <tt>__newindex</tt> tables and non-string lookups in ctype
1218 <tt>__index</tt> tables.</li>
1219 <li><tt>tostring()</tt> for cdata types.</li>
1220 <li>Calls to <tt>ffi.cdef()</tt>, <tt>ffi.load()</tt> and
1221 <tt>ffi.metatype()</tt>.</li>
1222 </ul>
1223 <p>
1224 Other missing features:
1225 </p>
1226 <ul>
1227 <li>Bit operations for 64&nbsp;bit types.</li>
1228 <li>Arithmetic for <tt>complex</tt> numbers.</li>
1229 <li>Passing structs by value to vararg C&nbsp;functions.</li>
1230 <li><a href="extensions.html#exceptions">C++ exception interoperability</a>
1231 does not extend to C&nbsp;functions called via the FFI, if the call is
1232 compiled.</li>
1233 </ul>
1234 <br class="flush">
1235 </div>
1236 <div id="foot">
1237 <hr class="hide">
1238 Copyright &copy; 2005-2017 Mike Pall
1239 <span class="noprint">
1240 &middot;
1241 <a href="contact.html">Contact</a>
1242 </span>
1243 </div>
1244 </body>
1245 </html>