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