| blob | a624e6fd6e6734ca6b4c114670d508589923b084 |
2 <html>
3 <head>
17 </style>
18 </head>
19 <body>
22 </div>
25 </div>
27 <ul><li>
29 <ul><li>
31 </li><li>
33 </li><li>
35 </li></ul>
36 </li><li>
38 <ul><li>
40 <ul><li>
42 </li><li>
44 </li><li>
46 </li></ul>
47 </li><li>
49 </li><li>
51 </li><li>
53 </li></ul>
54 </li><li>
56 <ul><li>
58 </li></ul>
59 </li><li>
61 </li><li>
63 </li><li>
65 </li><li>
67 </li></ul>
68 </div>
70 <p>
71 This page is intended to give you an overview of the features of the FFI
72 library by presenting a few use cases and guidelines.
73 </p>
74 <p>
75 This page makes no attempt to explain all of the FFI library, though.
78 semantics</a> to learn more.
79 </p>
82 <p>
83 The FFI library is built into LuaJIT by default, but it's not loaded
84 and initialized by default. The suggested way to use the FFI library
85 is to add the following to the start of every Lua file that needs one
86 of its functions:
87 </p>
89 local ffi = require("ffi")
90 </pre>
91 <p>
93 of globals — you really need to use the local variable. The
95 </p>
97 Note: If you want to experiment with the FFI from the interactive prompt
99 preserve local variables across lines.
100 </p>
103 <p>
104 The following code explains how to access standard system functions.
106 after each dot:
107 </p>
110 ①
116 ②
117 ③
118 ④
122 ⑤
129 ffi.cdef[[
131 int poll(struct pollfd *fds, unsigned long nfds, int timeout);</span>
132 ]]
134 local sleep
135 if ffi.os == "Windows" then
136 function sleep(s)
137 ffi.C.Sleep(s*1000)
138 end
139 else
140 function sleep(s)
142 end
143 end
146 io.write("."); io.flush()
147 sleep(0.01)
148 end
149 io.write("\n")
150 </pre>
151 <p>
152 Here's the step-by-step explanation:
153 </p>
154 <p>
156 C library functions we're going to use. The part inside the
157 double-brackets (in green) is just standard C syntax. You can
158 usually get this info from the C header files or the
160 </p>
161 <p>
163 facing here, is that there are different standards to choose from.
165 are a variety of functions available to achieve sub-second sleeps, but
167 this task, too, and it's present on most non-Windows systems. The
169 function only on Windows systems.
170 </p>
171 <p>
173 call to the C function in a Lua function. This isn't strictly
174 necessary, but it's helpful to deal with system-specific issues only
175 in one part of the code. The way we're wrapping it ensures the check
176 for the OS is only done during initialization and not for every call.
177 </p>
178 <p>
181 example) as taking the number of seconds, but accepting fractional
182 seconds. Multiplying this by 1000 gets us milliseconds, but that still
183 leaves it a Lua number, which is a floating-point value. Alas, the
185 us, the FFI library automatically performs the conversion when calling
186 the function (truncating the FP value towards zero, like in C).
187 </p>
192 default C library namespace, which allows calling functions from
193 the default set of libraries, like a C compiler would. Also, the
195 don't need to declare them as such.
196 </p>
197 <p>
199 function takes a couple more arguments we're not going to use. You can
203 unlike in C++. You really have to pass pointers to pointer arguments
204 and numbers to number arguments.
205 </p>
208 of the gory details about
211 with this, as it's performed automatically and it's carefully designed
212 to bridge the semantic differences between Lua and C.
213 </p>
214 <p>
217 code. That wasn't so bad, huh? Turning these boring animated dots into
218 a fascinating best-selling game is left as an exercise for the reader.
219 :-)
220 </p>
223 <p>
224 The following code shows how to access the <a
226 We'll define two convenience wrapper functions that take a string and
227 compress or uncompress it to another string:
228 </p>
231 ①
238 ②
241 ③
243 ④
246 ⑤
249 ⑥
258 ffi.cdef[[
260 int compress2(uint8_t *dest, unsigned long *destLen,
261 const uint8_t *source, unsigned long sourceLen, int level);
262 int uncompress(uint8_t *dest, unsigned long *destLen,
263 const uint8_t *source, unsigned long sourceLen);</span>
264 ]]
267 local function compress(txt)
268 local n = zlib.compressBound(#txt)
269 local buf = ffi.new("uint8_t[?]", n)
270 local buflen = ffi.new("unsigned long[1]", n)
271 local res = zlib.compress2(buf, buflen, txt, #txt, 9)
272 assert(res == 0)
273 return ffi.string(buf, buflen[0])
274 end
276 local function uncompress(comp, n)
277 local buf = ffi.new("uint8_t[?]", n)
278 local buflen = ffi.new("unsigned long[1]", n)
279 local res = zlib.uncompress(buf, buflen, comp, #comp)
280 assert(res == 0)
281 return ffi.string(buf, buflen[0])
282 end
284 -- Simple test code.
286 print("Uncompressed size: ", #txt)
287 local c = compress(txt)
288 print("Compressed size: ", #c)
289 local txt2 = uncompress(c, #txt)
290 assert(txt2 == txt)
291 </pre>
292 <p>
293 Here's the step-by-step explanation:
294 </p>
295 <p>
297 C functions provided by zlib. For the sake of this example, some
298 type indirections have been reduced and it uses the pre-defined
299 fixed-size integer types, while still adhering to the zlib API/ABI.
300 </p>
301 <p>
305 missing standard prefixes/suffixes, we can simply load the
307 you'll have to download it first from the
311 </p>
312 <p>
314 the compression buffer is obtained by calling the
316 uncompressed string. The next line allocates a byte buffer of this
318 variable-length array (VLA). The actual number of elements of this
320 </p>
321 <p>
324 function from zlib: the destination length is defined as a pointer!
325 This is because you pass in the maximum buffer size and get back the
326 actual length that was used.
327 </p>
328 <p>
329 In C you'd pass in the address of a local variable
331 Lua, we'll just pass in a one-element array. Conveniently it can be
332 initialized with the maximum buffer size in one step. Calling the
334 </p>
335 <p>
338 It needs a pointer to the start of the data and the actual length. The
340 get it from there.
341 </p>
346 newly created (interned) Lua string. If you plan to call this function
347 lots of times, consider reusing the buffers and/or handing back the
348 results in buffers instead of strings. This will reduce the overhead
349 for garbage collection and string interning.
350 </p>
351 <p>
354 The compressed data doesn't include the size of the original string,
355 so this needs to be passed in. Otherwise no surprises here.
356 </p>
357 <p>
359 of the functions we just defined, is just plain Lua code. It doesn't
360 need to know anything about the LuaJIT FFI — the convenience
361 wrapper functions completely hide it.
362 </p>
363 <p>
364 One major advantage of the LuaJIT FFI is that you are now able to
366 would cost you to create an extra C module using the Lua/C API.
367 Many of the simpler C functions can probably be used directly
368 from your Lua code, without any wrappers.
369 </p>
372 lengths and sizes around. But all those zlib functions actually only
374 public API, but may be explained by zlib's history — we'll just
375 have to deal with it.
376 </p>
382 the target system.
383 </p>
386 wherever you'd want to use a number. That's why we get a away with
388 library functions or modules don't know how to deal with this. So for
391 application might work on some systems, but would fail in a POSIX/x64
392 environment.
393 </p>
396 <p>
397 The following code explains how to define metamethods for a C type.
398 We define a simple point type and add some operations to it:
399 </p>
402 ①
406 ②
408 ③
410 ④
414 ⑤
417 ffi.cdef[[
419 ]]
421 local point
422 local mt = {
423 __add = function(a, b) return point(a.x+b.x, a.y+b.y) end,
424 __len = function(a) return math.sqrt(a.x*a.x + a.y*a.y) end,
425 __index = {
426 area = function(a) return a.x*a.x + a.y*a.y end,
427 },
428 }
429 point = ffi.metatype("point_t", mt)
432 print(a.x, a.y) --> 3 4
433 print(#a) --> 5
434 print(a:area()) --> 25
436 print(#b) --> 12.5
437 </pre>
438 <p>
439 Here's the step-by-step explanation:
440 </p>
441 <p>
443 two-dimensional point object.
444 </p>
445 <p>
447 holding the point constructor first, because it's used inside of a
448 metamethod.
449 </p>
450 <p>
452 metamethod which adds the coordinates of two points and creates a new
453 point object. For simplicity, this function assumes that both arguments
454 are points. But it could be any mix of objects, if at least one operand
455 is of the required type (e.g. adding a point plus a number or vice
457 the origin.
458 </p>
459 <p>
464 </p>
465 <p>
467 our C type. This only needs to be done once. For convenience, a
468 constructor is returned by
470 We're not required to use it, though. The original C type can still
471 be used e.g. to create an array of points. The metamethods automatically
472 apply to any and all uses of this type.
473 </p>
474 <p>
475 Please note that the association with a metatable is permanent and
478 </p>
479 <p>
481 for the point type and their expected results. The pre-defined
486 </p>
487 <p>
488 The C type metamethod mechanism is most useful when used in
489 conjunction with C libraries that are written in an object-oriented
490 style. Creators return a pointer to a new instance and methods take an
491 instance pointer as the first argument. Sometimes you can just point
493 destructor and you're done. But often enough you'll want to add
494 convenience wrappers, e.g. to return actual Lua strings or when
495 returning multiple values.
496 </p>
497 <p>
498 Some C libraries only declare instance pointers as an opaque
500 declarations, e.g. a pointer to a named (incomplete) struct will do:
502 know what you declare with the LuaJIT FFI, but as long as the underlying
503 types are compatible, everything still works.
504 </p>
507 <p>
508 Here's a list of common C idioms and their translation to the
509 LuaJIT FFI:
510 </p>
516 </tr>
518 <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>
520 <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>
522 <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>
524 <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>
526 <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>
528 <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>
530 <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>
532 <td class="idiomdesc">Array element pointer<br><tt>int i, a[];</tt></td><td class="idiomc"><tt>x = &a[i];</tt></td><td class="idiomlua"><tt>x = <b>a+i</b></tt></td></tr>
534 <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> ffi.cast("intptr_t",<br> p))</b></tt></td></tr>
536 <td class="idiomdesc">Functions with outargs<br><tt>void foo(int *inoutlen);</tt></td><td class="idiomc"><tt>int len = x;<br>foo(&len);<br>y = len;</tt></td><td class="idiomlua"><tt><b>local len =<br> ffi.new("int[1]", x)<br>foo(len)<br>y = len[0]</b></tt></td></tr>
538 <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> </tt></td><td class="idiomlua"><tt>printf("%g", 1);<br>printf("%d",<br> <b>ffi.new("int", 1)</b>)</tt></td></tr>
539 </table>
542 <p>
543 It's a common Lua idiom to cache library functions in local variables
544 or upvalues, e.g.:
545 </p>
547 local byte, char = string.byte, string.char
548 local function foo(x)
549 return char(byte(x)+1)
550 end
551 </pre>
552 <p>
553 This replaces several hash-table lookups with a (faster) direct use of
554 a local or an upvalue. This is less important with LuaJIT, since the
555 JIT compiler optimizes hash-table lookups a lot and is even able to
556 hoist most of them out of the inner loops. It can't eliminate
558 functions. So there's still a place for this, even with LuaJIT.
559 </p>
560 <p>
561 The situation is a bit different with C function calls via the
562 FFI library. The JIT compiler has special logic to eliminate <em>all
563 of the lookup overhead</em> for functions resolved from a
565 Thus it's not helpful and actually counter-productive to cache
566 individual C functions like this:
567 </p>
569 local <b>funca</b>, <b>funcb</b> = ffi.C.funca, ffi.C.funcb -- <span style="color:#c00000;">Not helpful!</span>
570 local function foo(x, n)
572 end
573 </pre>
574 <p>
575 This turns them into indirect calls and generates bigger and slower
576 machine code. Instead you'll want to cache the namespace itself and
577 rely on the JIT compiler to eliminate the lookups:
578 </p>
581 local function foo(x, n)
583 end
584 </pre>
585 <p>
586 This generates both shorter and faster code. So <b>don't cache
588 namespace is already in a local variable at an outer scope, e.g. from
590 it to a local variable in the function scope is unnecessary.
591 </p>
593 </div>
598 ·
600 </span>
601 </div>
602 </body>
603 </html>