doc/ext_ffi_tutorial.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 Tutorial</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-2013, 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.idiomtable { font-size: 90%; line-height: 1.2; }
  13 table.idiomtable tt { font-size: 100%; }
  14 table.idiomtable td { vertical-align: top; }
  15 tr.idiomhead td { font-weight: bold; }
  16 td.idiomlua b { font-weight: normal; color: #2142bf; }
  17 </style>
  18 </head>
  19 <body>
  20 <div id="site">
  21 <a href="http://luajit.org"><span>Lua<span id="logo">JIT</span></span></a>
  22 </div>
  23 <div id="head">
  24 <h1>FFI Tutorial</h1>
  25 </div>
  26 <div id="nav">
  27 <ul><li>
  28 <a href="luajit.html">LuaJIT</a>
  29 <ul><li>
  30 <a href="http://luajit.org/download.html">Download <span class="ext">&raquo;</span></a>
  31 </li><li>
  32 <a href="install.html">Installation</a>
  33 </li><li>
  34 <a href="running.html">Running</a>
  35 </li></ul>
  36 </li><li>
  37 <a href="extensions.html">Extensions</a>
  38 <ul><li>
  39 <a href="ext_ffi.html">FFI Library</a>
  40 <ul><li>
  41 <a class="current" href="ext_ffi_tutorial.html">FFI Tutorial</a>
  42 </li><li>
  43 <a href="ext_ffi_api.html">ffi.* API</a>
  44 </li><li>
  45 <a href="ext_ffi_semantics.html">FFI Semantics</a>
  46 </li></ul>
  47 </li><li>
  48 <a href="ext_jit.html">jit.* Library</a>
  49 </li><li>
  50 <a href="ext_c_api.html">Lua/C API</a>
  51 </li></ul>
  52 </li><li>
  53 <a href="status.html">Status</a>
  54 <ul><li>
  55 <a href="changes.html">Changes</a>
  56 </li></ul>
  57 </li><li>
  58 <a href="faq.html">FAQ</a>
  59 </li><li>
  60 <a href="http://luajit.org/performance.html">Performance <span class="ext">&raquo;</span></a>
  61 </li><li>
  62 <a href="http://wiki.luajit.org/">Wiki <span class="ext">&raquo;</span></a>
  63 </li><li>
  64 <a href="http://luajit.org/list.html">Mailing List <span class="ext">&raquo;</span></a>
  65 </li></ul>
  66 </div>
  67 <div id="main">
  68 <p>
  69 This page is intended to give you an overview of the features of the FFI
  70 library by presenting a few use cases and guidelines.
  71 </p>
  72 <p>
  73 This page makes no attempt to explain all of the FFI library, though.
  74 You'll want to have a look at the <a href="ext_ffi_api.html">ffi.* API
  75 function reference</a> and the <a href="ext_ffi_semantics.html">FFI
  76 semantics</a> to learn more.
  77 </p>
  78
  79 <h2 id="load">Loading the FFI Library</h2>
  80 <p>
  81 The FFI library is built into LuaJIT by default, but it's not loaded
  82 and initialized by default. The suggested way to use the FFI library
  83 is to add the following to the start of every Lua file that needs one
  84 of its functions:
  85 </p>
  86 <pre class="code">
  87 local ffi = require("ffi")
  88 </pre>
  89 <p>
  90 Please note this doesn't define an <tt>ffi</tt> variable in the table
  91 of globals &mdash; you really need to use the local variable. The
  92 <tt>require</tt> function ensures the library is only loaded once.
  93 </p>
  94 <p style="font-size: 8pt;">
  95 Note: If you want to experiment with the FFI from the interactive prompt
  96 of the command line executable, omit the <tt>local</tt>, as it doesn't
  97 preserve local variables across lines.
  98 </p>
  99
 100 <h2 id="sleep">Accessing Standard System Functions</h2>
 101 <p>
 102 The following code explains how to access standard system functions.
 103 We slowly print two lines of dots by sleeping for 10&nbsp;milliseconds
 104 after each dot:
 105 </p>
 106 <pre class="code mark">
 107 <span class="codemark">&nbsp;
 108 &#9312;
 109
 110
 111
 112
 113
 114 &#9313;
 115 &#9314;
 116 &#9315;
 117
 118
 119
 120 &#9316;
 121
 122
 123
 124
 125
 126 &#9317;</span>local ffi = require("ffi")
 127 ffi.cdef[[
 128 <span style="color:#00a000;">void Sleep(int ms);
 129 int poll(struct pollfd *fds, unsigned long nfds, int timeout);</span>
 130 ]]
 131
 132 local sleep
 133 if ffi.os == "Windows" then
 134   function sleep(s)
 135     ffi.C.Sleep(s*1000)
 136   end
 137 else
 138   function sleep(s)
 139     ffi.C.poll(nil, 0, s*1000)
 140   end
 141 end
 142
 143 for i=1,160 do
 144   io.write("."); io.flush()
 145   sleep(0.01)
 146 end
 147 io.write("\n")
 148 </pre>
 149 <p>
 150 Here's the step-by-step explanation:
 151 </p>
 152 <p>
 153 <span class="mark">&#9312;</span> This defines the
 154 C&nbsp;library functions we're going to use. The part inside the
 155 double-brackets (in green) is just standard C&nbsp;syntax. You can
 156 usually get this info from the C&nbsp;header files or the
 157 documentation provided by each C&nbsp;library or C&nbsp;compiler.
 158 </p>
 159 <p>
 160 <span class="mark">&#9313;</span> The difficulty we're
 161 facing here, is that there are different standards to choose from.
 162 Windows has a simple <tt>Sleep()</tt> function. On other systems there
 163 are a variety of functions available to achieve sub-second sleeps, but
 164 with no clear consensus. Thankfully <tt>poll()</tt> can be used for
 165 this task, too, and it's present on most non-Windows systems. The
 166 check for <tt>ffi.os</tt> makes sure we use the Windows-specific
 167 function only on Windows systems.
 168 </p>
 169 <p>
 170 <span class="mark">&#9314;</span> Here we're wrapping the
 171 call to the C&nbsp;function in a Lua function. This isn't strictly
 172 necessary, but it's helpful to deal with system-specific issues only
 173 in one part of the code. The way we're wrapping it ensures the check
 174 for the OS is only done during initialization and not for every call.
 175 </p>
 176 <p>
 177 <span class="mark">&#9315;</span> A more subtle point is
 178 that we defined our <tt>sleep()</tt> function (for the sake of this
 179 example) as taking the number of seconds, but accepting fractional
 180 seconds. Multiplying this by 1000 gets us milliseconds, but that still
 181 leaves it a Lua number, which is a floating-point value. Alas, the
 182 <tt>Sleep()</tt> function only accepts an integer value. Luckily for
 183 us, the FFI library automatically performs the conversion when calling
 184 the function (truncating the FP value towards zero, like in C).
 185 </p>
 186 <p style="font-size: 8pt;">
 187 Some readers will notice that <tt>Sleep()</tt> is part of
 188 <tt>KERNEL32.DLL</tt> and is also a <tt>stdcall</tt> function. So how
 189 can this possibly work? The FFI library provides the <tt>ffi.C</tt>
 190 default C&nbsp;library namespace, which allows calling functions from
 191 the default set of libraries, like a C&nbsp;compiler would. Also, the
 192 FFI library automatically detects <tt>stdcall</tt> functions, so you
 193 don't need to declare them as such.
 194 </p>
 195 <p>
 196 <span class="mark">&#9316;</span> The <tt>poll()</tt>
 197 function takes a couple more arguments we're not going to use. You can
 198 simply use <tt>nil</tt> to pass a <tt>NULL</tt> pointer and <tt>0</tt>
 199 for the <tt>nfds</tt> parameter. Please note that the
 200 number&nbsp;<tt>0</tt> <em>does not convert to a pointer value</em>,
 201 unlike in C++. You really have to pass pointers to pointer arguments
 202 and numbers to number arguments.
 203 </p>
 204 <p style="font-size: 8pt;">
 205 The page on <a href="ext_ffi_semantics.html">FFI semantics</a> has all
 206 of the gory details about
 207 <a href="ext_ffi_semantics.html#convert">conversions between Lua
 208 objects and C&nbsp;types</a>. For the most part you don't have to deal
 209 with this, as it's performed automatically and it's carefully designed
 210 to bridge the semantic differences between Lua and C.
 211 </p>
 212 <p>
 213 <span class="mark">&#9317;</span> Now that we have defined
 214 our own <tt>sleep()</tt> function, we can just call it from plain Lua
 215 code. That wasn't so bad, huh? Turning these boring animated dots into
 216 a fascinating best-selling game is left as an exercise for the reader.
 217 :-)
 218 </p>
 219
 220 <h2 id="zlib">Accessing the zlib Compression Library</h2>
 221 <p>
 222 The following code shows how to access the <a
 223 href="http://zlib.net/">zlib</a> compression library from Lua code.
 224 We'll define two convenience wrapper functions that take a string and
 225 compress or uncompress it to another string:
 226 </p>
 227 <pre class="code mark">
 228 <span class="codemark">&nbsp;
 229 &#9312;
 230
 231
 232
 233
 234
 235
 236 &#9313;
 237
 238
 239 &#9314;
 240
 241 &#9315;
 242
 243
 244 &#9316;
 245
 246
 247 &#9317;
 248
 249
 250
 251
 252
 253
 254
 255 &#9318;</span>local ffi = require("ffi")
 256 ffi.cdef[[
 257 <span style="color:#00a000;">unsigned long compressBound(unsigned long sourceLen);
 258 int compress2(uint8_t *dest, unsigned long *destLen,
 259               const uint8_t *source, unsigned long sourceLen, int level);
 260 int uncompress(uint8_t *dest, unsigned long *destLen,
 261                const uint8_t *source, unsigned long sourceLen);</span>
 262 ]]
 263 local zlib = ffi.load(ffi.os == "Windows" and "zlib1" or "z")
 264
 265 local function compress(txt)
 266   local n = zlib.compressBound(#txt)
 267   local buf = ffi.new("uint8_t[?]", n)
 268   local buflen = ffi.new("unsigned long[1]", n)
 269   local res = zlib.compress2(buf, buflen, txt, #txt, 9)
 270   assert(res == 0)
 271   return ffi.string(buf, buflen[0])
 272 end
 273
 274 local function uncompress(comp, n)
 275   local buf = ffi.new("uint8_t[?]", n)
 276   local buflen = ffi.new("unsigned long[1]", n)
 277   local res = zlib.uncompress(buf, buflen, comp, #comp)
 278   assert(res == 0)
 279   return ffi.string(buf, buflen[0])
 280 end
 281
 282 -- Simple test code.
 283 local txt = string.rep("abcd", 1000)
 284 print("Uncompressed size: ", #txt)
 285 local c = compress(txt)
 286 print("Compressed size: ", #c)
 287 local txt2 = uncompress(c, #txt)
 288 assert(txt2 == txt)
 289 </pre>
 290 <p>
 291 Here's the step-by-step explanation:
 292 </p>
 293 <p>
 294 <span class="mark">&#9312;</span> This defines some of the
 295 C&nbsp;functions provided by zlib. For the sake of this example, some
 296 type indirections have been reduced and it uses the pre-defined
 297 fixed-size integer types, while still adhering to the zlib API/ABI.
 298 </p>
 299 <p>
 300 <span class="mark">&#9313;</span> This loads the zlib shared
 301 library. On POSIX systems it's named <tt>libz.so</tt> and usually
 302 comes pre-installed. Since <tt>ffi.load()</tt> automatically adds any
 303 missing standard prefixes/suffixes, we can simply load the
 304 <tt>"z"</tt> library. On Windows it's named <tt>zlib1.dll</tt> and
 305 you'll have to download it first from the
 306 <a href="http://zlib.net/"><span class="ext">&raquo;</span>&nbsp;zlib site</a>. The check for
 307 <tt>ffi.os</tt> makes sure we pass the right name to
 308 <tt>ffi.load()</tt>.
 309 </p>
 310 <p>
 311 <span class="mark">&#9314;</span> First, the maximum size of
 312 the compression buffer is obtained by calling the
 313 <tt>zlib.compressBound</tt> function with the length of the
 314 uncompressed string. The next line allocates a byte buffer of this
 315 size. The <tt>[?]</tt> in the type specification indicates a
 316 variable-length array (VLA). The actual number of elements of this
 317 array is given as the 2nd argument to <tt>ffi.new()</tt>.
 318 </p>
 319 <p>
 320 <span class="mark">&#9315;</span> This may look strange at
 321 first, but have a look at the declaration of the <tt>compress2</tt>
 322 function from zlib: the destination length is defined as a pointer!
 323 This is because you pass in the maximum buffer size and get back the
 324 actual length that was used.
 325 </p>
 326 <p>
 327 In C you'd pass in the address of a local variable
 328 (<tt>&amp;buflen</tt>). But since there's no address-of operator in
 329 Lua, we'll just pass in a one-element array. Conveniently it can be
 330 initialized with the maximum buffer size in one step. Calling the
 331 actual <tt>zlib.compress2</tt> function is then straightforward.
 332 </p>
 333 <p>
 334 <span class="mark">&#9316;</span> We want to return the
 335 compressed data as a Lua string, so we'll use <tt>ffi.string()</tt>.
 336 It needs a pointer to the start of the data and the actual length. The
 337 length has been returned in the <tt>buflen</tt> array, so we'll just
 338 get it from there.
 339 </p>
 340 <p style="font-size: 8pt;">
 341 Note that since the function returns now, the <tt>buf</tt> and
 342 <tt>buflen</tt> variables will eventually be garbage collected. This
 343 is fine, because <tt>ffi.string()</tt> has copied the contents to a
 344 newly created (interned) Lua string. If you plan to call this function
 345 lots of times, consider reusing the buffers and/or handing back the
 346 results in buffers instead of strings. This will reduce the overhead
 347 for garbage collection and string interning.
 348 </p>
 349 <p>
 350 <span class="mark">&#9317;</span> The <tt>uncompress</tt>
 351 functions does the exact opposite of the <tt>compress</tt> function.
 352 The compressed data doesn't include the size of the original string,
 353 so this needs to be passed in. Otherwise no surprises here.
 354 </p>
 355 <p>
 356 <span class="mark">&#9318;</span> The code, that makes use
 357 of the functions we just defined, is just plain Lua code. It doesn't
 358 need to know anything about the LuaJIT FFI &mdash; the convenience
 359 wrapper functions completely hide it.
 360 </p>
 361 <p>
 362 One major advantage of the LuaJIT FFI is that you are now able to
 363 write those wrappers <em>in Lua</em>. And at a fraction of the time it
 364 would cost you to create an extra C&nbsp;module using the Lua/C API.
 365 Many of the simpler C&nbsp;functions can probably be used directly
 366 from your Lua code, without any wrappers.
 367 </p>
 368 <p style="font-size: 8pt;">
 369 Side note: the zlib API uses the <tt>long</tt> type for passing
 370 lengths and sizes around. But all those zlib functions actually only
 371 deal with 32&nbsp;bit values. This is an unfortunate choice for a
 372 public API, but may be explained by zlib's history &mdash; we'll just
 373 have to deal with it.
 374 </p>
 375 <p style="font-size: 8pt;">
 376 First, you should know that a <tt>long</tt> is a 64&nbsp;bit type e.g.
 377 on POSIX/x64 systems, but a 32&nbsp;bit type on Windows/x64 and on
 378 32&nbsp;bit systems. Thus a <tt>long</tt> result can be either a plain
 379 Lua number or a boxed 64&nbsp;bit integer cdata object, depending on
 380 the target system.
 381 </p>
 382 <p style="font-size: 8pt;">
 383 Ok, so the <tt>ffi.*</tt> functions generally accept cdata objects
 384 wherever you'd want to use a number. That's why we get a away with
 385 passing <tt>n</tt> to <tt>ffi.string()</tt> above. But other Lua
 386 library functions or modules don't know how to deal with this. So for
 387 maximum portability one needs to use <tt>tonumber()</tt> on returned
 388 <tt>long</tt> results before passing them on. Otherwise the
 389 application might work on some systems, but would fail in a POSIX/x64
 390 environment.
 391 </p>
 392
 393 <h2 id="metatype">Defining Metamethods for a C&nbsp;Type</h2>
 394 <p>
 395 The following code explains how to define metamethods for a C type.
 396 We define a simple point type and add some operations to it:
 397 </p>
 398 <pre class="code mark">
 399 <span class="codemark">&nbsp;
 400 &#9312;
 401
 402
 403
 404 &#9313;
 405
 406 &#9314;
 407
 408 &#9315;
 409
 410
 411
 412 &#9316;
 413
 414 &#9317;</span>local ffi = require("ffi")
 415 ffi.cdef[[
 416 <span style="color:#00a000;">typedef struct { double x, y; } point_t;</span>
 417 ]]
 418
 419 local point
 420 local mt = {
 421   __add = function(a, b) return point(a.x+b.x, a.y+b.y) end,
 422   __len = function(a) return math.sqrt(a.x*a.x + a.y*a.y) end,
 423   __index = {
 424     area = function(a) return a.x*a.x + a.y*a.y end,
 425   },
 426 }
 427 point = ffi.metatype("point_t", mt)
 428
 429 local a = point(3, 4)
 430 print(a.x, a.y)  --> 3  4
 431 print(#a)        --> 5
 432 print(a:area())  --> 25
 433 local b = a + point(0.5, 8)
 434 print(#b)        --> 12.5
 435 </pre>
 436 <p>
 437 Here's the step-by-step explanation:
 438 </p>
 439 <p>
 440 <span class="mark">&#9312;</span> This defines the C&nbsp;type for a
 441 two-dimensional point object.
 442 </p>
 443 <p>
 444 <span class="mark">&#9313;</span> We have to declare the variable
 445 holding the point constructor first, because it's used inside of a
 446 metamethod.
 447 </p>
 448 <p>
 449 <span class="mark">&#9314;</span> Let's define an <tt>__add</tt>
 450 metamethod which adds the coordinates of two points and creates a new
 451 point object. For simplicity, this function assumes that both arguments
 452 are points. But it could be any mix of objects, if at least one operand
 453 is of the required type (e.g. adding a point plus a number or vice
 454 versa). Our <tt>__len</tt> metamethod returns the distance of a point to
 455 the origin.
 456 </p>
 457 <p>
 458 <span class="mark">&#9315;</span> If we run out of operators, we can
 459 define named methods, too. Here the <tt>__index</tt> table defines an
 460 <tt>area</tt> function. For custom indexing needs, one might want to
 461 define <tt>__index</tt> and <tt>__newindex</tt> <em>functions</em> instead.
 462 </p>
 463 <p>
 464 <span class="mark">&#9316;</span> This associates the metamethods with
 465 our C&nbsp;type. This only needs to be done once. For convenience, a
 466 constructor is returned by
 467 <a href="ext_ffi_api.html#ffi_metatype"><tt>ffi.metatype()</tt></a>.
 468 We're not required to use it, though. The original C&nbsp;type can still
 469 be used e.g. to create an array of points. The metamethods automatically
 470 apply to any and all uses of this type.
 471 </p>
 472 <p>
 473 Please note that the association with a metatable is permanent and
 474 <b>the metatable must not be modified afterwards!</b> Ditto for the
 475 <tt>__index</tt> table.
 476 </p>
 477 <p>
 478 <span class="mark">&#9317;</span> Here are some simple usage examples
 479 for the point type and their expected results. The pre-defined
 480 operations (such as <tt>a.x</tt>) can be freely mixed with the newly
 481 defined metamethods. Note that <tt>area</tt> is a method and must be
 482 called with the Lua syntax for methods: <tt>a:area()</tt>, not
 483 <tt>a.area()</tt>.
 484 </p>
 485 <p>
 486 The C&nbsp;type metamethod mechanism is most useful when used in
 487 conjunction with C&nbsp;libraries that are written in an object-oriented
 488 style. Creators return a pointer to a new instance and methods take an
 489 instance pointer as the first argument. Sometimes you can just point
 490 <tt>__index</tt> to the library namespace and <tt>__gc</tt> to the
 491 destructor and you're done. But often enough you'll want to add
 492 convenience wrappers, e.g. to return actual Lua strings or when
 493 returning multiple values.
 494 </p>
 495 <p>
 496 Some C libraries only declare instance pointers as an opaque
 497 <tt>void&nbsp;*</tt> type. In this case you can use a fake type for all
 498 declarations, e.g. a pointer to a named (incomplete) struct will do:
 499 <tt>typedef struct foo_type *foo_handle</tt>. The C&nbsp;side doesn't
 500 know what you declare with the LuaJIT FFI, but as long as the underlying
 501 types are compatible, everything still works.
 502 </p>
 503
 504 <h2 id="idioms">Translating C&nbsp;Idioms</h2>
 505 <p>
 506 Here's a list of common C&nbsp;idioms and their translation to the
 507 LuaJIT FFI:
 508 </p>
 509 <table class="idiomtable">
 510 <tr class="idiomhead">
 511 <td class="idiomdesc">Idiom</td>
 512 <td class="idiomc">C&nbsp;code</td>
 513 <td class="idiomlua">Lua code</td>
 514 </tr>
 515 <tr class="odd separate">
 516 <td class="idiomdesc">Pointer dereference<br><tt>int *p;</tt></td><td class="idiomc"><tt>x = *p;<br>*p = y;</tt></td><td class="idiomlua"><tt>x = <b>p[0]</b><br><b>p[0]</b> = y</tt></td></tr>
 517 <tr class="even">
 518 <td class="idiomdesc">Pointer indexing<br><tt>int i, *p;</tt></td><td class="idiomc"><tt>x = p[i];<br>p[i+1] = y;</tt></td><td class="idiomlua"><tt>x = p[i]<br>p[i+1] = y</tt></td></tr>
 519 <tr class="odd">
 520 <td class="idiomdesc">Array indexing<br><tt>int i, a[];</tt></td><td class="idiomc"><tt>x = a[i];<br>a[i+1] = y;</tt></td><td class="idiomlua"><tt>x = a[i]<br>a[i+1] = y</tt></td></tr>
 521 <tr class="even separate">
 522 <td class="idiomdesc"><tt>struct</tt>/<tt>union</tt> dereference<br><tt>struct foo s;</tt></td><td class="idiomc"><tt>x = s.field;<br>s.field = y;</tt></td><td class="idiomlua"><tt>x = s.field<br>s.field = y</tt></td></tr>
 523 <tr class="odd">
 524 <td class="idiomdesc"><tt>struct</tt>/<tt>union</tt> pointer deref.<br><tt>struct foo *sp;</tt></td><td class="idiomc"><tt>x = sp->field;<br>sp->field = y;</tt></td><td class="idiomlua"><tt>x = <b>s.field</b><br><b>s.field</b> = y</tt></td></tr>
 525 <tr class="even separate">
 526 <td class="idiomdesc">Pointer arithmetic<br><tt>int i, *p;</tt></td><td class="idiomc"><tt>x = p + i;<br>y = p - i;</tt></td><td class="idiomlua"><tt>x = p + i<br>y = p - i</tt></td></tr>
 527 <tr class="odd">
 528 <td class="idiomdesc">Pointer difference<br><tt>int *p1, *p2;</tt></td><td class="idiomc"><tt>x = p1 - p2;</tt></td><td class="idiomlua"><tt>x = p1 - p2</tt></td></tr>
 529 <tr class="even">
 530 <td class="idiomdesc">Array element pointer<br><tt>int i, a[];</tt></td><td class="idiomc"><tt>x = &amp;a[i];</tt></td><td class="idiomlua"><tt>x = <b>a+i</b></tt></td></tr>
 531 <tr class="odd">
 532 <td class="idiomdesc">Cast pointer to address<br><tt>int *p;</tt></td><td class="idiomc"><tt>x = (intptr_t)p;</tt></td><td class="idiomlua"><tt>x = <b>tonumber(<br>&nbsp;ffi.cast("intptr_t",<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;p))</b></tt></td></tr>
 533 <tr class="even separate">
 534 <td class="idiomdesc">Functions with outargs<br><tt>void foo(int *inoutlen);</tt></td><td class="idiomc"><tt>int len = x;<br>foo(&amp;len);<br>y = len;</tt></td><td class="idiomlua"><tt><b>local len =<br>&nbsp;&nbsp;ffi.new("int[1]", x)<br>foo(len)<br>y = len[0]</b></tt></td></tr>
 535 <tr class="odd">
 536 <td class="idiomdesc"><a href="ext_ffi_semantics.html#convert_vararg">Vararg conversions</a><br><tt>int printf(char *fmt, ...);</tt></td><td class="idiomc"><tt>printf("%g", 1.0);<br>printf("%d", 1);<br>&nbsp;</tt></td><td class="idiomlua"><tt>printf("%g", 1);<br>printf("%d",<br>&nbsp;&nbsp;<b>ffi.new("int", 1)</b>)</tt></td></tr>
 537 </table>
 538
 539 <h2 id="cache">To Cache or Not to Cache</h2>
 540 <p>
 541 It's a common Lua idiom to cache library functions in local variables
 542 or upvalues, e.g.:
 543 </p>
 544 <pre class="code">
 545 local byte, char = string.byte, string.char
 546 local function foo(x)
 547   return char(byte(x)+1)
 548 end
 549 </pre>
 550 <p>
 551 This replaces several hash-table lookups with a (faster) direct use of
 552 a local or an upvalue. This is less important with LuaJIT, since the
 553 JIT compiler optimizes hash-table lookups a lot and is even able to
 554 hoist most of them out of the inner loops. It can't eliminate
 555 <em>all</em> of them, though, and it saves some typing for often-used
 556 functions. So there's still a place for this, even with LuaJIT.
 557 </p>
 558 <p>
 559 The situation is a bit different with C&nbsp;function calls via the
 560 FFI library. The JIT compiler has special logic to eliminate <em>all
 561 of the lookup overhead</em> for functions resolved from a
 562 <a href="ext_ffi_semantics.html#clib">C&nbsp;library namespace</a>!
 563 Thus it's not helpful and actually counter-productive to cache
 564 individual C&nbsp;functions like this:
 565 </p>
 566 <pre class="code">
 567 local <b>funca</b>, <b>funcb</b> = ffi.C.funcb, ffi.C.funcb -- <span style="color:#c00000;">Not helpful!</span>
 568 local function foo(x, n)
 569   for i=1,n do <b>funcb</b>(<b>funca</b>(x, i), 1) end
 570 end
 571 </pre>
 572 <p>
 573 This turns them into indirect calls and generates bigger and slower
 574 machine code. Instead you'll want to cache the namespace itself and
 575 rely on the JIT compiler to eliminate the lookups:
 576 </p>
 577 <pre class="code">
 578 local <b>C</b> = ffi.C          -- <span style="color:#00a000;">Instead use this!</span>
 579 local function foo(x, n)
 580   for i=1,n do <b>C.funcb</b>(<b>C.funca</b>(x, i), 1) end
 581 end
 582 </pre>
 583 <p>
 584 This generates both shorter and faster code. So <b>don't cache
 585 C&nbsp;functions</b>, but <b>do</b> cache namespaces! Most often the
 586 namespace is already in a local variable at an outer scope, e.g. from
 587 <tt>local&nbsp;lib&nbsp;=&nbsp;ffi.load(...)</tt>. Note that copying
 588 it to a local variable in the function scope is unnecessary.
 589 </p>
 590 <br class="flush">
 591 </div>
 592 <div id="foot">
 593 <hr class="hide">
 594 Copyright &copy; 2005-2013 Mike Pall
 595 <span class="noprint">
 596 &middot;
 597 <a href="contact.html">Contact</a>
 598 </span>
 599 </div>
 600 </body>
 601 </html>