FFI Semantics

+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

+
+