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