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