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