From 2388a7fcc017b9e9a75a4674aa81933b510882f7 Mon Sep 17 00:00:00 2001
From: Mike Pall <mike>
Date: Tue, 8 Feb 2011 01:20:53 +0100
Subject: [PATCH] FFI: Document current FFI implementation status.

---
 doc/ext_ffi_semantics.html | 91 ++++++++++++++++++++++++++++++++++----
 1 file changed, 82 insertions(+), 9 deletions(-)

diff --git a/doc/ext_ffi_semantics.html b/doc/ext_ffi_semantics.html
index 4a1b6c11..9b7cac70 100644
--- a/doc/ext_ffi_semantics.html
+++ b/doc/ext_ffi_semantics.html
@@ -128,13 +128,13 @@ TODO
 
 <h2 id="gc">Garbage Collection of cdata Objects</h2>
 <p>
-All explicitly (<tt>ffi.new()</tt> 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).
+All explicitly (<tt>ffi.new()</tt>, <tt>ffi.cast()</tt> 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).
 </p>
 <p>
 Please note that pointers themselves are cdata objects, however they
@@ -176,12 +176,85 @@ ffi.C.printf("integer value: %d\n", ffi.new("int", x)) -- <span style="color:#00
 </pre>
 <p>
 Memory areas returned by C functions (e.g. from <tt>malloc()</tt>)
-must be manually managed of course. Pointers to cdata objects are
+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).
 </p>
 
-<h2>TODO</h2>
+<h2 id="status">Current Status</h2>
+<p>
+The initial release of the FFI library has some limitations and is
+missing some features. Most of these will be fixed in future releases.
+</p>
+<p>
+<a href="#clang">C language support</a> is
+currently incomplete:
+</p>
+<ul>
+<li>C&nbsp;declarations are not passed through a C&nbsp;pre-processor,
+yet.</li>
+<li>The C&nbsp;parser is able to evaluate most constant expressions
+commonly found in C&nbsp;header files. However it doesn't handle the
+full range of C&nbsp;expression semantics and may fail for some
+obscure constructs.</li>
+<li><tt>static const</tt> declarations only work for integer types
+up to 32&nbsp;bits. Neither declaring string constants nor
+floating-point constants is supported.</li>
+<li>The <tt>long double</tt> C&nbsp;type is parsed correctly, but
+there's no support for the related conversions, accesses or
+arithmetic operations.</li>
+<li>Packed <tt>struct</tt> bitfields that cross container boundaries
+are not implemented.</li>
+<li>Native vector types may be defined with the GCC <tt>mode</tt> and
+<tt>vector_size</tt> attributes. But no operations other than loading,
+storing and initializing them are supported, yet.</li>
+<li>The <tt>volatile</tt> type qualifier is currently ignored by
+compiled code.</li>
+<li><a href="ext_ffi_api.html#ffi_cdef">ffi.cdef</a> silently ignores
+all redeclarations.</li>
+</ul>
+<p>
+The JIT compiler already handles a large subset of all FFI operations.
+It automatically falls back to the interpreter for unimplemented
+operations (you can check for this with the
+<a href="running.html#opt_j"><tt>-jv</tt></a> command line option).
+The following operations are currently not compiled and may exhibit
+suboptimal performance, especially when used in inner loops:
+</p>
+<ul>
+<li>Array/<tt>struct</tt> copies and bulk initializations.</li>
+<li>Bitfield accesses and initializations.</li>
+<li>Vector operations.</li>
+<li>Lua tables as compound initializers.</li>
+<li>Initialization of nested <tt>struct</tt>/<tt>union</tt> types.</li>
+<li>Allocations of variable-length arrays or structs.</li>
+<li>Allocations of C&nbsp;types with a size &gt; 64&nbsp;bytes or an
+alignment &gt; 8&nbsp;bytes.</li>
+<li>Conversions from <tt>lightuserdata</tt> to <tt>void&nbsp;*</tt>.</li>
+<li>Pointer differences for element sizes that are not a power of
+two.</li>
+<li>Calls to non-cdecl or vararg C&nbsp;functions.</li>
+<li>Calls to C&nbsp;functions with aggregates passed or returned by
+value.</li>
+<li>Calls to C&nbsp;functions with 64 bit arguments or return values
+on 32 bit CPUs.</li>
+<li><tt>tostring()</tt> for cdata types.</li>
+<li>The following <a href="ext_ffi_api.html">ffi.* API</a> functions:
+<tt>ffi.sizeof()</tt>, <tt>ffi.alignof()</tt>, <tt>ffi.offsetof()</tt>.
+</ul>
+<p>
+Other missing features:
+</p>
+<ul>
+<li>Bit operations for 64&nbsp;bit types.</li>
+<li>Arithmetic for <tt>complex</tt> numbers.</li>
+<li>User-defined metamethods for C&nbsp;types.</li>
+<li>Callbacks from C&nbsp;code to Lua functions.</li>
+<li>Atomic handling of <tt>errno</tt>.</li>
+<li>Passing structs by value to vararg C&nbsp;functions.</li>
+<li><a href="extensions.html#exceptions">C++ exception interoperability<a/>
+does not extend to C&nbsp;functions called via the FFI.</li>
+</ul>
 <br class="flush">
 </div>
 <div id="foot">