+
+The FFI library allows calling external C functions and the use
+of C data structures from pure Lua code.
+
+
+The FFI library largely obviates the need to write tedious manual
+Lua/C bindings in C. It doesn't require learning a separate binding
+language — it parses plain C declarations, which can be
+cut-n-pasted from C header files or reference manuals. It's up to
+the task of binding large libraries without the need for dealing with
+fragile binding generators.
+
+
+The FFI library is tightly integrated into LuaJIT (it's not available
+as a separate module). The code generated by the JIT-compiler for
+accesses to C data structures from Lua code is on par with the
+code a C compiler would generate. Calls to C functions can
+be inlined in the JIT-compiled code, unlike calls to functions bound
+via the classic Lua/C API.
+
+
+This page gives a short introduction to the usage of the FFI library.
+Please use the FFI sub-topics in the navigation bar to learn more.
+
+
+
Motivating Example: Calling External C Functions
+
+It's really easy to call an external C library function:
+
+
+local ffi = require("ffi")
+ffi.cdef[[
+int printf(const char *fmt, ...);
+]]
+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!
+
+
+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
+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,
+when called, runs the printf function. The arguments passed
+to this function are automatically converted from Lua objects to the
+corresponding C types.
+
+
+Ok, so maybe the use of printf() wasn't such a spectacular
+example. You could have done that with io.write() and
+string.format(), too. But you get the idea ...
+
+
+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);
+]]
+ffi.C.MessageBoxA(nil, "Hello world!", "Test", 0)
+
+
+Bing! Again, that was far too easy, no?
+
+
+Compare this with the effort required to bind that function using the
+classic Lua/C API: create an extra C file, add a C function
+that retrieves and checks the argument types passed from Lua and calls
+the actual C function, add a list of module functions and their
+names, add a luaopen_* function and register all module
+functions, compile and link it into a shared library (DLL), move it to
+the proper path, add Lua code that loads the module aaaand ... finally
+call the binding function. Phew!
+
+
+
Motivating Example: Using C Data Structures
+
+The FFI library allows you to create and access C data
+structures. Of course the main use for this is for interfacing with
+C functions. But they can be used stand-alone, too.
+
+
+Lua is built upon high-level data types. They are flexible, extensible
+and dynamic. That's why we all love Lua so much. Alas, this can be
+inefficient for certain tasks, where you'd really want a low-level
+data type. E.g. a large array of a fixed structure needs to be
+implemented with a big table holding lots of tiny tables. This imposes
+both a substantial memory overhead as well as a performance overhead.
+
+
+Here's a sketch of a library that operates on color images plus a
+simple benchmark. First, the plain Lua version:
+
+
+local floor = math.floor
+
+local function image_ramp_green(n)
+ local img = {}
+ local f = 255/(n-1)
+ for i=1,n do
+ img[i] = { red = 0, green = floor((i-1)*f), blue = 0, alpha = 255 }
+ end
+ return img
+end
+
+local function image_to_grey(img, n)
+ for i=1,n do
+ local y = floor(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
+
+local N = 400*400
+local img = image_ramp_green(N)
+for i=1,1000 do
+ image_to_grey(img, N)
+end
+
+
+This creates a table with 160.000 pixels, each of which is a table
+holding four number values in the range of 0-255. First an image with
+a green ramp is created (1D for simplicity), then the image is
+converted to greyscale 1000 times. Yes, that's silly, but I was in
+need of a simple example ...
+
+
+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 function image_ramp_green(n)
+ local img = ffi.new("rgba_pixel[?]", n)
+ local f = 255/(n-1)
+ 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
+ img[i].red = y; img[i].green = y; img[i].blue = y
+ end
+end
+
+local N = 400*400
+local img = image_ramp_green(N)
+for i=1,1000 do
+ image_to_grey(img, N)
+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.
+
+
+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.
+
+
+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
+consumption for the image is down from 22 Megabytes to
+640 Kilobytes (400*400*4 bytes). That's a factor of 35x less! So,
+yes, tables do have a noticeable overhead. BTW: The original program
+would consume 40 Megabytes in plain Lua (on x64).
+
+
+Next, performance: the pure Lua version runs in 9.57 seconds (52.9
+seconds with the Lua interpreter) and the FFI version runs in 0.48
+seconds on my machine (YMMV). That's a factor of 20x faster (110x
+faster than with plain Lua).
+
+
+The avid reader may notice that converting the pure Lua version over
+to use array indexes for the colors ([1] instead of
+.red, [2] instead of .green etc.) ought to
+be more compact and faster. This is certainly true (by a factor of
+~1.7x), but the resulting code would be less idiomatic and rather
+error-prone. And it still doesn't get even close to the performance of
+the FFI version of the code. Also, high-level data structures cannot
+be easily passed to other C functions, especially I/O functions,
+without undue conversion penalties.
+
+
+
+
+
+
diff --git a/doc/ext_ffi_api.html b/doc/ext_ffi_api.html
new file mode 100644
index 00000000..f985d965
--- /dev/null
+++ b/doc/ext_ffi_api.html
@@ -0,0 +1,410 @@
+
+
+
+
+
+This page describes the API functions provided by the FFI library in
+detail. It's recommended to read through the
+introduction and the
+FFI tutorial first.
+
+
+
Glossary
+
+- cdecl — An abstract C type declaration (a Lua
+string).
+- ctype — A C type object. This is a special kind of
+cdata returned by ffi.typeof(). It serves as a
+cdata constructor when called.
+- cdata — A C data object. It holds a value of the
+corresponding ctype.
+- ct — A C type specification which can be used for
+most of the API functions. Either a cdecl, a ctype or a
+cdata serving as a template type.
+- VLA — A variable-length array is declared with a
+? instead of the number of elements, e.g. "int[?]".
+The number of elements (nelem) must be given when it's
+created.
+- VLS — A variable-length struct is a struct C
+type where the last element is a VLA. The same rules for
+declaration and creation apply.
+
+
+
Declaring and Accessing External Symbols
+
+External symbols must be declared first and can then be accessed by
+indexing a C library
+namespace, which automatically binds the symbol to a specific
+library.
+
+
+
ffi.cdef(def)
+
+Adds multiple C declarations for types or external symbols (named
+variables or functions). def must be a Lua string. It's
+recommended to use the syntactic sugar for string arguments as
+follows:
+
+
+ffi.cdef[[
+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. */
+]]
+
+
+The contents of the string (the part in green above) must be a
+sequence of
+C declarations,
+separated by semicolons. The trailing semicolon for a single
+declaration may be omitted.
+
+
+Please note that external symbols are only declared, but they
+are not bound to any specific address, yet. Binding is
+achieved with C library namespaces (see below).
+
+
+C declarations are not passed through a C pre-processor,
+yet. No pre-processor tokens are allowed, except for
+#pragma pack. Replace #define in existing
+C header files with enum, static const
+or typedef and/or pass the files through an external
+C pre-processor (once). Be careful not to include unneeded or
+redundant declarations from unrelated header files.
+
+
+
ffi.C
+
+This is the default C library namespace — note the
+uppercase 'C'. It binds to the default set of symbols or
+libraries on the target system. These are more or less the same as a
+C compiler would offer by default, without specifying extra link
+libraries.
+
+
+On POSIX systems, this binds to symbols in the default or global
+namespace. This includes all exported symbols from the executable and
+any libraries loaded into the global namespace. This includes at least
+libc, libm, libdl (on Linux),
+libgcc (if compiled with GCC), as well as any exported
+symbols from the Lua/C API provided by LuaJIT itself.
+
+
+On Windows systems, this binds to symbols exported from the
+*.exe, the lua51.dll (i.e. the Lua/C API
+provided by LuaJIT itself), the C runtime library LuaJIT was linked
+with (msvcrt*.dll), kernel32.dll,
+user32.dll and gdi32.dll.
+
+
+
clib = ffi.load(name [,global])
+
+This loads the dynamic library given by name and returns
+a new C library namespace which binds to its symbols. On POSIX
+systems, if global is true, the library symbols are
+loaded into the global namespace, too.
+
+
+If name is a path, the library is loaded from this path.
+Otherwise name is canonicalized in a system-dependent way and
+searched in the default search path for dynamic libraries:
+
+
+On POSIX systems, if the name contains no dot, the extension
+.so is appended. Also, the lib prefix is prepended
+if necessary. So ffi.load("z") looks for "libz.so"
+in the default shared library search path.
+
+
+On Windows systems, if the name contains no dot, the extension
+.dll is appended. So ffi.load("ws2_32") looks for
+"ws2_32.dll" in the default DLL search path.
+
+
+
Creating cdata Objects
+
+The following API functions create cdata objects (type()
+returns "cdata"). All created cdata objects are
+garbage collected.
+
+
+
cdata = ffi.new(ct [,nelem] [,init...])
+cdata = ctype([nelem,] [init...])
+
+Creates a cdata object for the given ct. VLA/VLS types
+require the nelem argument. The second syntax uses a ctype as
+a constructor and is otherwise fully equivalent.
+
+
+The init arguments provide optional initializers. The created
+cdata object is filled with zero bytes if no initializers are given.
+Scalar types accept a single initializer. Aggregates can either be
+initialized with a flat list of initializers or a single aggregate
+initializer (see the C type
+conversion rules). Excess initializers cause an error.
+
+
+If a single initializer is given for an array, it's repeated for all
+remaining elements. This doesn't happen if two or more initializers
+are given — all uninitialized elements are filled with zero
+bytes. The fields of a struct are initialized in the order of
+their declaration. Uninitialized fields are filled with zero bytes.
+Only the first field of union can be initialized with a flat
+initializer. Elements or fields which are aggregates themselves are
+initialized with a single init argument, but this
+may be an aggregate initializer of course.
+
+
+Performance notice: if you want to create many objects of one kind,
+parse the cdecl only once and get its ctype with
+ffi.typeof(). Then use the ctype as a constructor repeatedly.
+
+
+Please note that an anonymous struct declaration implicitly
+creates a new and distinguished ctype every time you use it for
+ffi.new(). This is probably not what you want,
+especially if you create more than one cdata object. Different anonymous
+structs are not considered assignment-compatible by the
+C standard, even though they may have the same fields! Also, they
+are considered different types by the JIT-compiler, which may cause an
+excessive number of traces. It's strongly suggested to either declare
+a named struct or typedef with ffi.cdef()
+or to create a single ctype object for an anonymous struct
+with ffi.typeof().
+
+
+
ctype = ffi.typeof(ct)
+
+Creates a ctype object for the given ct.
+
+
+This function is especially useful to parse a cdecl only once and then
+use the resulting ctype object as a constructor.
+
+
+
cdata = ffi.cast(ct, init)
+
+Creates a scalar cdata object for the given ct. The cdata
+object is initialized with init using the "cast" variant of
+the C type conversion
+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:
+
+
+local addr = tonumber(ffi.cast("intptr_t", ptr))
+
+
+
C Type Information
+
+The following API functions return information about C types.
+They are most useful for inspecting cdata objects.
+
+
+
size = ffi.sizeof(ct [,nelem])
+
+Returns the size of ct in bytes. Returns nil if
+the size is not known (e.g. for "void" or function types).
+Requires nelem for VLA/VLS types, except for cdata objects.
+
+
+
align = ffi.alignof(ct)
+
+Returns the minimum required alignment for ct in bytes.
+
+
+
ofs [,bpos,bsize] = ffi.offsetof(ct, field)
+
+Returns the offset (in bytes) of field relative to the start
+of ct, which must be a struct. Additionally returns
+the position and the field size (in bits) for bit fields.
+
+
+
Utility Functions
+
+
str = ffi.string(ptr [,len])
+
+Creates an interned Lua string from the data pointed to by
+ptr.
+
+
+If the optional argument len is missing, ptr is
+converted to a "char *" and the data is assumed to be
+zero-terminated. The length of the string is computed with
+strlen().
+
+
+Otherwise ptr is converted to a "void *" and
+len gives the length of the data. The data may contain
+embedded zeros and need not be byte-oriented (though this may cause
+endianess issues).
+
+
+This function is mainly useful to convert (temporary)
+"const char *" pointers returned by
+C functions to Lua strings and store them or pass them to other
+functions expecting a Lua string. The Lua string is an (interned) copy
+of the data and bears no relation to the original data area anymore.
+Lua strings are 8 bit clean and may be used to hold arbitrary,
+non-character data.
+
+
+Performance notice: it's faster to pass the length of the string, if
+it's known. E.g. when the length is returned by a C call like
+sprintf().
+
+
+
ffi.copy(dst, src, len)
+ffi.copy(dst, str)
+
+Copies the data pointed to by src to dst.
+dst is converted to a "void *" and src
+is converted to a "const void *".
+
+
+In the first syntax, len gives the number of bytes to copy.
+In case src is a Lua string, the maximum copy length is the
+number of bytes of the string plus a zero-terminator. Caveat: the
+copied data may not be zero-terminated if len ≤ #src.
+
+
+In the second syntax, the source of the copy must be a Lua string. All
+bytes of the string plus a zero-terminator are copied to dst.
+
+
+Performance notice: ffi.copy() may be used as a faster
+(inlineable) replacement for the C library functions
+memcpy(), strcpy() and strncpy().
+
+
+
ffi.fill(dst, len [,c])
+
+Fills the data pointed to by dst with len constant
+bytes, given by c. If c is omitted, the data is
+zero-filled.
+
+
+Performance notice: ffi.fill() may be used as a faster
+(inlineable) replacement for the C library function
+memset(dst, c, len). Please note the different
+order of arguments!
+
+
+
Target-specific Information
+
+
status = ffi.abi(param)
+
+Returns true if param (a Lua string) applies for the
+target ABI (Application Binary Interface). Otherwise returns
+false. The following parameters are currently defined:
+
+
+
+Parameter |
+Description |
+
+
+32bit | 32 bit architecture |
+
+64bit | 64 bit architecture |
+
+le | Little-endian architecture |
+
+be | Big-endian architecture |
+
+fpu | Target has a hardware FPU |
+
+softfp | softfp calling conventions |
+
+hardfp | hardfp calling conventions |
+
+eabi | EABI variant of the standard ABI |
+
+win | Windows variant of the standard ABI |
+
+
+
ffi.os
+
+Contains the target OS name. Same contents as
+jit.os.
+
+
+
ffi.arch
+
+Contains the target architecture name. Same contents as
+jit.arch.
+
+
+
+
+
+
diff --git a/doc/ext_ffi_int64.html b/doc/ext_ffi_int64.html
new file mode 100644
index 00000000..fa155825
--- /dev/null
+++ b/doc/ext_ffi_int64.html
@@ -0,0 +1,73 @@
+
+
+
+
+
+TODO
+
+
+
C Language Support
+
+TODO
+
+
+
C Type Conversion Rules
+
+TODO
+
+
+
C Library Namespaces
+
+A C library namespace is a special kind of object which allows
+access to the symbols contained in libraries. Indexing it with a
+symbol name (a Lua string) automatically binds it to the library.
+
+
+TODO
+
+
+
Operations on cdata Objects
+
+TODO
+
+
+
Garbage Collection of cdata Objects
+
+All explicitly (ffi.new() etc.) or implicitly (accessors)
+created cdata objects are garbage collected. You need to ensure to
+retain valid references to cdata objects somewhere on a Lua stack, an
+upvalue or in a Lua table while they are still in use. Once the last
+reference to a cdata object is gone, the garbage collector will
+automatically free the memory used by it (at the end of the next GC
+cycle).
+
+
+Please note that pointers themselves are cdata objects, however they
+are not followed by the garbage collector. So e.g. if you
+assign a cdata array to a pointer, you must keep the cdata object
+holding the array alive as long as the pointer is still in use:
+
+
+ffi.cdef[[
+typedef struct { int *a; } foo_t;
+]]
+
+local s = ffi.new("foo_t", ffi.new("int[10]")) -- WRONG!
+
+local a = ffi.new("int[10]") -- OK
+local s = ffi.new("foo_t", a)
+-- Now do something with 's', but keep 'a' alive until you're done.
+
+
+Similar rules apply for Lua strings which are implicitly converted to
+"const char *": the string object itself must be
+referenced somewhere or it'll be garbage collected eventually. The
+pointer will then point to stale data, which may have already beeen
+overwritten. Note that string literals are automatically kept alive as
+long as the function containing it (actually its prototype) is not
+garbage collected.
+
+
+Objects which are passed as an argument to an external C function
+are kept alive until the call returns. So it's generally safe to
+create temporary cdata objects in argument lists. This is a common
+idiom for passing specific C types to vararg functions:
+
+
+ffi.cdef[[
+int printf(const char *fmt, ...);
+]]
+ffi.C.printf("integer value: %d\n", ffi.new("int", x)) -- OK
+
+
+Memory areas returned by C functions (e.g. from malloc())
+must be manually managed of course. Pointers to cdata objects are
+indistinguishable from pointers returned by C functions (which is one
+of the reasons why the GC cannot follow them).
+
+
+
TODO
+
+
+
+
+
diff --git a/doc/ext_ffi_tutorial.html b/doc/ext_ffi_tutorial.html
new file mode 100644
index 00000000..11e83339
--- /dev/null
+++ b/doc/ext_ffi_tutorial.html
@@ -0,0 +1,91 @@
+
+
+
+