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