aboutsummaryrefslogtreecommitdiff
path: root/doc/ext_ffi_semantics.html
diff options
context:
space:
mode:
authorMike Pall <mike>2011-01-20 22:14:17 +0100
committerMike Pall <mike>2011-01-20 22:14:17 +0100
commite985aeda84d8af63c4bfaa176c3312dfb2f7f230 (patch)
tree8a68df0aac6779db0972bb9dc07fbbe0c7629bc7 /doc/ext_ffi_semantics.html
parent8396c3cdbc26e08fdf9dea204efb641dd6ad1f91 (diff)
downloadluajit-e985aeda84d8af63c4bfaa176c3312dfb2f7f230.tar.gz
luajit-e985aeda84d8af63c4bfaa176c3312dfb2f7f230.tar.bz2
luajit-e985aeda84d8af63c4bfaa176c3312dfb2f7f230.zip
FFI: Add preliminary FFI documentation (still incomplete).
Diffstat (limited to 'doc/ext_ffi_semantics.html')
-rw-r--r--doc/ext_ffi_semantics.html155
1 files changed, 155 insertions, 0 deletions
diff --git a/doc/ext_ffi_semantics.html b/doc/ext_ffi_semantics.html
new file mode 100644
index 00000000..598d44c9
--- /dev/null
+++ b/doc/ext_ffi_semantics.html
@@ -0,0 +1,155 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
2<html>
3<head>
4<title>FFI Semantics</title>
5<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
6<meta name="Author" content="Mike Pall">
7<meta name="Copyright" content="Copyright (C) 2005-2011, Mike Pall">
8<meta name="Language" content="en">
9<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
10<link rel="stylesheet" type="text/css" href="bluequad-print.css" media="print">
11</head>
12<body>
13<div id="site">
14<a href="http://luajit.org"><span>Lua<span id="logo">JIT</span></span></a>
15</div>
16<div id="head">
17<h1>FFI Semantics</h1>
18</div>
19<div id="nav">
20<ul><li>
21<a href="luajit.html">LuaJIT</a>
22<ul><li>
23<a href="install.html">Installation</a>
24</li><li>
25<a href="running.html">Running</a>
26</li></ul>
27</li><li>
28<a href="extensions.html">Extensions</a>
29<ul><li>
30<a href="ext_ffi.html">FFI Library</a>
31<ul><li>
32<a href="ext_ffi_tutorial.html">FFI Tutorial</a>
33</li><li>
34<a href="ext_ffi_api.html">ffi.* API</a>
35</li><li>
36<a href="ext_ffi_int64.html">64 bit Integers</a>
37</li><li>
38<a class="current" href="ext_ffi_semantics.html">FFI Semantics</a>
39</li></ul>
40</li><li>
41<a href="ext_jit.html">jit.* Library</a>
42</li><li>
43<a href="ext_c_api.html">Lua/C API</a>
44</li></ul>
45</li><li>
46<a href="status.html">Status</a>
47<ul><li>
48<a href="changes.html">Changes</a>
49</li></ul>
50</li><li>
51<a href="faq.html">FAQ</a>
52</li><li>
53<a href="http://luajit.org/performance.html">Performance <span class="ext">&raquo;</span></a>
54</li><li>
55<a href="http://luajit.org/download.html">Download <span class="ext">&raquo;</span></a>
56</li></ul>
57</div>
58<div id="main">
59<p>
60TODO
61</p>
62
63<h2 id="clang">C Language Support</h2>
64<p>
65TODO
66</p>
67
68<h2 id="convert">C Type Conversion Rules</h2>
69<p>
70TODO
71</p>
72
73<h2 id="clib">C Library Namespaces</h2>
74<p>
75A C&nbsp;library namespace is a special kind of object which allows
76access to the symbols contained in libraries. Indexing it with a
77symbol name (a Lua string) automatically binds it to the library.
78</p>
79<p>
80TODO
81</p>
82
83<h2 id="ops">Operations on cdata Objects</h2>
84<p>
85TODO
86</p>
87
88<h2 id="gc">Garbage Collection of cdata Objects</h2>
89<p>
90All explicitly (<tt>ffi.new()</tt> etc.) or implicitly (accessors)
91created cdata objects are garbage collected. You need to ensure to
92retain valid references to cdata objects somewhere on a Lua stack, an
93upvalue or in a Lua table while they are still in use. Once the last
94reference to a cdata object is gone, the garbage collector will
95automatically free the memory used by it (at the end of the next GC
96cycle).
97</p>
98<p>
99Please note that pointers themselves are cdata objects, however they
100are <b>not</b> followed by the garbage collector. So e.g. if you
101assign a cdata array to a pointer, you must keep the cdata object
102holding the array alive as long as the pointer is still in use:
103</p>
104<pre class="code">
105ffi.cdef[[
106typedef struct { int *a; } foo_t;
107]]
108
109local s = ffi.new("foo_t", ffi.new("int[10]")) -- <span style="color:#c00000;">WRONG!</span>
110
111local a = ffi.new("int[10]") -- <span style="color:#00a000;">OK</span>
112local s = ffi.new("foo_t", a)
113-- Now do something with 's', but keep 'a' alive until you're done.
114</pre>
115<p>
116Similar rules apply for Lua strings which are implicitly converted to
117<tt>"const&nbsp;char&nbsp;*"</tt>: the string object itself must be
118referenced somewhere or it'll be garbage collected eventually. The
119pointer will then point to stale data, which may have already beeen
120overwritten. Note that string literals are automatically kept alive as
121long as the function containing it (actually its prototype) is not
122garbage collected.
123</p>
124<p>
125Objects which are passed as an argument to an external C&nbsp;function
126are kept alive until the call returns. So it's generally safe to
127create temporary cdata objects in argument lists. This is a common
128idiom for passing specific C&nbsp;types to vararg functions:
129</p>
130<pre class="code">
131ffi.cdef[[
132int printf(const char *fmt, ...);
133]]
134ffi.C.printf("integer value: %d\n", ffi.new("int", x)) -- <span style="color:#00a000;">OK</span>
135</pre>
136<p>
137Memory areas returned by C functions (e.g. from <tt>malloc()</tt>)
138must be manually managed of course. Pointers to cdata objects are
139indistinguishable from pointers returned by C functions (which is one
140of the reasons why the GC cannot follow them).
141</p>
142
143<h2>TODO</h2>
144<br class="flush">
145</div>
146<div id="foot">
147<hr class="hide">
148Copyright &copy; 2005-2011 Mike Pall
149<span class="noprint">
150&middot;
151<a href="contact.html">Contact</a>
152</span>
153</div>
154</body>
155</html>
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2026-01-12 17:44:15 +0000