|
@@ -84,7 +84,7 @@ footprint. It's used by the <a href="ext_ffi_api.html">ffi.* library
|
|
|
functions</a> to declare C types or external symbols.
|
|
|
</p>
|
|
|
<p>
|
|
|
-It's only purpose is to parse C declarations, as found e.g. in
|
|
|
+Its only purpose is to parse C declarations, as found e.g. in
|
|
|
C header files. Although it does evaluate constant expressions,
|
|
|
it's <em>not</em> a C compiler. The body of <tt>inline</tt>
|
|
|
C function definitions is simply ignored.
|
|
@@ -161,7 +161,7 @@ function declarations.</li>
|
|
|
|
|
|
</ul>
|
|
|
<p>
|
|
|
-The following C types are pre-defined by the C parser (like
|
|
|
+The following C types are predefined by the C parser (like
|
|
|
a <tt>typedef</tt>, except re-declarations will be ignored):
|
|
|
</p>
|
|
|
<ul>
|
|
@@ -577,9 +577,9 @@ ffi.new("struct nested", {x=1,y={2,3}}) --> x = 1, y.a = 2, y.b = 3
|
|
|
|
|
|
<h2 id="cdata_ops">Operations on cdata Objects</h2>
|
|
|
<p>
|
|
|
-All of the standard Lua operators can be applied to cdata objects or a
|
|
|
+All standard Lua operators can be applied to cdata objects or a
|
|
|
mix of a cdata object and another Lua object. The following list shows
|
|
|
-the pre-defined operations.
|
|
|
+the predefined operations.
|
|
|
</p>
|
|
|
<p>
|
|
|
Reference types are dereferenced <em>before</em> performing each of
|
|
@@ -587,7 +587,7 @@ the operations below — the operation is applied to the
|
|
|
C type pointed to by the reference.
|
|
|
</p>
|
|
|
<p>
|
|
|
-The pre-defined operations are always tried first before deferring to a
|
|
|
+The predefined operations are always tried first before deferring to a
|
|
|
metamethod or index table (if any) for the corresponding ctype (except
|
|
|
for <tt>__new</tt>). An error is raised if the metamethod lookup or
|
|
|
index table lookup fails.
|
|
@@ -637,7 +637,7 @@ assigning to an index of a vector raises an error.</li>
|
|
|
</ul>
|
|
|
<p>
|
|
|
A ctype object can be indexed with a string key, too. The only
|
|
|
-pre-defined operation is reading scoped constants of
|
|
|
+predefined operation is reading scoped constants of
|
|
|
<tt>struct</tt>/<tt>union</tt> types. All other accesses defer
|
|
|
to the corresponding metamethods or index tables (if any).
|
|
|
</p>
|
|
@@ -650,7 +650,7 @@ certain optimizations.
|
|
|
<p>
|
|
|
As a consequence, the <em>elements</em> of complex numbers and
|
|
|
vectors are immutable. But the elements of an aggregate holding these
|
|
|
-types <em>may</em> be modified of course. I.e. you cannot assign to
|
|
|
+types <em>may</em> be modified, of course. I.e. you cannot assign to
|
|
|
<tt>foo.c.im</tt>, but you can assign a (newly created) complex number
|
|
|
to <tt>foo.c</tt>.
|
|
|
</p>
|
|
@@ -669,8 +669,8 @@ through unions is explicitly detected and allowed.
|
|
|
to <tt>ffi.new(ct, ...)</tt>, unless a <tt>__new</tt> metamethod is
|
|
|
defined. The <tt>__new</tt> metamethod is called with the ctype object
|
|
|
plus any other arguments passed to the constructor. Note that you have to
|
|
|
-use <tt>ffi.new</tt> inside of it, since calling <tt>ct(...)</tt> would
|
|
|
-cause infinite recursion.</li>
|
|
|
+use <tt>ffi.new</tt> inside the metamethod, since calling <tt>ct(...)</tt>
|
|
|
+would cause infinite recursion.</li>
|
|
|
|
|
|
<li><b>C function call</b>: a cdata function or cdata function
|
|
|
pointer can be called. The passed arguments are
|
|
@@ -681,7 +681,7 @@ variable argument part of vararg C function use
|
|
|
C function is called and the return value (if any) is
|
|
|
<a href="#convert_tolua">converted to a Lua object</a>.<br>
|
|
|
On Windows/x86 systems, <tt>__stdcall</tt> functions are automatically
|
|
|
-detected and a function declared as <tt>__cdecl</tt> (the default) is
|
|
|
+detected, and a function declared as <tt>__cdecl</tt> (the default) is
|
|
|
silently fixed up after the first call.</li>
|
|
|
|
|
|
</ul>
|
|
@@ -691,7 +691,7 @@ silently fixed up after the first call.</li>
|
|
|
|
|
|
<li><b>Pointer arithmetic</b>: a cdata pointer/array and a cdata
|
|
|
number or a Lua number can be added or subtracted. The number must be
|
|
|
-on the right hand side for a subtraction. The result is a pointer of
|
|
|
+on the right-hand side for a subtraction. The result is a pointer of
|
|
|
the same type with an address plus or minus the number value
|
|
|
multiplied by the element size in bytes. An error is raised if the
|
|
|
element size is undefined.</li>
|
|
@@ -706,7 +706,7 @@ operators (<tt>+ - * / % ^</tt> and unary
|
|
|
minus) can be applied to two cdata numbers, or a cdata number and a
|
|
|
Lua number. If one of them is an <tt>uint64_t</tt>, the other side is
|
|
|
converted to an <tt>uint64_t</tt> and an unsigned arithmetic operation
|
|
|
-is performed. Otherwise both sides are converted to an
|
|
|
+is performed. Otherwise, both sides are converted to an
|
|
|
<tt>int64_t</tt> and a signed arithmetic operation is performed. The
|
|
|
result is a boxed 64 bit cdata object.<br>
|
|
|
|
|
@@ -737,7 +737,7 @@ which is compatible with any other pointer type.</li>
|
|
|
<li><b>64 bit integer comparison</b>: two cdata numbers, or a
|
|
|
cdata number and a Lua number can be compared with each other. If one
|
|
|
of them is an <tt>uint64_t</tt>, the other side is converted to an
|
|
|
-<tt>uint64_t</tt> and an unsigned comparison is performed. Otherwise
|
|
|
+<tt>uint64_t</tt> and an unsigned comparison is performed. Otherwise,
|
|
|
both sides are converted to an <tt>int64_t</tt> and a signed
|
|
|
comparison is performed.<br>
|
|
|
|
|
@@ -762,9 +762,9 @@ keys!</b>
|
|
|
A cdata object is treated like any other garbage-collected object and
|
|
|
is hashed and compared by its address for table indexing. Since
|
|
|
there's no interning for cdata value types, the same value may be
|
|
|
-boxed in different cdata objects with different addresses. Thus
|
|
|
+boxed in different cdata objects with different addresses. Thus,
|
|
|
<tt>t[1LL+1LL]</tt> and <tt>t[2LL]</tt> usually <b>do not</b> point to
|
|
|
-the same hash slot and they certainly <b>do not</b> point to the same
|
|
|
+the same hash slot, and they certainly <b>do not</b> point to the same
|
|
|
hash slot as <tt>t[2]</tt>.
|
|
|
</p>
|
|
|
<p>
|
|
@@ -786,7 +786,7 @@ the resulting Lua number as a key when indexing tables.<br>
|
|
|
One obvious benefit: <tt>t[tonumber(2LL)]</tt> <b>does</b> point to
|
|
|
the same slot as <tt>t[2]</tt>.</li>
|
|
|
|
|
|
-<li>Otherwise use either <tt>tostring()</tt> on 64 bit integers
|
|
|
+<li>Otherwise, use either <tt>tostring()</tt> on 64 bit integers
|
|
|
or complex numbers or combine multiple fields of a cdata aggregate to
|
|
|
a Lua string (e.g. with
|
|
|
<a href="ext_ffi_api.html#ffi_string"><tt>ffi.string()</tt></a>). Then
|
|
@@ -794,7 +794,7 @@ use the resulting Lua string as a key when indexing tables.</li>
|
|
|
|
|
|
<li>Create your own specialized hash table implementation using the
|
|
|
C types provided by the FFI library, just like you would in
|
|
|
-C code. Ultimately this may give much better performance than the
|
|
|
+C code. Ultimately, this may give much better performance than the
|
|
|
other alternatives or what a generic by-value hash table could
|
|
|
possibly provide.</li>
|
|
|
|
|
@@ -860,7 +860,7 @@ 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
|
|
|
+Please note, that pointers themselves are cdata objects, however they
|
|
|
are <b>not</b> 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:
|
|
@@ -909,18 +909,18 @@ of the function pointer and the Lua function object (closure).
|
|
|
</p>
|
|
|
<p>
|
|
|
This can happen implicitly due to the usual conversions, e.g. when
|
|
|
-passing a Lua function to a function pointer argument. Or you can use
|
|
|
+passing a Lua function to a function pointer argument. Or, you can use
|
|
|
<tt>ffi.cast()</tt> to explicitly cast a Lua function to a
|
|
|
C function pointer.
|
|
|
</p>
|
|
|
<p>
|
|
|
-Currently only certain C function types can be used as callback
|
|
|
+Currently, only certain C function types can be used as callback
|
|
|
functions. Neither C vararg functions nor functions with
|
|
|
pass-by-value aggregate argument or result types are supported. There
|
|
|
-are no restrictions for the kind of Lua functions that can be called
|
|
|
+are no restrictions on the kind of Lua functions that can be called
|
|
|
from the callback — no checks for the proper number of arguments
|
|
|
are made. The return value of the Lua function will be converted to the
|
|
|
-result type and an error will be thrown for invalid conversions.
|
|
|
+result type, and an error will be thrown for invalid conversions.
|
|
|
</p>
|
|
|
<p>
|
|
|
It's allowed to throw errors across a callback invocation, but it's not
|
|
@@ -981,7 +981,7 @@ convention cannot be automatically detected, unlike for
|
|
|
<tt>__stdcall</tt> calls <em>to</em> Windows functions.
|
|
|
</p>
|
|
|
<p>
|
|
|
-For some use cases it's necessary to free up the resources or to
|
|
|
+For some use cases, it's necessary to free up the resources or to
|
|
|
dynamically redirect callbacks. Use an explicit cast to a
|
|
|
C function pointer and keep the resulting cdata object. Then use
|
|
|
the <a href="ext_ffi_api.html#callback_free"><tt>cb:free()</tt></a>
|
|
@@ -1034,7 +1034,7 @@ GUI application, which waits for user input most of the time, anyway.
|
|
|
</p>
|
|
|
<p>
|
|
|
For new designs <b>avoid push-style APIs</b>: a C function repeatedly
|
|
|
-calling a callback for each result. Instead <b>use pull-style APIs</b>:
|
|
|
+calling a callback for each result. Instead, <b>use pull-style APIs</b>:
|
|
|
call a C function repeatedly to get a new result. Calls from Lua
|
|
|
to C via the FFI are much faster than the other way round. Most well-designed
|
|
|
libraries already use pull-style APIs (read/write, get/put).
|
|
@@ -1053,7 +1053,7 @@ function.
|
|
|
</p>
|
|
|
<p>
|
|
|
Indexing a C library namespace object with a symbol name (a Lua
|
|
|
-string) automatically binds it to the library. First the symbol type
|
|
|
+string) automatically binds it to the library. First, the symbol type
|
|
|
is resolved — it must have been declared with
|
|
|
<a href="ext_ffi_api.html#ffi_cdef"><tt>ffi.cdef</tt></a>. Then the
|
|
|
symbol address is resolved by searching for the symbol name in the
|
|
@@ -1108,7 +1108,7 @@ Performance notice: the JIT compiler specializes to the identity of
|
|
|
namespace objects and to the strings used to index it. This
|
|
|
effectively turns function cdata objects into constants. It's not
|
|
|
useful and actually counter-productive to explicitly cache these
|
|
|
-function objects, e.g. <tt>local strlen = ffi.C.strlen</tt>. OTOH it
|
|
|
+function objects, e.g. <tt>local strlen = ffi.C.strlen</tt>. OTOH, it
|
|
|
<em>is</em> useful to cache the namespace itself, e.g. <tt>local C =
|
|
|
ffi.C</tt>.
|
|
|
</p>
|
|
@@ -1133,14 +1133,14 @@ This behavior is inevitable, since the goal is to provide full
|
|
|
interoperability with C code. Adding extra safety measures, like
|
|
|
bounds checks, would be futile. There's no way to detect
|
|
|
misdeclarations of C functions, since shared libraries only
|
|
|
-provide symbol names, but no type information. Likewise there's no way
|
|
|
+provide symbol names, but no type information. Likewise, there's no way
|
|
|
to infer the valid range of indexes for a returned pointer.
|
|
|
</p>
|
|
|
<p>
|
|
|
Again: the FFI library is a low-level library. This implies it needs
|
|
|
to be used with care, but it's flexibility and performance often
|
|
|
outweigh this concern. If you're a C or C++ developer, it'll be easy
|
|
|
-to apply your existing knowledge. OTOH writing code for the FFI
|
|
|
+to apply your existing knowledge. OTOH, writing code for the FFI
|
|
|
library is not for the faint of heart and probably shouldn't be the
|
|
|
first exercise for someone with little experience in Lua, C or C++.
|
|
|
</p>
|
|
@@ -1168,7 +1168,7 @@ currently incomplete:
|
|
|
<li>C declarations are not passed through a C pre-processor,
|
|
|
yet.</li>
|
|
|
<li>The C parser is able to evaluate most constant expressions
|
|
|
-commonly found in C header files. However it doesn't handle the
|
|
|
+commonly found in C header files. However, it doesn't handle the
|
|
|
full range of C expression semantics and may fail for some
|
|
|
obscure constructs.</li>
|
|
|
<li><tt>static const</tt> declarations only work for integer types
|