-TODO -
--
-local ffi = require("ffi") -ffi.cdef[[ -int printf(const char *fmt, ...); +local ffi = require("ffi") --① +ffi.cdef[[ //② +int printf(const char *fmt, ...); ]] -ffi.C.printf("Hello %s!", "world") +ffi.C.printf("Hello %s!", "world") --③
-So, let's pick that apart: the first line (in blue) loads the FFI -library. The next one adds a C declaration for the function. The -part between the double-brackets (in green) is just standard -C syntax. And the last line calls the named C function. Yes, -it's that simple! +So, let's pick that apart: +
++① Load the FFI library. +
++② Add a C declaration +for the function. The part inside the double-brackets (in green) is +just standard C syntax. +
++③ Call the named +C function — Yes, it's that simple!
-Actually, what goes on behind the scenes is far from simple: the first -part of the last line (in orange) makes use of the standard +Actually, what goes on behind the scenes is far from simple: ③ makes use of the standard C library namespace ffi.C. Indexing this namespace with a symbol name ("printf") automatically binds it to the the standard C library. The result is a special kind of object which, @@ -120,7 +126,7 @@ So here's something to pop up a message box on Windows:
local ffi = require("ffi")
ffi.cdef[[
-int MessageBoxA(void *w, const char *txt, const char *cap, int type);
+int MessageBoxA(void *w, const char *txt, const char *cap, int type);
]]
ffi.C.MessageBoxA(nil, "Hello world!", "Test", 0)
@@ -193,24 +199,24 @@ And here's the FFI version. The modified parts have been marked in
bold:
-local ffi = require("ffi")
-ffi.cdef[[
-typedef struct { uint8_t red, green, blue, alpha; } rgba_pixel;
+local ffi = require("ffi") --①
+ffi.cdef[[
+typedef struct { uint8_t red, green, blue, alpha; } rgba_pixel;
]]
local function image_ramp_green(n)
- local img = ffi.new("rgba_pixel[?]", n)
+ local img = ffi.new("rgba_pixel[?]", n) --②
local f = 255/(n-1)
- for i=0,n-1 do
- img[i].green = i*f
+ for i=0,n-1 do --③
+ img[i].green = i*f --④
img[i].alpha = 255
end
return img
end
local function image_to_grey(img, n)
- for i=0,n-1 do
- local y = 0.3*img[i].red + 0.59*img[i].green + 0.11*img[i].blue
+ for i=0,n-1 do --③
+ local y = 0.3*img[i].red + 0.59*img[i].green + 0.11*img[i].blue --⑤
img[i].red = y; img[i].green = y; img[i].blue = y
end
end
@@ -222,25 +228,37 @@ for i=1,1000 do
end
-Ok, so that wasn't too difficult: first, load the FFI library and -declare the low-level data type. Here we choose a struct -which holds four byte fields, one for each component of a 4x8 bit -RGBA pixel. +Ok, so that wasn't too difficult:
-Creating the data structure with ffi.new() is straightforward -— the '?' is a placeholder for the number of elements -of a variable-length array. C arrays are zero-based, so the -indexes have to run from 0 to n-1 (one might -allocate one more element instead to simplify converting legacy -code). Since ffi.new() zero-fills the array by default, we -only need to set the green and the alpha fields. +① First, load the FFI +library and declare the low-level data type. Here we choose a +struct which holds four byte fields, one for each component +of a 4x8 bit RGBA pixel.
-The calls to math.floor() can be omitted here, because -floating-point numbers are already truncated towards zero when -converting them to an integer. This happens implicitly when the number -is stored in the fields of each pixel. +② Creating the data +structure with ffi.new() is straightforward — the +'?' is a placeholder for the number of elements of a +variable-length array. +
++③ C arrays are +zero-based, so the indexes have to run from 0 to +n-1. One might want to allocate one more element instead to +simplify converting legacy code. +
++④ Since ffi.new() +zero-fills the array by default, we only need to set the green and the +alpha fields. +
++⑤ The calls to +math.floor() can be omitted here, because floating-point +numbers are already truncated towards zero when converting them to an +integer. This happens implicitly when the number is stored in the +fields of each pixel.
Now let's have a look at the impact of the changes: first, memory diff --git a/doc/ext_ffi_api.html b/doc/ext_ffi_api.html index 7c2e53dd..9bedd52e 100644 --- a/doc/ext_ffi_api.html +++ b/doc/ext_ffi_api.html @@ -38,8 +38,6 @@ td.abiparam { font-weight: bold; width: 6em; }
ffi.cdef[[
-typedef struct foo { int a, b; } foo_t; // Declare a struct and typedef.
+typedef struct foo { int a, b; } foo_t; // Declare a struct and typedef.
int dofoo(foo_t *f, int n); /* Declare an external C function. */
]]
@@ -237,12 +235,8 @@ rules.
This functions is mainly useful to override the pointer compatibility -rules or to convert pointers to addresses or vice versa. For maximum -portability you should convert a pointer to its address as follows: +checks or to convert pointers to addresses or vice versa.
-
-local addr = tonumber(ffi.cast("intptr_t", ptr))
-
@@ -383,6 +377,45 @@ Contains the target OS name. Same contents as Contains the target architecture name. Same contents as jit.arch.
+ ++The following standard library functions have been extended to work +with cdata objects: +
+ ++Converts a number cdata object to a double and returns it as +a Lua number. This is particularly useful for boxed 64 bit +integer values. Caveat: this conversion may incur a precision loss. +
+ ++Returns a string representation of the value of 64 bit integers +("nnnLL" or "nnnULL") or +complex numbers ("re±imi"). Otherwise +returns a string representation of the C type of a ctype object +("ctype<type>") or a cdata object +("cdata<type>: address"). +
+ ++The parser for Lua source code treats numeric literals with the +suffixes LL or ULL as signed or unsigned 64 bit +integers. Case doesn't matter, but uppercase is recommended for +readability. It handles both decimal (42LL) and hexadecimal +(0x2aLL) literals. +
++The imaginary part of complex numbers can be specified by suffixing +number literals with i or I, e.g. 12.5i. +Caveat: you'll need to use 1i to get an imaginary part with +the value one, since i itself still refers to a variable +named i. +
-TODO -
--TODO +This page is intended to give you an overview of the features of the FFI +library by presenting a few use cases and guidelines. +
++This page makes no attempt to explain all of the FFI library, though. +You'll want to have a look at the ffi.* API +function reference and the FFI +semantics to learn more.
+The following code explains how to access standard system functions. +We slowly print two lines of dots by sleeping for 10 milliseconds +after each dot: +
+
+local ffi = require("ffi")
+ffi.cdef[[ //①
+void Sleep(int ms);
+int poll(struct pollfd *fds, unsigned long nfds, int timeout);
+]]
+
+local sleep
+if ffi.os == "Windows" then --②
+ function sleep(s) --③
+ ffi.C.Sleep(s*1000) --④
+ end
+else
+ function sleep(s)
+ ffi.C.poll(nil, 0, s*1000) --⑤
+ end
+end
+
+for i=1,160 do
+ io.write("."); io.flush()
+ sleep(0.01) --⑥
+end
+io.write("\n")
+
++Here's the step-by-step explanation: +
++① This defines the +C library functions we're going to use. The part inside the +double-brackets (in green) is just standard C syntax. You can +usually get this info from the C header files or the +documentation provided by each C library or C compiler. +
++② The difficulty we're +facing here, is that there are different standards to choose from. +Windows has a simple Sleep() function. On other systems there +are a variety of functions available to achieve sub-second sleeps, but +with no clear consensus. Thankfully poll() can be used for +this task, too, and it's present on most non-Windows systems. The +check for ffi.os makes sure we use the Windows-specific +function only on Windows systems. +
++③ Here we're wrapping the +call to the C function in a Lua function. This isn't strictly +necessary, but it's helpful to deal with system-specific issues only +in one part of the code. The way we're wrapping it ensures the check +for the OS is only done during initialization and not for every call. +
++④ A more subtle point is +that we defined our sleep() function (for the sake of this +example) as taking the number of seconds, but accepting fractional +seconds. Multiplying this by 1000 gets us milliseconds, but that still +leaves it a Lua number, which is a floating-point value. Alas, the +Sleep() function only accepts an integer value. Luckily for +us, the FFI library automatically performs the conversion when calling +the function (truncating the FP value towards zero, like in C). +
++Some readers will notice that Sleep() is part of +KERNEL32.DLL and is also a stdcall function. So how +can this possibly work? The FFI library provides the ffi.C +default C library namespace, which allows calling functions from +the default set of libraries, like a C compiler would. Also, the +FFI library automatically detects stdcall functions, so you +don't need to declare them as such. +
++⑤ The poll() +function takes a couple more arguments we're not going to use. You can +simply use nil to pass a NULL pointer and 0 +for the nfds parameter. Please note that the +number 0 does not convert to a pointer value, +unlike in C++. You really have to pass pointers to pointer arguments +and numbers to number arguments. +
++The page on FFI semantics has all +of the gory details about +conversions between Lua +objects and C types. For the most part you don't have to deal +with this, as it's performed automatically and it's carefully designed +to bridge the semantic differences between Lua and C. +
++⑥ Now that we have defined +our own sleep() function, we can just call it from plain Lua +code. That wasn't so bad, huh? Turning these boring animated dots into +a fascinating best-selling game is left as an exercise for the reader. +:-) +
+ ++The following code shows how to access the zlib compression library from Lua code. +We'll define two convenience wrapper functions that take a string and +compress or uncompress it to another string: +
+
+local ffi = require("ffi")
+ffi.cdef[[ //①
+unsigned long compressBound(unsigned long sourceLen);
+int compress2(uint8_t *dest, unsigned long *destLen,
+ const uint8_t *source, unsigned long sourceLen, int level);
+int uncompress(uint8_t *dest, unsigned long *destLen,
+ const uint8_t *source, unsigned long sourceLen);
+]]
+local zlib = ffi.load(ffi.os == "Windows" and "zlib1" or "z") --②
+
+local function compress(txt)
+ local n = zlib.compressBound(#txt) --③
+ local buf = ffi.new("uint8_t[?]", n)
+ local buflen = ffi.new("unsigned long[1]", n) --④
+ local res = zlib.compress2(buf, buflen, txt, #txt, 9)
+ assert(res == 0)
+ return ffi.string(buf, buflen[0]) --⑤
+end
+
+local function uncompress(comp, n) --⑥
+ local buf = ffi.new("uint8_t[?]", n)
+ local buflen = ffi.new("unsigned long[1]", n)
+ local res = zlib.uncompress(buf, buflen, comp, #comp)
+ assert(res == 0)
+ return ffi.string(buf, buflen[0])
+end
+
+-- Simple test code. --⑦
+local txt = string.rep("abcd", 1000)
+print("Uncompressed size: ", #txt)
+local c = compress(txt)
+print("Compressed size: ", #c)
+local txt2 = uncompress(c, #txt)
+assert(txt2 == txt)
+
++Here's the step-by-step explanation: +
++① This defines some of the +C functions provided by zlib. For the sake of this example, some +type indirections have been reduced and it uses the pre-defined +fixed-size integer types, while still adhering to the zlib API/ABI. +
++② This loads the zlib shared +library. On POSIX systems it's named libz.so and usually +comes pre-installed. Since ffi.load() automatically adds any +missing standard prefixes/suffixes, we can simply load the +"z" library. On Windows it's named zlib1.dll and +you'll have to download it first from the +» zlib site. The check for +ffi.os makes sure we pass the right name to +ffi.load(). +
++③ First, the maximum size of +the compression buffer is obtained by calling the +zlib.compressBound function with the length of the +uncompressed string. The next line allocates a byte buffer of this +size. The [?] in the type specification indicates a +variable-length array (VLA). The actual number of elements of this +array is given as the 2nd argument to ffi.new(). +
++④ This may look strange at +first, but have a look at the declaration of the compress2 +function from zlib: the destination length is defined as a pointer! +This is because you pass in the maximum buffer size and get back the +actual length that was used. +
++In C you'd pass in the address of a local variable +(&buflen). But since there's no address-of operator in +Lua, we'll just pass in a one-element array. Conveniently it can be +initialized with the maximum buffer size in one step. Calling the +actual zlib.compress2 function is then straightforward. +
++⑤ We want to return the +compressed data as a Lua string, so we'll use ffi.string(). +It needs a pointer to the start of the data and the actual length. The +length has been returned in the buflen array, so we'll just +get it from there. +
++Note that since the function returns now, the buf and +buflen variables will eventually be garbage collected. This +is fine, because ffi.string() has copied the contents to a +newly created (interned) Lua string. If you plan to call this function +lots of times, consider reusing the buffers and/or handing back the +results in buffers instead of strings. This will reduce the overhead +for garbage collection and string interning. +
++⑥ The uncompress +functions does the exact opposite of the compress function. +The compressed data doesn't include the size of the original string, +so this needs to be passed in. Otherwise no surprises here. +
++⑦ The code, that makes use +of the functions we just defined, is just plain Lua code. It doesn't +need to know anything about the LuaJIT FFI — the convenience +wrapper functions completely hide it. +
++One major advantage of the LuaJIT FFI is that you are now able to +write those wrappers in Lua. And at a fraction of the time it +would cost you to create an extra C module using the Lua/C API. +Many of the simpler C functions can probably be used directly +from your Lua code, without any wrappers. +
++Side note: the zlib API uses the long type for passing +lengths and sizes around. But all those zlib functions actually only +deal with 32 bit values. This is an unfortunate choice for a +public API, but may be explained by zlib's history — we'll just +have to deal with it. +
++First, you should know that a long is a 64 bit type e.g. +on POSIX/x64 systems, but a 32 bit type on Windows/x64 and on +32 bit systems. Thus a long result can be either a plain +Lua number or a boxed 64 bit integer cdata object, depending on +the target system. +
++Ok, so the ffi.* functions generally accept cdata objects +wherever you'd want to use a number. That's why we get a away with +passing n to ffi.string() above. But other Lua +library functions or modules don't know how to deal with this. So for +maximum portability one needs to use tonumber() on returned +long results before passing them on. Otherwise the +application might work on some systems, but would fail in a POSIX/x64 +environment. +
+ ++Here's a list of common C idioms and their translation to the +LuaJIT FFI: +
+| Idiom | +C code | +Lua code | +
| Pointer dereference int *p; | x = *p; *p = y; | x = p[0] p[0] = y |
| Pointer indexing int i, *p; | x = p[i]; p[i+1] = y; | x = p[i] p[i+1] = y |
| Array indexing int i, a[]; | x = a[i]; a[i+1] = y; | x = a[i] a[i+1] = y |
| struct/union dereference struct foo s; | x = s.field; s.field = y; | x = s.field s.field = y |
| struct/union pointer deref. struct foo *sp; | x = sp->field; sp->field = y; | x = s.field s.field = y |
| Pointer arithmetic int i, *p; | x = p + i; y = p - i; | x = p + i y = p - i |
| Pointer difference int *p1, *p2; | x = p1 - p2; | x = p1 - p2 |
| Array element pointer int i, a[]; | x = &a[i]; | x = a+i |
| Cast pointer to address int *p; | x = (intptr_t)p; | x = tonumber( ffi.cast("intptr_t", p)) |
| Functions with outargs void foo(int *inoutlen); | int len = x; foo(&len); y = len; | local len = ffi.new("int[1]", x) foo(len) y = len[0] |
| Vararg conversions int printf(char *fmt, ...); | printf("%g", 1.0); printf("%d", 1); | printf("%g", 1); printf("%d", ffi.new("int", 1)) |
+It's a common Lua idiom to cache library functions in local variables +or upvalues, e.g.: +
++local byte, char = string.byte, string.char +local function foo(x) + return char(byte(x)+1) +end ++
+This replaces several hash-table lookups with a (faster) direct use of +a local or an upvalue. This is less important with LuaJIT, since the +JIT compiler optimizes hash-table lookups a lot and is even able to +hoist most of them out of the inner loops. It can't eliminate +all of them, though, and it saves some typing for often-used +functions. So there's still a place for this, even with LuaJIT. +
++The situation is a bit different with C function calls via the +FFI library. The JIT compiler has special logic to eliminate all +of the lookup overhead for functions resolved from a +C library namespace! +Thus it's not helpful and actually counter-productive to cache +individual C functions like this: +
+
+local funca, funcb = ffi.C.funcb, ffi.C.funcb -- Not helpful!
+local function foo(x, n)
+ for i=1,n do funcb(funca(x, i), 1) end
+end
+
++This turns them into indirect calls and generates bigger and slower +machine code. Instead you'll want to cache the namespace itself and +rely on the JIT compiler to eliminate the lookups: +
+
+local C = ffi.C -- Instead use this!
+local function foo(x, n)
+ for i=1,n do C.funcb(C.funca(x, i), 1) end
+end
+
++This generates both shorter and faster code. So don't cache +C functions, but do cache namespaces! Most often the +namespace is already in a local variable at an outer scope, e.g. from +local lib = ffi.load(...). Note that copying +it to a local variable in the function scope is unnecessary. +