diff options
Diffstat (limited to 'libs/luajit-cmake/luajit/doc/ext_ffi_tutorial.html')
| -rw-r--r-- | libs/luajit-cmake/luajit/doc/ext_ffi_tutorial.html | 597 |
1 files changed, 597 insertions, 0 deletions
diff --git a/libs/luajit-cmake/luajit/doc/ext_ffi_tutorial.html b/libs/luajit-cmake/luajit/doc/ext_ffi_tutorial.html new file mode 100644 index 0000000..ff0c3a9 --- /dev/null +++ b/libs/luajit-cmake/luajit/doc/ext_ffi_tutorial.html @@ -0,0 +1,597 @@ +<!DOCTYPE html> +<html> +<head> +<title>FFI Tutorial</title> +<meta charset="utf-8"> +<meta name="Copyright" content="Copyright (C) 2005-2022"> +<meta name="Language" content="en"> +<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen"> +<link rel="stylesheet" type="text/css" href="bluequad-print.css" media="print"> +<style type="text/css"> +table.idiomtable { font-size: 90%; line-height: 1.2; } +table.idiomtable tt { font-size: 100%; } +table.idiomtable td { vertical-align: top; } +tr.idiomhead td { font-weight: bold; } +td.idiomlua b { font-weight: normal; color: #2142bf; } +</style> +</head> +<body> +<div id="site"> +<a href="https://luajit.org"><span>Lua<span id="logo">JIT</span></span></a> +</div> +<div id="head"> +<h1>FFI Tutorial</h1> +</div> +<div id="nav"> +<ul><li> +<a href="luajit.html">LuaJIT</a> +<ul><li> +<a href="https://luajit.org/download.html">Download <span class="ext">»</span></a> +</li><li> +<a href="install.html">Installation</a> +</li><li> +<a href="running.html">Running</a> +</li></ul> +</li><li> +<a href="extensions.html">Extensions</a> +<ul><li> +<a href="ext_ffi.html">FFI Library</a> +<ul><li> +<a class="current" href="ext_ffi_tutorial.html">FFI Tutorial</a> +</li><li> +<a href="ext_ffi_api.html">ffi.* API</a> +</li><li> +<a href="ext_ffi_semantics.html">FFI Semantics</a> +</li></ul> +</li><li> +<a href="ext_buffer.html">String Buffers</a> +</li><li> +<a href="ext_jit.html">jit.* Library</a> +</li><li> +<a href="ext_c_api.html">Lua/C API</a> +</li><li> +<a href="ext_profiler.html">Profiler</a> +</li></ul> +</li><li> +<a href="status.html">Status</a> +</li><li> +<a href="faq.html">FAQ</a> +</li><li> +<a href="https://luajit.org/list.html">Mailing List <span class="ext">»</span></a> +</li></ul> +</div> +<div id="main"> +<p> +This page is intended to give you an overview of the features of the FFI +library by presenting a few use cases and guidelines. +</p> +<p> +This page makes no attempt to explain all of the FFI library, though. +You'll want to have a look at the <a href="ext_ffi_api.html">ffi.* API +function reference</a> and the <a href="ext_ffi_semantics.html">FFI +semantics</a> to learn more. +</p> + +<h2 id="load">Loading the FFI Library</h2> +<p> +The FFI library is built into LuaJIT by default, but it's not loaded +and initialized by default. The suggested way to use the FFI library +is to add the following to the start of every Lua file that needs one +of its functions: +</p> +<pre class="code"> +local ffi = require("ffi") +</pre> +<p> +Please note, this doesn't define an <tt>ffi</tt> variable in the table +of globals — you really need to use the local variable. The +<tt>require</tt> function ensures the library is only loaded once. +</p> +<p style="font-size: 8pt;"> +Note: If you want to experiment with the FFI from the interactive prompt +of the command line executable, omit the <tt>local</tt>, as it doesn't +preserve local variables across lines. +</p> + +<h2 id="sleep">Accessing Standard System Functions</h2> +<p> +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: +</p> +<pre class="code mark"> +<span class="codemark"> +① + + + + + +② +③ +④ + + + +⑤ + + + + + +⑥</span>local ffi = require("ffi") +ffi.cdef[[ +<span style="color:#00a000;">void Sleep(int ms); +int poll(struct pollfd *fds, unsigned long nfds, int timeout);</span> +]] + +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") +</pre> +<p> +Here's the step-by-step explanation: +</p> +<p> +<span class="mark">①</span> 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. +</p> +<p> +<span class="mark">②</span> The difficulty we're +facing here, is that there are different standards to choose from. +Windows has a simple <tt>Sleep()</tt> function. On other systems there +are a variety of functions available to achieve sub-second sleeps, but +with no clear consensus. Thankfully <tt>poll()</tt> can be used for +this task, too, and it's present on most non-Windows systems. The +check for <tt>ffi.os</tt> makes sure we use the Windows-specific +function only on Windows systems. +</p> +<p> +<span class="mark">③</span> 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. +</p> +<p> +<span class="mark">④</span> A more subtle point is +that we defined our <tt>sleep()</tt> 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 +<tt>Sleep()</tt> 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). +</p> +<p style="font-size: 8pt;"> +Some readers will notice that <tt>Sleep()</tt> is part of +<tt>KERNEL32.DLL</tt> and is also a <tt>stdcall</tt> function. So how +can this possibly work? The FFI library provides the <tt>ffi.C</tt> +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 <tt>stdcall</tt> functions, so you +don't need to declare them as such. +</p> +<p> +<span class="mark">⑤</span> The <tt>poll()</tt> +function takes a couple more arguments we're not going to use. You can +simply use <tt>nil</tt> to pass a <tt>NULL</tt> pointer and <tt>0</tt> +for the <tt>nfds</tt> parameter. Please note, that the +number <tt>0</tt> <em>does not convert to a pointer value</em>, +unlike in C++. You really have to pass pointers to pointer arguments +and numbers to number arguments. +</p> +<p style="font-size: 8pt;"> +The page on <a href="ext_ffi_semantics.html">FFI semantics</a> has all +of the gory details about +<a href="ext_ffi_semantics.html#convert">conversions between Lua +objects and C types</a>. 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. +</p> +<p> +<span class="mark">⑥</span> Now that we have defined +our own <tt>sleep()</tt> 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. +:-) +</p> + +<h2 id="zlib">Accessing the zlib Compression Library</h2> +<p> +The following code shows how to access the <a +href="https://zlib.net/"><span class="ext">»</span> zlib</a> compression library from Lua code. +We'll define two convenience wrapper functions that take a string and +compress or uncompress it to another string: +</p> +<pre class="code mark"> +<span class="codemark"> +① + + + + + + +② + + +③ + +④ + + +⑤ + + +⑥ + + + + + + + +⑦</span>local ffi = require("ffi") +ffi.cdef[[ +<span style="color:#00a000;">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);</span> +]] +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) +</pre> +<p> +Here's the step-by-step explanation: +</p> +<p> +<span class="mark">①</span> 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 predefined +fixed-size integer types, while still adhering to the zlib API/ABI. +</p> +<p> +<span class="mark">②</span> This loads the zlib shared +library. On POSIX systems, it's named <tt>libz.so</tt> and usually +comes pre-installed. Since <tt>ffi.load()</tt> automatically adds any +missing standard prefixes/suffixes, we can simply load the +<tt>"z"</tt> library. On Windows it's named <tt>zlib1.dll</tt> and +you'll have to download it first from the +<a href="https://zlib.net/"><span class="ext">»</span> zlib site</a>. The check for +<tt>ffi.os</tt> makes sure we pass the right name to +<tt>ffi.load()</tt>. +</p> +<p> +<span class="mark">③</span> First, the maximum size of +the compression buffer is obtained by calling the +<tt>zlib.compressBound</tt> function with the length of the +uncompressed string. The next line allocates a byte buffer of this +size. The <tt>[?]</tt> 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 <tt>ffi.new()</tt>. +</p> +<p> +<span class="mark">④</span> This may look strange at +first, but have a look at the declaration of the <tt>compress2</tt> +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. +</p> +<p> +In C you'd pass in the address of a local variable +(<tt>&buflen</tt>). 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 <tt>zlib.compress2</tt> function is then straightforward. +</p> +<p> +<span class="mark">⑤</span> We want to return the +compressed data as a Lua string, so we'll use <tt>ffi.string()</tt>. +It needs a pointer to the start of the data and the actual length. The +length has been returned in the <tt>buflen</tt> array, so we'll just +get it from there. +</p> +<p style="font-size: 8pt;"> +Note that since the function returns now, the <tt>buf</tt> and +<tt>buflen</tt> variables will eventually be garbage collected. This +is fine, because <tt>ffi.string()</tt> 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. +</p> +<p> +<span class="mark">⑥</span> The <tt>uncompress</tt> +functions does the exact opposite of the <tt>compress</tt> function. +The compressed data doesn't include the size of the original string, +so this needs to be passed in. Otherwise, no surprises here. +</p> +<p> +<span class="mark">⑦</span> 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. +</p> +<p> +One major advantage of the LuaJIT FFI is that you are now able to +write those wrappers <em>in Lua</em>. 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. +</p> +<p style="font-size: 8pt;"> +Side note: the zlib API uses the <tt>long</tt> 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. +</p> +<p style="font-size: 8pt;"> +First, you should know that a <tt>long</tt> 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 <tt>long</tt> result can be either a plain +Lua number or a boxed 64 bit integer cdata object, depending on +the target system. +</p> +<p style="font-size: 8pt;"> +Ok, so the <tt>ffi.*</tt> functions generally accept cdata objects +wherever you'd want to use a number. That's why we get a away with +passing <tt>n</tt> to <tt>ffi.string()</tt> above. But other Lua +library functions or modules don't know how to deal with this. So for +maximum portability, one needs to use <tt>tonumber()</tt> on returned +<tt>long</tt> results before passing them on. Otherwise the +application might work on some systems, but would fail in a POSIX/x64 +environment. +</p> + +<h2 id="metatype">Defining Metamethods for a C Type</h2> +<p> +The following code explains how to define metamethods for a C type. +We define a simple point type and add some operations to it: +</p> +<pre class="code mark"> +<span class="codemark"> +① + + + +② + +③ + +④ + + + +⑤ + +⑥</span>local ffi = require("ffi") +ffi.cdef[[ +<span style="color:#00a000;">typedef struct { double x, y; } point_t;</span> +]] + +local point +local mt = { + __add = function(a, b) return point(a.x+b.x, a.y+b.y) end, + __len = function(a) return math.sqrt(a.x*a.x + a.y*a.y) end, + __index = { + area = function(a) return a.x*a.x + a.y*a.y end, + }, +} +point = ffi.metatype("point_t", mt) + +local a = point(3, 4) +print(a.x, a.y) --> 3 4 +print(#a) --> 5 +print(a:area()) --> 25 +local b = a + point(0.5, 8) +print(#b) --> 12.5 +</pre> +<p> +Here's the step-by-step explanation: +</p> +<p> +<span class="mark">①</span> This defines the C type for a +two-dimensional point object. +</p> +<p> +<span class="mark">②</span> We have to declare the variable +holding the point constructor first, because it's used inside of a +metamethod. +</p> +<p> +<span class="mark">③</span> Let's define an <tt>__add</tt> +metamethod which adds the coordinates of two points and creates a new +point object. For simplicity, this function assumes that both arguments +are points. But it could be any mix of objects, if at least one operand +is of the required type (e.g. adding a point plus a number or vice +versa). Our <tt>__len</tt> metamethod returns the distance of a point to +the origin. +</p> +<p> +<span class="mark">④</span> If we run out of operators, we can +define named methods, too. Here, the <tt>__index</tt> table defines an +<tt>area</tt> function. For custom indexing needs, one might want to +define <tt>__index</tt> and <tt>__newindex</tt> <em>functions</em> instead. +</p> +<p> +<span class="mark">⑤</span> This associates the metamethods with +our C type. This only needs to be done once. For convenience, a +constructor is returned by +<a href="ext_ffi_api.html#ffi_metatype"><tt>ffi.metatype()</tt></a>. +We're not required to use it, though. The original C type can still +be used e.g. to create an array of points. The metamethods automatically +apply to any and all uses of this type. +</p> +<p> +Please note, that the association with a metatable is permanent and +<b>the metatable must not be modified afterwards!</b> Ditto for the +<tt>__index</tt> table. +</p> +<p> +<span class="mark">⑥</span> Here are some simple usage examples +for the point type and their expected results. The predefined +operations (such as <tt>a.x</tt>) can be freely mixed with the newly +defined metamethods. Note that <tt>area</tt> is a method and must be +called with the Lua syntax for methods: <tt>a:area()</tt>, not +<tt>a.area()</tt>. +</p> +<p> +The C type metamethod mechanism is most useful when used in +conjunction with C libraries that are written in an object-oriented +style. Creators return a pointer to a new instance, and methods take an +instance pointer as the first argument. Sometimes you can just point +<tt>__index</tt> to the library namespace and <tt>__gc</tt> to the +destructor and you're done. But often enough you'll want to add +convenience wrappers, e.g. to return actual Lua strings or when +returning multiple values. +</p> +<p> +Some C libraries only declare instance pointers as an opaque +<tt>void *</tt> type. In this case you can use a fake type for all +declarations, e.g. a pointer to a named (incomplete) struct will do: +<tt>typedef struct foo_type *foo_handle</tt>. The C side doesn't +know what you declare with the LuaJIT FFI, but as long as the underlying +types are compatible, everything still works. +</p> + +<h2 id="idioms">Translating C Idioms</h2> +<p> +Here's a list of common C idioms and their translation to the +LuaJIT FFI: +</p> +<table class="idiomtable"> +<tr class="idiomhead"> +<td class="idiomdesc">Idiom</td> +<td class="idiomc">C code</td> +<td class="idiomlua">Lua code</td> +</tr> +<tr class="odd separate"> +<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> +<tr class="even"> +<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> +<tr class="odd"> +<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> +<tr class="even separate"> +<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> +<tr class="odd"> +<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> +<tr class="even separate"> +<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> +<tr class="odd"> +<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> +<tr class="even"> +<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> +<tr class="odd"> +<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> +<tr class="even separate"> +<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> +<tr class="odd"> +<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> +</table> + +<h2 id="cache">To Cache or Not to Cache</h2> +<p> +It's a common Lua idiom to cache library functions in local variables +or upvalues, e.g.: +</p> +<pre class="code"> +local byte, char = string.byte, string.char +local function foo(x) + return char(byte(x)+1) +end +</pre> +<p> +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 +<em>all</em> of them, though, and it saves some typing for often-used +functions. So there's still a place for this, even with LuaJIT. +</p> +<p> +The situation is a bit different with C function calls via the +FFI library. The JIT compiler has special logic to eliminate <em>all +of the lookup overhead</em> for functions resolved from a +<a href="ext_ffi_semantics.html#clib">C library namespace</a>! +Thus it's not helpful and actually counter-productive to cache +individual C functions like this: +</p> +<pre class="code"> +local <b>funca</b>, <b>funcb</b> = ffi.C.funca, ffi.C.funcb -- <span style="color:#c00000;">Not helpful!</span> +local function foo(x, n) + for i=1,n do <b>funcb</b>(<b>funca</b>(x, i), 1) end +end +</pre> +<p> +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: +</p> +<pre class="code"> +local <b>C</b> = ffi.C -- <span style="color:#00a000;">Instead use this!</span> +local function foo(x, n) + for i=1,n do <b>C.funcb</b>(<b>C.funca</b>(x, i), 1) end +end +</pre> +<p> +This generates both shorter and faster code. So <b>don't cache +C functions</b>, but <b>do</b> cache namespaces! Most often the +namespace is already in a local variable at an outer scope, e.g. from +<tt>local lib = ffi.load(...)</tt>. Note that copying +it to a local variable in the function scope is unnecessary. +</p> +<br class="flush"> +</div> +<div id="foot"> +<hr class="hide"> +Copyright © 2005-2022 +<span class="noprint"> +· +<a href="contact.html">Contact</a> +</span> +</div> +</body> +</html> |