FFI: Update docs on FFI semantics.

author: Mike Pall <mike> 2012-10-10 19:57:00 +0200
committer: Mike Pall <mike> 2012-10-10 19:57:00 +0200
commit: 425f67c7d6b33382d04ee1a9ade31b79150ec953 (patch)
tree: 67ff32dcc1a158a06d12ef3a6580eb73a8a7790e
parent: 0b55e05d06bc760070b8ca9f99c01c3d8e67e7db (diff)
download: luajit-425f67c7d6b33382d04ee1a9ade31b79150ec953.tar.gz
luajit-425f67c7d6b33382d04ee1a9ade31b79150ec953.tar.bz2
luajit-425f67c7d6b33382d04ee1a9ade31b79150ec953.zip
1 files changed, 51 insertions, 10 deletions
diff --git a/doc/ext_ffi_semantics.html b/doc/ext_ffi_semantics.html
index 36c3be32..2db9f882 100644
--- a/doc/ext_ffi_semantics.html
+++ b/doc/ext_ffi_semantics.html
@@ -83,12 +83,6 @@ expect them to work. It should be straightforward to write
 applications using the LuaJIT FFI for developers with a C or C++
 background.
 </p>
-<p class="indent" style="color: #c00000;">
-Please note: this doesn't comprise the final specification for the FFI
-semantics, yet. Some semantics may need to be changed, based on your
-feedback. Please <a href="contact.html">report</a> any problems you may
-encounter or any improvements you'd like to see &mdash; thank you!
-</p>
 <h2 id="clang">C Language Support</h2>
 <p>
@@ -813,6 +807,55 @@ possibly provide.</li>
 </ul>
+<h2 id="param">Parameterized Types</h2>
+<p>
+To facilitate some abstractions, the two functions
+<a href="ext_ffi_api.html#ffi_typeof"><tt>ffi.typeof</tt></a> and
+<a href="ext_ffi_api.html#ffi_cdef"><tt>ffi.cdef</tt></a> support
+parameterized types in C&nbsp;declarations. Note: none of the other API
+functions taking a cdecl allow this.
+</p>
+<p>
+Any place you can write a <b><tt>typedef</tt> name</b>, an
+<b>identifier</b> or a <b>number</b> in a declaration, you can write
+<tt>$</tt> (the dollar sign) instead. These placeholders are replaced in
+order of appearance with the arguments following the cdecl string:
+</p>
+<pre class="code">
+-- Declare a struct with a parameterized field type and name:
+ffi.cdef([[
+typedef struct { $ $; } foo_t;
+]], type1, name1)
+-- Anonymous struct with dynamic names:
+local bar_t = ffi.typeof("struct { int $, $; }", name1, name2)
+-- Derived pointer type:
+local bar_ptr_t = ffi.typeof("$ *", bar_t)
+-- Parameterized dimensions work even where a VLA won't work:
+local matrix_t = ffi.typeof("uint8_t[$][$]", width, height)
+</pre>
+<p>
+Caveat: this is <em>not</em> simple text substitution! A passed ctype or
+cdata object is treated like the underlying type, a passed string is
+considered an identifier and a number is considered a number. You must
+not mix this up: e.g. passing <tt>"int"</tt> as a string doesn't work in
+place of a type, you'd need to use <tt>ffi.typeof("int")</tt> instead.
+</p>
+<p>
+The main use for parameterized types are libraries implementing abstract
+data types
+(<a href="http://www.freelists.org/post/luajit/ffi-type-of-pointer-to,8"><span class="ext">&raquo;</span>&nbsp;example</a>),
+similar to what can be achieved with C++ template metaprogramming.
+Another use case are derived types of anonymous structs, which avoids
+pollution of the global struct namespace.
+</p>
+<p>
+Please note that parameterized types are a nice tool and indispensable
+for certain use cases. But you'll want to use them sparingly in regular
+code, e.g. when all types are actually fixed.
+</p>
 <h2 id="gc">Garbage Collection of cdata Objects</h2>
 <p>
 All explicitly (<tt>ffi.new()</tt>, <tt>ffi.cast()</tt> etc.) or
@@ -1156,10 +1199,8 @@ value.</li>
 <li>ctype <tt>__newindex</tt> tables and non-string lookups in ctype
 <tt>__index</tt> tables.</li>
 <li><tt>tostring()</tt> for cdata types.</li>
-<li>Calls to the following <a href="ext_ffi_api.html">ffi.* API</a>
+<li>Calls to <tt>ffi.cdef()</tt>, <tt>ffi.load()</tt> and
-functions: <tt>cdef</tt>, <tt>load</tt>, <tt>typeof</tt>,
+<tt>ffi.metatype()</tt>.</li>
-<tt>metatype</tt>, <tt>gc</tt>, <tt>sizeof</tt>, <tt>alignof</tt>,
-<tt>offsetof</tt>.</li>
 </ul>
 <p>
 Other missing features:
author	Mike Pall <mike>	2012-10-10 19:57:00 +0200
committer	Mike Pall <mike>	2012-10-10 19:57:00 +0200
commit	425f67c7d6b33382d04ee1a9ade31b79150ec953 (patch)
tree	67ff32dcc1a158a06d12ef3a6580eb73a8a7790e
parent	0b55e05d06bc760070b8ca9f99c01c3d8e67e7db (diff)
download	luajit-425f67c7d6b33382d04ee1a9ade31b79150ec953.tar.gz luajit-425f67c7d6b33382d04ee1a9ade31b79150ec953.tar.bz2 luajit-425f67c7d6b33382d04ee1a9ade31b79150ec953.zip

