From 72b3fff72f6bb9cf5796bbcd50e9a490d4e02b4b Mon Sep 17 00:00:00 2001 From: Mike Pall Date: Sun, 23 Jan 2011 14:23:21 +0100 Subject: FFI: Simplify initializer rules. Clarify docs. --- doc/ext_ffi.html | 11 +++++++---- doc/ext_ffi_api.html | 25 ++++++------------------- doc/ext_ffi_semantics.html | 41 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 54 insertions(+), 23 deletions(-) (limited to 'doc') diff --git a/doc/ext_ffi.html b/doc/ext_ffi.html index e8e2a62b..f496b51b 100644 --- a/doc/ext_ffi.html +++ b/doc/ext_ffi.html @@ -73,8 +73,8 @@ 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. +be inlined in 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. @@ -253,14 +253,17 @@ 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). +faster than the Lua interpreter).

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 +~1.7x). Switching to a struct-of-arrays would help, too. +

+

+However 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, diff --git a/doc/ext_ffi_api.html b/doc/ext_ffi_api.html index f985d965..f0c4de90 100644 --- a/doc/ext_ffi_api.html +++ b/doc/ext_ffi_api.html @@ -195,23 +195,10 @@ 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. +The cdata object is initialized according to the +rules for initializers, +using the optional init arguments. Excess initializers cause +an error.

Performance notice: if you want to create many objects of one kind, @@ -357,8 +344,8 @@ order of arguments!

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: +target ABI (Application Binary Interface). Returns false +otherwise. The following parameters are currently defined:

diff --git a/doc/ext_ffi_semantics.html b/doc/ext_ffi_semantics.html index 598d44c9..4a1b6c11 100644 --- a/doc/ext_ffi_semantics.html +++ b/doc/ext_ffi_semantics.html @@ -70,6 +70,47 @@ TODO TODO

+

Initializers

+

+Creating a cdata object with ffi.new() +or the equivalent constructor syntax always initializes its contents, +too. Different rules apply, depending on the number of optional +initializers and the C types involved: +

+ +

C Library Namespaces

A C library namespace is a special kind of object which allows -- cgit v1.2.3-55-g6feb