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 </head>
  12 <body>
  13 <div id="site">
  14 <a href="http://luajit.org"><span>Lua<span id="logo">JIT</span></span></a>
  15 </div>
  16 <div id="head">
  17 <h1>FFI Semantics</h1>
  18 </div>
  19 <div id="nav">
  20 <ul><li>
  21 <a href="luajit.html">LuaJIT</a>
  22 <ul><li>
  23 <a href="install.html">Installation</a>
  24 </li><li>
  25 <a href="running.html">Running</a>
  26 </li></ul>
  27 </li><li>
  28 <a href="extensions.html">Extensions</a>
  29 <ul><li>
  30 <a href="ext_ffi.html">FFI Library</a>
  31 <ul><li>
  32 <a href="ext_ffi_tutorial.html">FFI Tutorial</a>
  33 </li><li>
  34 <a href="ext_ffi_api.html">ffi.* API</a>
  35 </li><li>
  36 <a href="ext_ffi_int64.html">64 bit Integers</a>
  37 </li><li>
  38 <a class="current" href="ext_ffi_semantics.html">FFI Semantics</a>
  39 </li></ul>
  40 </li><li>
  41 <a href="ext_jit.html">jit.* Library</a>
  42 </li><li>
  43 <a href="ext_c_api.html">Lua/C API</a>
  44 </li></ul>
  45 </li><li>
  46 <a href="status.html">Status</a>
  47 <ul><li>
  48 <a href="changes.html">Changes</a>
  49 </li></ul>
  50 </li><li>
  51 <a href="faq.html">FAQ</a>
  52 </li><li>
  53 <a href="http://luajit.org/performance.html">Performance <span class="ext">&raquo;</span></a>
  54 </li><li>
  55 <a href="http://luajit.org/download.html">Download <span class="ext">&raquo;</span></a>
  56 </li></ul>
  57 </div>
  58 <div id="main">
  59 <p>
  60 TODO
  61 </p>
  62
  63 <h2 id="clang">C Language Support</h2>
  64 <p>
  65 TODO
  66 </p>
  67
  68 <h2 id="convert">C Type Conversion Rules</h2>
  69 <p>
  70 TODO
  71 </p>
  72
  73 <h2 id="init">Initializers</h2>
  74 <p>
  75 Creating a cdata object with <a href="ffi_ext_api.html#ffi_new">ffi.new()</a>
  76 or the equivalent constructor syntax always initializes its contents,
  77 too. Different rules apply, depending on the number of optional
  78 initializers and the C&nbsp;types involved:
  79 </p>
  80 <ul>
  81 <li>If no initializers are given, the object is filled with zero bytes.</li>
  82
  83 <li>Scalar types (numbers and pointers) accept a single initializer.
  84 The standard <a href="#convert">C&nbsp;type conversion rules</a>
  85 apply.</li>
  86
  87 <li>Valarrays (complex numbers and vectors) are treated like scalars
  88 when a single initializer is given. Otherwise they are treated like
  89 regular arrays.</li>
  90
  91 <li>Aggregate types (arrays and structs) accept either a single
  92 compound initializer (Lua table or string) or a flat list of
  93 initializers.</li>
  94
  95 <li>The elements of an array are initialized, starting at index zero.
  96 If a single initializer is given for an array, it's repeated for all
  97 remaining elements. This doesn't happen if two or more initializers
  98 are given: all remaining uninitialized elements are filled with zero
  99 bytes.</li>
 100
 101 <li>The fields of a <tt>struct</tt> are initialized in the order of
 102 their declaration. Uninitialized fields are filled with zero
 103 bytes.</li>
 104
 105 <li>Only the first field of a <tt>union</tt> can be initialized with a
 106 flat initializer.</li>
 107
 108 <li>Elements or fields which are aggregates themselves are initialized
 109 with a <em>single</em> initializer, but this may be a compound
 110 initializer or a compatible aggregate, of course.</li>
 111
 112 </ul>
 113
 114 <h2 id="clib">C Library Namespaces</h2>
 115 <p>
 116 A C&nbsp;library namespace is a special kind of object which allows
 117 access to the symbols contained in libraries. Indexing it with a
 118 symbol name (a Lua string) automatically binds it to the library.
 119 </p>
 120 <p>
 121 TODO
 122 </p>
 123
 124 <h2 id="ops">Operations on cdata Objects</h2>
 125 <p>
 126 TODO
 127 </p>
 128
 129 <h2 id="gc">Garbage Collection of cdata Objects</h2>
 130 <p>
 131 All explicitly (<tt>ffi.new()</tt> etc.) or implicitly (accessors)
 132 created cdata objects are garbage collected. You need to ensure to
 133 retain valid references to cdata objects somewhere on a Lua stack, an
 134 upvalue or in a Lua table while they are still in use. Once the last
 135 reference to a cdata object is gone, the garbage collector will
 136 automatically free the memory used by it (at the end of the next GC
 137 cycle).
 138 </p>
 139 <p>
 140 Please note that pointers themselves are cdata objects, however they
 141 are <b>not</b> followed by the garbage collector. So e.g. if you
 142 assign a cdata array to a pointer, you must keep the cdata object
 143 holding the array alive as long as the pointer is still in use:
 144 </p>
 145 <pre class="code">
 146 ffi.cdef[[
 147 typedef struct { int *a; } foo_t;
 148 ]]
 149
 150 local s = ffi.new("foo_t", ffi.new("int[10]")) -- <span style="color:#c00000;">WRONG!</span>
 151
 152 local a = ffi.new("int[10]") -- <span style="color:#00a000;">OK</span>
 153 local s = ffi.new("foo_t", a)
 154 -- Now do something with 's', but keep 'a' alive until you're done.
 155 </pre>
 156 <p>
 157 Similar rules apply for Lua strings which are implicitly converted to
 158 <tt>"const&nbsp;char&nbsp;*"</tt>: the string object itself must be
 159 referenced somewhere or it'll be garbage collected eventually. The
 160 pointer will then point to stale data, which may have already beeen
 161 overwritten. Note that string literals are automatically kept alive as
 162 long as the function containing it (actually its prototype) is not
 163 garbage collected.
 164 </p>
 165 <p>
 166 Objects which are passed as an argument to an external C&nbsp;function
 167 are kept alive until the call returns. So it's generally safe to
 168 create temporary cdata objects in argument lists. This is a common
 169 idiom for passing specific C&nbsp;types to vararg functions:
 170 </p>
 171 <pre class="code">
 172 ffi.cdef[[
 173 int printf(const char *fmt, ...);
 174 ]]
 175 ffi.C.printf("integer value: %d\n", ffi.new("int", x)) -- <span style="color:#00a000;">OK</span>
 176 </pre>
 177 <p>
 178 Memory areas returned by C functions (e.g. from <tt>malloc()</tt>)
 179 must be manually managed of course. Pointers to cdata objects are
 180 indistinguishable from pointers returned by C functions (which is one
 181 of the reasons why the GC cannot follow them).
 182 </p>
 183
 184 <h2>TODO</h2>
 185 <br class="flush">
 186 </div>
 187 <div id="foot">
 188 <hr class="hide">
 189 Copyright &copy; 2005-2011 Mike Pall
 190 <span class="noprint">
 191 &middot;
 192 <a href="contact.html">Contact</a>
 193 </span>
 194 </div>
 195 </body>
 196 </html>