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