diff --git a/doc/ext_ffi_semantics.html b/doc/ext_ffi_semantics.html index 36c3be32..2db9f882 100644 --- a/doc/ext_ffi_semantics.html +++ b/doc/ext_ffi_semantics.html
@@ -83,12 +83,6 @@ expect them to work. It should be straightforward to write
83	applications using the LuaJIT FFI for developers with a C or C++	83	applications using the LuaJIT FFI for developers with a C or C++
84	background.	84	background.
85	</p>	85	</p>
86	<p class="indent" style="color: #c00000;">
87	Please note: this doesn't comprise the final specification for the FFI
88	semantics, yet. Some semantics may need to be changed, based on your
89	feedback. Please <a href="contact.html">report</a> any problems you may
90	encounter or any improvements you'd like to see — thank you!
91	</p>
92		86
93	<h2 id="clang">C Language Support</h2>	87	<h2 id="clang">C Language Support</h2>
94	<p>	88	<p>
@@ -813,6 +807,55 @@ possibly provide.</li>
813		807
814	</ul>	808	</ul>
815		809
		810	<h2 id="param">Parameterized Types</h2>
		811	<p>
		812	To facilitate some abstractions, the two functions
		813	<a href="ext_ffi_api.html#ffi_typeof"><tt>ffi.typeof</tt></a> and
		814	<a href="ext_ffi_api.html#ffi_cdef"><tt>ffi.cdef</tt></a> support
		815	parameterized types in C declarations. Note: none of the other API
		816	functions taking a cdecl allow this.
		817	</p>
		818	<p>
		819	Any place you can write a <b><tt>typedef</tt> name</b>, an
		820	<b>identifier</b> or a <b>number</b> in a declaration, you can write
		821	<tt>$</tt> (the dollar sign) instead. These placeholders are replaced in
		822	order of appearance with the arguments following the cdecl string:
		823	</p>
		824	<pre class="code">
		825	-- Declare a struct with a parameterized field type and name:
		826	ffi.cdef([[
		827	typedef struct { $ $; } foo_t;
		828	]], type1, name1)
		829
		830	-- Anonymous struct with dynamic names:
		831	local bar_t = ffi.typeof("struct { int $, $; }", name1, name2)
		832	-- Derived pointer type:
		833	local bar_ptr_t = ffi.typeof("$ *", bar_t)
		834
		835	-- Parameterized dimensions work even where a VLA won't work:
		836	local matrix_t = ffi.typeof("uint8_t[$][$]", width, height)
		837	</pre>
		838	<p>
		839	Caveat: this is <em>not</em> simple text substitution! A passed ctype or
		840	cdata object is treated like the underlying type, a passed string is
		841	considered an identifier and a number is considered a number. You must
		842	not mix this up: e.g. passing <tt>"int"</tt> as a string doesn't work in
		843	place of a type, you'd need to use <tt>ffi.typeof("int")</tt> instead.
		844	</p>
		845	<p>
		846	The main use for parameterized types are libraries implementing abstract
		847	data types
		848	(<a href="http://www.freelists.org/post/luajit/ffi-type-of-pointer-to,8"><span class="ext">»</span> example</a>),
		849	similar to what can be achieved with C++ template metaprogramming.
		850	Another use case are derived types of anonymous structs, which avoids
		851	pollution of the global struct namespace.
		852	</p>
		853	<p>
		854	Please note that parameterized types are a nice tool and indispensable
		855	for certain use cases. But you'll want to use them sparingly in regular
		856	code, e.g. when all types are actually fixed.
		857	</p>
		858
816	<h2 id="gc">Garbage Collection of cdata Objects</h2>	859	<h2 id="gc">Garbage Collection of cdata Objects</h2>
817	<p>	860	<p>
818	All explicitly (<tt>ffi.new()</tt>, <tt>ffi.cast()</tt> etc.) or	861	All explicitly (<tt>ffi.new()</tt>, <tt>ffi.cast()</tt> etc.) or
@@ -1156,10 +1199,8 @@ value.</li>
1156	<li>ctype <tt>__newindex</tt> tables and non-string lookups in ctype	1199	<li>ctype <tt>__newindex</tt> tables and non-string lookups in ctype
1157	<tt>__index</tt> tables.</li>	1200	<tt>__index</tt> tables.</li>
1158	<li><tt>tostring()</tt> for cdata types.</li>	1201	<li><tt>tostring()</tt> for cdata types.</li>
1159	<li>Calls to the following <a href="ext_ffi_api.html">ffi.* API</a>	1202	<li>Calls to <tt>ffi.cdef()</tt>, <tt>ffi.load()</tt> and
1160	functions: <tt>cdef</tt>, <tt>load</tt>, <tt>typeof</tt>,	1203	<tt>ffi.metatype()</tt>.</li>
1161	<tt>metatype</tt>, <tt>gc</tt>, <tt>sizeof</tt>, <tt>alignof</tt>,
1162	<tt>offsetof</tt>.</li>
1163	</ul>	1204	</ul>
1164	<p>	1205	<p>
1165	Other missing features:	1206	Other missing features: