| blob | 6b846c4104019589654e8f52219a002302e04736 |
2 <html>
3 <head>
10 </head>
11 <body>
14 </div>
17 </div>
19 <ul><li>
21 <ul><li>
23 </li><li>
25 </li><li>
27 </li></ul>
28 </li><li>
30 <ul><li>
32 <ul><li>
34 </li><li>
36 </li><li>
38 </li></ul>
39 </li><li>
41 </li><li>
43 </li></ul>
44 </li><li>
46 </li><li>
48 </li><li>
50 </li><li>
52 </li></ul>
53 </div>
55 <p>
60 </p>
61 <p>
63 The FFI library largely obviates the need to write tedious manual
64 Lua/C bindings in C. No need to learn a separate binding language
66 cut-n-pasted from C header files or reference manuals. It's up to
67 the task of binding large libraries without the need for dealing with
68 fragile binding generators.
70 </p>
71 <p>
72 The FFI library is tightly integrated into LuaJIT (it's not available
73 as a separate module). The code generated by the JIT-compiler for
74 accesses to C data structures from Lua code is on par with the
76 be inlined in JIT-compiled code, unlike calls to functions bound via
77 the classic Lua/C API.
78 </p>
79 <p>
80 This page gives a short introduction to the usage of the FFI library.
82 </p>
85 <p>
86 It's really easy to call an external C library function:
87 </p>
90 ②
94 ffi.cdef[[
96 ]]
98 </pre>
99 <p>
100 So, let's pick that apart:
101 </p>
102 <p>
104 </p>
105 <p>
107 for the function. The part inside the double-brackets (in green) is
108 just standard C syntax.
109 </p>
110 <p>
113 </p>
115 Actually, what goes on behind the scenes is far from simple: <span
119 standard C library. The result is a special kind of object which,
121 to this function are automatically converted from Lua objects to the
122 corresponding C types.
123 </p>
124 <p>
128 </p>
129 <p>
130 So here's something to pop up a message box on Windows:
131 </p>
133 local ffi = require("ffi")
134 ffi.cdef[[
135 <span style="color:#00a000;">int MessageBoxA(void *w, const char *txt, const char *cap, int type);</span>
136 ]]
138 </pre>
139 <p>
140 Bing! Again, that was far too easy, no?
141 </p>
143 Compare this with the effort required to bind that function using the
145 that retrieves and checks the argument types passed from Lua and calls
146 the actual C function, add a list of module functions and their
148 functions, compile and link it into a shared library (DLL), move it to
149 the proper path, add Lua code that loads the module aaaand ... finally
150 call the binding function. Phew!
151 </p>
154 <p>
155 The FFI library allows you to create and access C data
156 structures. Of course the main use for this is for interfacing with
157 C functions. But they can be used stand-alone, too.
158 </p>
159 <p>
160 Lua is built upon high-level data types. They are flexible, extensible
161 and dynamic. That's why we all love Lua so much. Alas, this can be
162 inefficient for certain tasks, where you'd really want a low-level
163 data type. E.g. a large array of a fixed structure needs to be
164 implemented with a big table holding lots of tiny tables. This imposes
165 both a substantial memory overhead as well as a performance overhead.
166 </p>
167 <p>
168 Here's a sketch of a library that operates on color images plus a
169 simple benchmark. First, the plain Lua version:
170 </p>
172 local floor = math.floor
174 local function image_ramp_green(n)
175 local img = {}
177 for i=1,n do
179 end
180 return img
181 end
183 local function image_to_grey(img, n)
184 for i=1,n do
186 img[i].red = y; img[i].green = y; img[i].blue = y
187 end
188 end
191 local img = image_ramp_green(N)
193 image_to_grey(img, N)
194 end
195 </pre>
196 <p>
197 This creates a table with 160.000 pixels, each of which is a table
199 a green ramp is created (1D for simplicity), then the image is
200 converted to greyscale 1000 times. Yes, that's silly, but I was in
201 need of a simple example ...
202 </p>
203 <p>
204 And here's the FFI version. The modified parts have been marked in
205 bold:
206 </p>
214 ②
216 ③
217 ④
224 ③
226 ffi.cdef[[
227 </b><span style="color:#00a000;">typedef struct { uint8_t red, green, blue, alpha; } rgba_pixel;</span><b>
228 ]]</b>
230 local function image_ramp_green(n)
236 end
237 return img
238 end
240 local function image_to_grey(img, n)
243 img[i].red = y; img[i].green = y; img[i].blue = y
244 end
245 end
248 local img = image_ramp_green(N)
250 image_to_grey(img, N)
251 end
252 </pre>
253 <p>
254 Ok, so that wasn't too difficult:
255 </p>
256 <p>
258 library and declare the low-level data type. Here we choose a
261 </p>
262 <p>
266 variable-length array.
267 </p>
268 <p>
272 simplify converting legacy code.
273 </p>
274 <p>
276 zero-fills the array by default, we only need to set the green and the
277 alpha fields.
278 </p>
279 <p>
282 numbers are already truncated towards zero when converting them to an
283 integer. This happens implicitly when the number is stored in the
284 fields of each pixel.
285 </p>
286 <p>
287 Now let's have a look at the impact of the changes: first, memory
290 yes, tables do have a noticeable overhead. BTW: The original program
292 </p>
293 <p>
295 seconds with the Lua interpreter) and the FFI version runs in 0.48
297 faster than the Lua interpreter).
298 </p>
300 The avid reader may notice that converting the pure Lua version over
303 be more compact and faster. This is certainly true (by a factor of
304 ~1.7x). Switching to a struct-of-arrays would help, too.
305 </p>
307 However the resulting code would be less idiomatic and rather
308 error-prone. And it still doesn't get even close to the performance of
309 the FFI version of the code. Also, high-level data structures cannot
310 be easily passed to other C functions, especially I/O functions,
311 without undue conversion penalties.
312 </p>
314 </div>
319 ·
321 </span>
322 </div>
323 </body>
324 </html>