aboutsummaryrefslogtreecommitdiffstatshomepage
path: root/libraries/luajit-2.0/doc
diff options
context:
space:
mode:
authorDavid Walter Seikel2012-01-23 23:36:30 +1000
committerDavid Walter Seikel2012-01-23 23:36:30 +1000
commit6523585c66c04cea54df50013df8886b589847d8 (patch)
tree0b22aee7064166d88595eda260ca2d17c0773da5 /libraries/luajit-2.0/doc
parentUpdate the EFL to what I'm actually using, coz I'm using some stuff not yet r... (diff)
downloadSledjHamr-6523585c66c04cea54df50013df8886b589847d8.zip
SledjHamr-6523585c66c04cea54df50013df8886b589847d8.tar.gz
SledjHamr-6523585c66c04cea54df50013df8886b589847d8.tar.bz2
SledjHamr-6523585c66c04cea54df50013df8886b589847d8.tar.xz
Add luaproc and LuaJIT libraries.
Two versions of LuaJIT, the stable release, and the dev version. Try the dev version first, until ih fails badly.
Diffstat (limited to 'libraries/luajit-2.0/doc')
-rw-r--r--libraries/luajit-2.0/doc/bluequad-print.css166
-rw-r--r--libraries/luajit-2.0/doc/bluequad.css306
-rw-r--r--libraries/luajit-2.0/doc/changes.html640
-rw-r--r--libraries/luajit-2.0/doc/contact.html98
-rw-r--r--libraries/luajit-2.0/doc/ext_c_api.html183
-rw-r--r--libraries/luajit-2.0/doc/ext_ffi.html332
-rw-r--r--libraries/luajit-2.0/doc/ext_ffi_api.html553
-rw-r--r--libraries/luajit-2.0/doc/ext_ffi_semantics.html1146
-rw-r--r--libraries/luajit-2.0/doc/ext_ffi_tutorial.html598
-rw-r--r--libraries/luajit-2.0/doc/ext_jit.html195
-rw-r--r--libraries/luajit-2.0/doc/extensions.html336
-rw-r--r--libraries/luajit-2.0/doc/faq.html180
-rw-r--r--libraries/luajit-2.0/doc/img/contact.pngbin0 -> 1340 bytes
-rw-r--r--libraries/luajit-2.0/doc/install.html543
-rw-r--r--libraries/luajit-2.0/doc/luajit.html142
-rw-r--r--libraries/luajit-2.0/doc/running.html313
-rw-r--r--libraries/luajit-2.0/doc/status.html240
17 files changed, 5971 insertions, 0 deletions
diff --git a/libraries/luajit-2.0/doc/bluequad-print.css b/libraries/luajit-2.0/doc/bluequad-print.css
new file mode 100644
index 0000000..69c07d6
--- /dev/null
+++ b/libraries/luajit-2.0/doc/bluequad-print.css
@@ -0,0 +1,166 @@
1/* Copyright (C) 2004-2011 Mike Pall.
2 *
3 * You are welcome to use the general ideas of this design for your own sites.
4 * But please do not steal the stylesheet, the layout or the color scheme.
5 */
6body {
7 font-family: serif;
8 font-size: 11pt;
9 margin: 0 3em;
10 padding: 0;
11 border: none;
12}
13a:link, a:visited, a:hover, a:active {
14 text-decoration: none;
15 background: transparent;
16 color: #0000ff;
17}
18h1, h2, h3 {
19 font-family: sans-serif;
20 font-weight: bold;
21 text-align: left;
22 margin: 0.5em 0;
23 padding: 0;
24}
25h1 {
26 font-size: 200%;
27}
28h2 {
29 font-size: 150%;
30}
31h3 {
32 font-size: 125%;
33}
34p {
35 margin: 0 0 0.5em 0;
36 padding: 0;
37}
38ul, ol {
39 margin: 0.5em 0;
40 padding: 0 0 0 2em;
41}
42ul {
43 list-style: outside square;
44}
45ol {
46 list-style: outside decimal;
47}
48li {
49 margin: 0;
50 padding: 0;
51}
52dl {
53 margin: 1em 0;
54 padding: 1em;
55 border: 1px solid black;
56}
57dt {
58 font-weight: bold;
59 margin: 0;
60 padding: 0;
61}
62dt sup {
63 float: right;
64 margin-left: 1em;
65}
66dd {
67 margin: 0.5em 0 0 2em;
68 padding: 0;
69}
70table {
71 table-layout: fixed;
72 width: 100%;
73 margin: 1em 0;
74 padding: 0;
75 border: 1px solid black;
76 border-spacing: 0;
77 border-collapse: collapse;
78}
79tr {
80 margin: 0;
81 padding: 0;
82 border: none;
83}
84td {
85 text-align: left;
86 margin: 0;
87 padding: 0.2em 0.5em;
88 border-top: 1px solid black;
89 border-bottom: 1px solid black;
90}
91tr.separate td {
92 border-top: double;
93}
94tt, pre, code, kbd, samp {
95 font-family: monospace;
96 font-size: 75%;
97}
98kbd {
99 font-weight: bolder;
100}
101blockquote, pre {
102 margin: 1em 2em;
103 padding: 0;
104}
105img {
106 border: none;
107 vertical-align: baseline;
108 margin: 0;
109 padding: 0;
110}
111img.left {
112 float: left;
113 margin: 0.5em 1em 0.5em 0;
114}
115img.right {
116 float: right;
117 margin: 0.5em 0 0.5em 1em;
118}
119.flush {
120 clear: both;
121 visibility: hidden;
122}
123.hide, .noprint, #nav {
124 display: none !important;
125}
126.pagebreak {
127 page-break-before: always;
128}
129#site {
130 text-align: right;
131 font-family: sans-serif;
132 font-weight: bold;
133 margin: 0 1em;
134 border-bottom: 1pt solid black;
135}
136#site a {
137 font-size: 1.2em;
138}
139#site a:link, #site a:visited {
140 text-decoration: none;
141 font-weight: bold;
142 background: transparent;
143 color: #ffffff;
144}
145#logo {
146 color: #ff8000;
147}
148#head {
149 clear: both;
150 margin: 0 1em;
151}
152#main {
153 line-height: 1.3;
154 text-align: justify;
155 margin: 1em;
156}
157#foot {
158 clear: both;
159 font-size: 80%;
160 text-align: center;
161 margin: 0 1.25em;
162 padding: 0.5em 0 0 0;
163 border-top: 1pt solid black;
164 page-break-before: avoid;
165 page-break-after: avoid;
166}
diff --git a/libraries/luajit-2.0/doc/bluequad.css b/libraries/luajit-2.0/doc/bluequad.css
new file mode 100644
index 0000000..49849fb
--- /dev/null
+++ b/libraries/luajit-2.0/doc/bluequad.css
@@ -0,0 +1,306 @@
1/* Copyright (C) 2004-2011 Mike Pall.
2 *
3 * You are welcome to use the general ideas of this design for your own sites.
4 * But please do not steal the stylesheet, the layout or the color scheme.
5 */
6/* colorscheme:
7 *
8 * site | head #4162bf/white | #6078bf/#e6ecff
9 * ------+------ ----------------+-------------------
10 * nav | main #bfcfff | #e6ecff/black
11 *
12 * nav: hiback loback #c5d5ff #b9c9f9
13 * hiborder loborder #e6ecff #97a7d7
14 * link hover #2142bf #ff0000
15 *
16 * link: link visited hover #2142bf #8122bf #ff0000
17 *
18 * main: boxback boxborder #f0f4ff #bfcfff
19 */
20body {
21 font-family: Verdana, Arial, Helvetica, sans-serif;
22 font-size: 10pt;
23 margin: 0;
24 padding: 0;
25 border: none;
26 background: #e0e0e0;
27 color: #000000;
28}
29a:link {
30 text-decoration: none;
31 background: transparent;
32 color: #2142bf;
33}
34a:visited {
35 text-decoration: none;
36 background: transparent;
37 color: #8122bf;
38}
39a:hover, a:active {
40 text-decoration: underline;
41 background: transparent;
42 color: #ff0000;
43}
44h1, h2, h3 {
45 font-weight: bold;
46 text-align: left;
47 margin: 0.5em 0;
48 padding: 0;
49 background: transparent;
50}
51h1 {
52 font-size: 200%;
53 line-height: 3em; /* really 6em relative to body, match #site span */
54 margin: 0;
55}
56h2 {
57 font-size: 150%;
58 color: #606060;
59}
60h3 {
61 font-size: 125%;
62 color: #404040;
63}
64p {
65 max-width: 600px;
66 margin: 0 0 0.5em 0;
67 padding: 0;
68}
69b {
70 color: #404040;
71}
72ul, ol {
73 max-width: 600px;
74 margin: 0.5em 0;
75 padding: 0 0 0 2em;
76}
77ul {
78 list-style: outside square;
79}
80ol {
81 list-style: outside decimal;
82}
83li {
84 margin: 0;
85 padding: 0;
86}
87dl {
88 max-width: 600px;
89 margin: 1em 0;
90 padding: 1em;
91 border: 1px solid #bfcfff;
92 background: #f0f4ff;
93}
94dt {
95 font-weight: bold;
96 margin: 0;
97 padding: 0;
98}
99dt sup {
100 float: right;
101 margin-left: 1em;
102 color: #808080;
103}
104dt a:visited {
105 text-decoration: none;
106 color: #2142bf;
107}
108dt a:hover, dt a:active {
109 text-decoration: none;
110 color: #ff0000;
111}
112dd {
113 margin: 0.5em 0 0 2em;
114 padding: 0;
115}
116div.tablewrap { /* for IE *sigh* */
117 max-width: 600px;
118}
119table {
120 table-layout: fixed;
121 border-spacing: 0;
122 border-collapse: collapse;
123 max-width: 600px;
124 width: 100%;
125 margin: 1em 0;
126 padding: 0;
127 border: 1px solid #bfcfff;
128}
129tr {
130 margin: 0;
131 padding: 0;
132 border: none;
133}
134tr.odd {
135 background: #f0f4ff;
136}
137tr.separate td {
138 border-top: 1px solid #bfcfff;
139}
140td {
141 text-align: left;
142 margin: 0;
143 padding: 0.2em 0.5em;
144 border: none;
145}
146tt, code, kbd, samp {
147 font-family: Courier New, Courier, monospace;
148 line-height: 1.2;
149 font-size: 110%;
150}
151kbd {
152 font-weight: bolder;
153}
154blockquote, pre {
155 max-width: 600px;
156 margin: 1em 2em;
157 padding: 0;
158}
159pre {
160 line-height: 1.1;
161}
162pre.code {
163 line-height: 1.4;
164 margin: 0.5em 0 1em 0.5em;
165 padding: 0.5em 1em;
166 border: 1px solid #bfcfff;
167 background: #f0f4ff;
168}
169img {
170 border: none;
171 vertical-align: baseline;
172 margin: 0;
173 padding: 0;
174}
175img.left {
176 float: left;
177 margin: 0.5em 1em 0.5em 0;
178}
179img.right {
180 float: right;
181 margin: 0.5em 0 0.5em 1em;
182}
183.indent {
184 padding-left: 1em;
185}
186.flush {
187 clear: both;
188 visibility: hidden;
189}
190.hide, .noscreen {
191 display: none !important;
192}
193.ext {
194 color: #ff8000;
195}
196#site {
197 clear: both;
198 float: left;
199 width: 13em;
200 text-align: center;
201 font-weight: bold;
202 margin: 0;
203 padding: 0;
204 background: transparent;
205 color: #ffffff;
206}
207#site a {
208 font-size: 200%;
209}
210#site a:link, #site a:visited {
211 text-decoration: none;
212 font-weight: bold;
213 background: transparent;
214 color: #ffffff;
215}
216#site span {
217 line-height: 3em; /* really 6em relative to body, match h1 */
218}
219#logo {
220 color: #ffb380;
221}
222#head {
223 margin: 0;
224 padding: 0 0 0 2em;
225 border-left: solid 13em #4162bf;
226 border-right: solid 3em #6078bf;
227 background: #6078bf;
228 color: #e6ecff;
229}
230#nav {
231 clear: both;
232 float: left;
233 overflow: hidden;
234 text-align: left;
235 line-height: 1.5;
236 width: 13em;
237 padding-top: 1em;
238 background: transparent;
239}
240#nav ul {
241 list-style: none outside;
242 margin: 0;
243 padding: 0;
244}
245#nav li {
246 margin: 0;
247 padding: 0;
248}
249#nav a {
250 display: block;
251 text-decoration: none;
252 font-weight: bold;
253 margin: 0;
254 padding: 2px 1em;
255 border-top: 1px solid transparent;
256 border-bottom: 1px solid transparent;
257 background: transparent;
258 color: #2142bf;
259}
260#nav a:hover, #nav a:active {
261 text-decoration: none;
262 border-top: 1px solid #97a7d7;
263 border-bottom: 1px solid #e6ecff;
264 background: #b9c9f9;
265 color: #ff0000;
266}
267#nav a.current, #nav a.current:hover, #nav a.current:active {
268 border-top: 1px solid #e6ecff;
269 border-bottom: 1px solid #97a7d7;
270 background: #c5d5ff;
271 color: #2142bf;
272}
273#nav ul ul a {
274 padding: 0 1em 0 1.7em;
275}
276#nav ul ul ul a {
277 padding: 0 0.5em 0 2.4em;
278}
279#main {
280 line-height: 1.5;
281 text-align: left;
282 margin: 0;
283 padding: 1em 2em;
284 border-left: solid 13em #bfcfff;
285 border-right: solid 3em #e6ecff;
286 background: #e6ecff;
287}
288#foot {
289 clear: both;
290 font-size: 80%;
291 text-align: center;
292 margin: 0;
293 padding: 0.5em;
294 background: #6078bf;
295 color: #ffffff;
296}
297#foot a:link, #foot a:visited {
298 text-decoration: underline;
299 background: transparent;
300 color: #ffffff;
301}
302#foot a:hover, #foot a:active {
303 text-decoration: underline;
304 background: transparent;
305 color: #bfcfff;
306}
diff --git a/libraries/luajit-2.0/doc/changes.html b/libraries/luajit-2.0/doc/changes.html
new file mode 100644
index 0000000..51027a9
--- /dev/null
+++ b/libraries/luajit-2.0/doc/changes.html
@@ -0,0 +1,640 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
2<html>
3<head>
4<title>LuaJIT Change History</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<style type="text/css">
12div.major { max-width: 600px; padding: 1em; margin: 1em 0 1em 0; }
13</style>
14</head>
15<body>
16<div id="site">
17<a href="http://luajit.org"><span>Lua<span id="logo">JIT</span></span></a>
18</div>
19<div id="head">
20<h1>LuaJIT Change History</h1>
21</div>
22<div id="nav">
23<ul><li>
24<a href="luajit.html">LuaJIT</a>
25<ul><li>
26<a href="install.html">Installation</a>
27</li><li>
28<a href="running.html">Running</a>
29</li></ul>
30</li><li>
31<a href="extensions.html">Extensions</a>
32<ul><li>
33<a href="ext_ffi.html">FFI Library</a>
34<ul><li>
35<a href="ext_ffi_tutorial.html">FFI Tutorial</a>
36</li><li>
37<a href="ext_ffi_api.html">ffi.* API</a>
38</li><li>
39<a href="ext_ffi_semantics.html">FFI Semantics</a>
40</li></ul>
41</li><li>
42<a href="ext_jit.html">jit.* Library</a>
43</li><li>
44<a href="ext_c_api.html">Lua/C API</a>
45</li></ul>
46</li><li>
47<a href="status.html">Status</a>
48<ul><li>
49<a class="current" href="changes.html">Changes</a>
50</li></ul>
51</li><li>
52<a href="faq.html">FAQ</a>
53</li><li>
54<a href="http://luajit.org/performance.html">Performance <span class="ext">&raquo;</span></a>
55</li><li>
56<a href="http://luajit.org/download.html">Download <span class="ext">&raquo;</span></a>
57</li></ul>
58</div>
59<div id="main">
60<p>
61This is a list of changes between the released versions of LuaJIT.<br>
62The current <span style="color: #c00000;">development version</span> is <strong>LuaJIT&nbsp;2.0.0-beta9</strong>.<br>
63The current <span style="color: #0000c0;">stable version</span> is <strong>LuaJIT&nbsp;1.1.7</strong>.
64</p>
65<p>
66Please check the
67<a href="http://luajit.org/changes.html"><span class="ext">&raquo;</span>&nbsp;Online Change History</a>
68to see whether newer versions are available.
69</p>
70
71<div class="major" style="background: #ffd0d0;">
72<h2 id="LuaJIT-2.0.0-beta9">LuaJIT 2.0.0-beta9 &mdash; 2011-12-14</h2>
73<ul>
74<li>New features:
75<ul>
76<li>PPC port of LuaJIT is complete. Default is the dual-number port
77(usually faster). Single-number port selectable via <tt>src/Makefile</tt>
78at build time.</li>
79<li>Add FFI callback support.</li>
80<li>Extend <tt>-b</tt> to generate <tt>.c</tt>, <tt>.h</tt> or <tt>.obj/.o</tt>
81files with embedded bytecode.</li>
82<li>Allow loading embedded bytecode with <tt>require()</tt>.</li>
83<li>From Lua 5.2: Change to <tt>'\z'</tt> escape. Reject undefined escape
84sequences.</li>
85</ul></li>
86<li>Correctness and completeness:
87<ul>
88<li>Fix OSX 10.7 build. Fix <tt>install_name</tt> and versioning on OSX.</li>
89<li>Fix iOS build.</li>
90<li>Install <tt>dis_arm.lua</tt>, too.</li>
91<li>Mark installed shared library as executable.</li>
92<li>Add debug option to <tt>msvcbuild.bat</tt> and improve error handling.</li>
93<li>Fix data-flow analysis for iterators.</li>
94<li>Fix forced unwinding triggered by external unwinder.</li>
95<li>Record missing <tt>for</tt> loop slot loads (return to lower frame).</li>
96<li>Always use ANSI variants of Windows system functions.</li>
97<li>Fix GC barrier for multi-result table constructor (<tt>TSETM</tt>).</li>
98<li>Fix/add various FOLD rules.</li>
99<li>Add potential PHI for number conversions due to type instability.</li>
100<li>Do not eliminate PHIs only referenced from other PHIs.</li>
101<li>Correctly anchor implicit number to string conversions in Lua/C API.</li>
102<li>Fix various stack limit checks.</li>
103<li>x64: Use thread-safe exceptions for external unwinding (GCC platforms).</li>
104<li>x64: Fix result type of cdata index conversions.</li>
105<li>x64: Fix <tt>math.random()</tt> and <tt>bit.bswap()</tt> code generation.</li>
106<li>x64: Fix <tt>lightuserdata</tt> comparisons.</li>
107<li>x64: Always extend stack-passed arguments to pointer size.</li>
108<li>ARM: Many fixes to code generation backend.</li>
109<li>PPC/e500: Fix dispatch for binop metamethods.</li>
110<li>PPC/e500: Save/restore condition registers when entering/leaving the VM.</li>
111<li>PPC/e500: Fix write barrier in stores of strings to upvalues.</li>
112</ul></li>
113<li>FFI library:
114<ul>
115<li>Fix C comment parsing.</li>
116<li>Fix snapshot optimization for cdata comparisons.</li>
117<li>Fix recording of const/enum lookups in namespaces.</li>
118<li>Fix call argument and return handling for <tt>I8/U8/I16/U16</tt> types.</li>
119<li>Fix unfused loads of float fields.</li>
120<li>Fix <tt>ffi.string()</tt> recording.</li>
121<li>Save <tt>GetLastError()</tt> around <tt>ffi.load()</tt> and symbol
122resolving, too.</li>
123<li>Improve ld script detection in <tt>ffi.load()</tt>.</li>
124<li>Record loads/stores to external variables in namespaces.</li>
125<li>Compile calls to stdcall, fastcall and vararg functions.</li>
126<li>Treat function ctypes like pointers in comparisons.</li>
127<li>Resolve <tt>__call</tt> metamethod for pointers, too.</li>
128<li>Record C function calls with bool return values.</li>
129<li>Record <tt>ffi.errno()</tt>.</li>
130<li>x86: Fix number to <tt>uint32_t</tt> conversion rounding.</li>
131<li>x86: Fix 64 bit arithmetic in assembler backend.</li>
132<li>x64: Fix struct-by-value calling conventions.</li>
133<li>ARM: Ensure invocation of SPLIT pass for float conversions.</li>
134</ul></li>
135<li>Structural and performance enhancements:
136<ul>
137<li>Display trace types with <tt>-jv</tt> and <tt>-jdump</tt>.</li>
138<li>Record isolated calls. But prefer recording loops over calls.</li>
139<li>Specialize to prototype for non-monomorphic functions. Solves the
140trace-explosion problem for closure-heavy programming styles.</li>
141<li>Always generate a portable <tt>vmdef.lua</tt>. Easier for distros.</li>
142</ul></li>
143</ul>
144
145<h2 id="LuaJIT-2.0.0-beta8">LuaJIT 2.0.0-beta8 &mdash; 2011-06-23</h2>
146<ul>
147<li>New features:
148<ul>
149<li>Soft-float ARM port of LuaJIT is complete.</li>
150<li>Add support for bytecode loading/saving and <tt>-b</tt> command line
151option.</li>
152<li>From Lua 5.2: <tt>__len</tt> metamethod for tables
153(disabled by default).</li>
154</ul></li>
155<li>Correctness and completeness:
156<ul>
157<li>ARM: Misc. fixes for interpreter.</li>
158<li>x86/x64: Fix <tt>bit.*</tt> argument checking in interpreter.</li>
159<li>Catch early out-of-memory in memory allocator initialization.</li>
160<li>Fix data-flow analysis for paths leading to an upvalue close.</li>
161<li>Fix check for missing arguments in <tt>string.format()</tt>.</li>
162<li>Fix Solaris/x86 build (note: not a supported target).</li>
163<li>Fix recording of loops with instable directions in side traces.</li>
164<li>x86/x64: Fix fusion of comparisons with <tt>u8</tt>/<tt>u16</tt>
165<tt>XLOAD</tt>.</li>
166<li>x86/x64: Fix register allocation for variable shifts.</li>
167</ul></li>
168<li>FFI library:
169<ul>
170<li>Add <tt>ffi.errno()</tt>. Save <tt>errno</tt>/<tt>GetLastError()</tt>
171around allocations etc.</li>
172<li>Fix <tt>__gc</tt> for VLA/VLS cdata objects.</li>
173<li>Fix recording of casts from 32 bit cdata pointers to integers.</li>
174<li><tt>tonumber(cdata)</tt> returns <tt>nil</tt> for non-numbers.</li>
175<li>Show address pointed to for <tt>tostring(pointer)</tt>.</li>
176<li>Print <tt>NULL</tt> pointers as <tt>"cdata&lt;... *&gt;: NULL"</tt>.</li>
177<li>Support <tt>__tostring</tt> metamethod for pointers to structs, too.</li>
178</ul></li>
179<li>Structural and performance enhancements:
180<ul>
181<li>More tuning for loop unrolling heuristics.</li>
182<li>Flatten and compress in-memory debug info (saves ~70%).</li>
183</ul></li>
184</ul>
185
186<h2 id="LuaJIT-2.0.0-beta7">LuaJIT 2.0.0-beta7 &mdash; 2011-05-05</h2>
187<ul>
188<li>New features:
189<ul>
190<li>ARM port of the LuaJIT interpreter is complete.</li>
191<li>FFI library: Add <tt>ffi.gc()</tt>, <tt>ffi.metatype()</tt>,
192<tt>ffi.istype()</tt>.</li>
193<li>FFI library: Resolve ld script redirection in <tt>ffi.load()</tt>.</li>
194<li>From Lua 5.2: <tt>package.searchpath()</tt>, <tt>fp:read("*L")</tt>,
195<tt>load(string)</tt>.</li>
196<li>From Lua 5.2, disabled by default: empty statement,
197<tt>table.unpack()</tt>, modified <tt>coroutine.running()</tt>.</li>
198</ul></li>
199<li>Correctness and completeness:
200<ul>
201<li>FFI library: numerous fixes.</li>
202<li>Fix type mismatches in store-to-load forwarding.</li>
203<li>Fix error handling within metamethods.</li>
204<li>Fix <tt>table.maxn()</tt>.</li>
205<li>Improve accuracy of <tt>x^-k</tt> on x64.</li>
206<li>Fix code generation for Intel Atom in x64 mode.</li>
207<li>Fix narrowing of POW.</li>
208<li>Fix recording of retried fast functions.</li>
209<li>Fix code generation for <tt>bit.bnot()</tt> and multiplies.</li>
210<li>Fix error location within cpcall frames.</li>
211<li>Add workaround for old libgcc unwind bug.</li>
212<li>Fix <tt>lua_yield()</tt> and <tt>getmetatable(lightuserdata)</tt> on x64.</li>
213<li>Misc. fixes for PPC/e500 interpreter.</li>
214<li>Fix stack slot updates for down-recursion.</li>
215</ul></li>
216<li>Structural and performance enhancements:
217<ul>
218<li>Add dual-number mode (int/double) for the VM. Enabled for ARM.</li>
219<li>Improve narrowing of arithmetic operators and <tt>for</tt> loops.</li>
220<li>Tune loop unrolling heuristics and increase trace recorder limits.</li>
221<li>Eliminate dead slots in snapshots using bytecode data-flow analysis.</li>
222<li>Avoid phantom stores to proxy tables.</li>
223<li>Optimize lookups in empty proxy tables.</li>
224<li>Improve bytecode optimization of <tt>and</tt>/<tt>or</tt> operators.</li>
225</ul></li>
226</ul>
227
228<h2 id="LuaJIT-2.0.0-beta6">LuaJIT 2.0.0-beta6 &mdash; 2011-02-11</h2>
229<ul>
230<li>New features:
231<ul>
232<li>PowerPC/e500v2 port of the LuaJIT interpreter is complete.</li>
233<li>Various minor features from Lua 5.2: Hex escapes in literals,
234<tt>'\*'</tt> escape, reversible <tt>string.format("%q",s)</tt>,
235<tt>"%g"</tt> pattern, <tt>table.sort</tt> checks callbacks,
236<tt>os.exit(status|true|false[,close])</tt>.</li>
237<li>Lua 5.2 <tt>__pairs</tt> and <tt>__ipairs</tt> metamethods
238(disabled by default).</li>
239<li>Initial release of the FFI library.</li>
240</ul></li>
241<li>Correctness and completeness:
242<ul>
243<li>Fix <tt>string.format()</tt> for non-finite numbers.</li>
244<li>Fix memory leak when compiled to use the built-in allocator.</li>
245<li>x86/x64: Fix unnecessary resize in <tt>TSETM</tt> bytecode.</li>
246<li>Fix various GC issues with traces and <tt>jit.flush()</tt>.</li>
247<li>x64: Fix fusion of indexes for array references.</li>
248<li>x86/x64: Fix stack overflow handling for coroutine results.</li>
249<li>Enable low-2GB memory allocation on FreeBSD/x64.</li>
250<li>Fix <tt>collectgarbage("count")</tt> result if more than 2GB is in use.</li>
251<li>Fix parsing of hex floats.</li>
252<li>x86/x64: Fix loop branch inversion with trailing
253<tt>HREF+NE/EQ</tt>.</li>
254<li>Add <tt>jit.os</tt> string.</li>
255<li><tt>coroutine.create()</tt> permits running C functions, too.</li>
256<li>Fix OSX build to work with newer ld64 versions.</li>
257<li>Fix bytecode optimization of <tt>and</tt>/<tt>or</tt> operators.</li>
258</ul></li>
259<li>Structural and performance enhancements:
260<ul>
261<li>Emit specialized bytecode for <tt>pairs()</tt>/<tt>next()</tt>.</li>
262<li>Improve bytecode coalescing of <tt>nil</tt> constants.</li>
263<li>Compile calls to vararg functions.</li>
264<li>Compile <tt>select()</tt>.</li>
265<li>Improve alias analysis, esp. for loads from allocations.</li>
266<li>Tuning of various compiler heuristics.</li>
267<li>Refactor and extend IR conversion instructions.</li>
268<li>x86/x64: Various backend enhancements related to the FFI.</li>
269<li>Add SPLIT pass to split 64 bit IR instructions for 32 bit CPUs.</li>
270</ul></li>
271</ul>
272
273<h2 id="LuaJIT-2.0.0-beta5">LuaJIT 2.0.0-beta5 &mdash; 2010-08-24</h2>
274<ul>
275<li>Correctness and completeness:
276<ul>
277<li>Fix trace exit dispatch to function headers.</li>
278<li>Fix Windows and OSX builds with LUAJIT_DISABLE_JIT.</li>
279<li>Reorganize and fix placement of generated machine code on x64.</li>
280<li>Fix TNEW in x64 interpreter.</li>
281<li>Do not eliminate PHIs for values only referenced from side exits.</li>
282<li>OS-independent canonicalization of strings for non-finite numbers.</li>
283<li>Fix <tt>string.char()</tt> range check on x64.</li>
284<li>Fix <tt>tostring()</tt> resolving within <tt>print()</tt>.</li>
285<li>Fix error handling for <tt>next()</tt>.</li>
286<li>Fix passing of constant arguments to external calls on x64.</li>
287<li>Fix interpreter argument check for two-argument SSE math functions.</li>
288<li>Fix C frame chain corruption caused by <tt>lua_cpcall()</tt>.</li>
289<li>Fix return from <tt>pcall()</tt> within active hook.</li>
290</ul></li>
291<li>Structural and performance enhancements:
292<ul>
293<li>Replace on-trace GC frame syncing with interpreter exit.</li>
294<li>Improve hash lookup specialization by not removing dead keys during GC.</li>
295<li>Turn traces into true GC objects.</li>
296<li>Avoid starting a GC cycle immediately after library init.</li>
297<li>Add weak guards to improve dead-code elimination.</li>
298<li>Speed up string interning.</li>
299</ul></li>
300</ul>
301
302<h2 id="LuaJIT-2.0.0-beta4">LuaJIT 2.0.0-beta4 &mdash; 2010-03-28</h2>
303<ul>
304<li>Correctness and completeness:
305<ul>
306<li>Fix precondition for on-trace creation of table keys.</li>
307<li>Fix <tt>{f()}</tt> on x64 when table is resized.</li>
308<li>Fix folding of ordered comparisons with same references.</li>
309<li>Fix snapshot restores for multi-result bytecodes.</li>
310<li>Fix potential hang when recording bytecode with nested closures.</li>
311<li>Fix recording of <tt>getmetatable()</tt>, <tt>tonumber()</tt> and bad argument types.</li>
312<li>Fix SLOAD fusion across returns to lower frames.</li>
313</ul></li>
314<li>Structural and performance enhancements:
315<ul>
316<li>Add array bounds check elimination. <tt>-Oabc</tt> is enabled by default.</li>
317<li>More tuning for x64, e.g. smaller table objects.</li>
318</ul></li>
319</ul>
320
321<h2 id="LuaJIT-2.0.0-beta3">LuaJIT 2.0.0-beta3 &mdash; 2010-03-07</h2>
322<ul>
323<li>LuaJIT x64 port:
324<ul>
325<li>Port integrated memory allocator to Linux/x64, Windows/x64 and OSX/x64.</li>
326<li>Port interpreter and JIT compiler to x64.</li>
327<li>Port DynASM to x64.</li>
328<li>Many 32/64 bit cleanups in the VM.</li>
329<li>Allow building the interpreter with either x87 or SSE2 arithmetics.</li>
330<li>Add external unwinding and C++ exception interop (default on x64).</li>
331</ul></li>
332<li>Correctness and completeness:
333<ul>
334<li>Fix constructor bytecode generation for certain conditional values.</li>
335<li>Fix some cases of ordered string comparisons.</li>
336<li>Fix <tt>lua_tocfunction()</tt>.</li>
337<li>Fix cutoff register in JMP bytecode for some conditional expressions.</li>
338<li>Fix PHI marking algorithm for references from variant slots.</li>
339<li>Fix <tt>package.cpath</tt> for non-default PREFIX.</li>
340<li>Fix DWARF2 frame unwind information for interpreter on OSX.</li>
341<li>Drive the GC forward on string allocations in the parser.</li>
342<li>Implement call/return hooks (zero-cost if disabled).</li>
343<li>Implement yield from C hooks.</li>
344<li>Disable JIT compiler on older non-SSE2 CPUs instead of aborting.</li>
345</ul></li>
346<li>Structural and performance enhancements:
347<ul>
348<li>Compile recursive code (tail-, up- and down-recursion).</li>
349<li>Improve heuristics for bytecode penalties and blacklisting.</li>
350<li>Split CALL/FUNC recording and clean up fast function call semantics.</li>
351<li>Major redesign of internal function call handling.</li>
352<li>Improve FOR loop const specialization and integerness checks.</li>
353<li>Switch to pre-initialized stacks. Avoid frame-clearing.</li>
354<li>Colocation of prototypes and related data: bytecode, constants, debug info.</li>
355<li>Cleanup parser and streamline bytecode generation.</li>
356<li>Add support for weak IR references to register allocator.</li>
357<li>Switch to compressed, extensible snapshots.</li>
358<li>Compile returns to frames below the start frame.</li>
359<li>Improve alias analysis of upvalues using a disambiguation hash value.</li>
360<li>Compile floor/ceil/trunc to SSE2 helper calls or SSE4.1 instructions.</li>
361<li>Add generic C call handling to IR and backend.</li>
362<li>Improve KNUM fuse vs. load heuristics.</li>
363<li>Compile various <tt>io.*()</tt> functions.</li>
364<li>Compile <tt>math.sinh()</tt>, <tt>math.cosh()</tt>, <tt>math.tanh()</tt>
365and <tt>math.random()</tt>.</li>
366</ul></li>
367</ul>
368
369<h2 id="LuaJIT-2.0.0-beta2">LuaJIT 2.0.0-beta2 &mdash; 2009-11-09</h2>
370<ul>
371<li>Reorganize build system. Build static+shared library on POSIX.</li>
372<li>Allow C++ exception conversion on all platforms
373using a wrapper function.</li>
374<li>Automatically catch C++ exceptions and rethrow Lua error
375(DWARF2 only).</li>
376<li>Check for the correct x87 FPU precision at strategic points.</li>
377<li>Always use wrappers for libm functions.</li>
378<li>Resurrect metamethod name strings before copying them.</li>
379<li>Mark current trace, even if compiler is idle.</li>
380<li>Ensure FILE metatable is created only once.</li>
381<li>Fix type comparisons when different integer types are involved.</li>
382<li>Fix <tt>getmetatable()</tt> recording.</li>
383<li>Fix TDUP with dead keys in template table.</li>
384<li><tt>jit.flush(tr)</tt> returns status.
385Prevent manual flush of a trace that's still linked.</li>
386<li>Improve register allocation heuristics for invariant references.</li>
387<li>Compile the push/pop variants of <tt>table.insert()</tt> and
388<tt>table.remove()</tt>.</li>
389<li>Compatibility with MSVC <tt>link&nbsp/debug</tt>.</li>
390<li>Fix <tt>lua_iscfunction()</tt>.</li>
391<li>Fix <tt>math.random()</tt> when compiled with <tt>-fpic</tt> (OSX).</li>
392<li>Fix <tt>table.maxn()</tt>.</li>
393<li>Bump <tt>MACOSX_DEPLOYMENT_TARGET</tt> to <tt>10.4</tt></li>
394<li><tt>luaL_check*()</tt> and <tt>luaL_opt*()</tt> now support
395negative arguments, too.<br>
396This matches the behavior of Lua 5.1, but not the specification.</li>
397</ul>
398
399<h2 id="LuaJIT-2.0.0-beta1">LuaJIT 2.0.0-beta1 &mdash; 2009-10-31</h2>
400<ul>
401<li>This is the first public release of LuaJIT 2.0.</li>
402<li>The whole VM has been rewritten from the ground up, so there's
403no point in listing differences over earlier versions.</li>
404</ul>
405</div>
406
407<div class="major" style="background: #d0d0ff;">
408<h2 id="LuaJIT-1.1.7">LuaJIT 1.1.7 &mdash; 2011-05-05</h2>
409<ul>
410<li>Added fixes for the
411<a href="http://www.lua.org/bugs.html#5.1.4"><span class="ext">&raquo;</span>&nbsp;currently known bugs in Lua 5.1.4</a>.</li>
412</ul>
413
414<h2 id="LuaJIT-1.1.6">LuaJIT 1.1.6 &mdash; 2010-03-28</h2>
415<ul>
416<li>Added fixes for the
417<a href="http://www.lua.org/bugs.html#5.1.4"><span class="ext">&raquo;</span>&nbsp;currently known bugs in Lua 5.1.4</a>.</li>
418<li>Removed wrong GC check in <tt>jit_createstate()</tt>.
419Thanks to Tim Mensch.</li>
420<li>Fixed bad assertions while compiling <tt>table.insert()</tt> and
421<tt>table.remove()</tt>.</li>
422</ul>
423
424<h2 id="LuaJIT-1.1.5">LuaJIT 1.1.5 &mdash; 2008-10-25</h2>
425<ul>
426<li>Merged with Lua 5.1.4. Fixes all
427<a href="http://www.lua.org/bugs.html#5.1.3"><span class="ext">&raquo;</span>&nbsp;known bugs in Lua 5.1.3</a>.</li>
428</ul>
429
430<h2 id="LuaJIT-1.1.4">LuaJIT 1.1.4 &mdash; 2008-02-05</h2>
431<ul>
432<li>Merged with Lua 5.1.3. Fixes all
433<a href="http://www.lua.org/bugs.html#5.1.2"><span class="ext">&raquo;</span>&nbsp;known bugs in Lua 5.1.2</a>.</li>
434<li>Fixed possible (but unlikely) stack corruption while compiling
435<tt>k^x</tt> expressions.</li>
436<li>Fixed DynASM template for cmpss instruction.</li>
437</ul>
438
439<h2 id="LuaJIT-1.1.3">LuaJIT 1.1.3 &mdash; 2007-05-24</h2>
440<ul>
441<li>Merged with Lua 5.1.2. Fixes all
442<a href="http://www.lua.org/bugs.html#5.1.1"><span class="ext">&raquo;</span>&nbsp;known bugs in Lua 5.1.1</a>.</li>
443<li>Merged pending Lua 5.1.x fixes: "return -nil" bug, spurious count hook call.</li>
444<li>Remove a (sometimes) wrong assertion in <tt>luaJIT_findpc()</tt>.</li>
445<li>DynASM now allows labels for displacements and <tt>.aword</tt>.</li>
446<li>Fix some compiler warnings for DynASM glue (internal API change).</li>
447<li>Correct naming for SSSE3 (temporarily known as SSE4) in DynASM and x86 disassembler.</li>
448<li>The loadable debug modules now handle redirection to stdout
449(e.g. <tt>-j&nbsp;trace=-</tt>).</li>
450</ul>
451
452<h2 id="LuaJIT-1.1.2">LuaJIT 1.1.2 &mdash; 2006-06-24</h2>
453<ul>
454<li>Fix MSVC inline assembly: use only local variables with
455<tt>lua_number2int()</tt>.</li>
456<li>Fix "attempt to call a thread value" bug on Mac OS X:
457make values of consts used as lightuserdata keys unique
458to avoid joining by the compiler/linker.</li>
459</ul>
460
461<h2 id="LuaJIT-1.1.1">LuaJIT 1.1.1 &mdash; 2006-06-20</h2>
462<ul>
463<li>Merged with Lua 5.1.1. Fixes all
464<a href="http://www.lua.org/bugs.html#5.1"><span class="ext">&raquo;</span>&nbsp;known bugs in Lua 5.1</a>.</li>
465<li>Enforce (dynamic) linker error for EXE/DLL version mismatches.</li>
466<li>Minor changes to DynASM: faster pre-processing, smaller encoding
467for some immediates.</li>
468</ul>
469<p>
470This release is in sync with Coco 1.1.1 (see the
471<a href="http://coco.luajit.org/changes.html"><span class="ext">&raquo;</span>&nbsp;Coco Change History</a>).
472</p>
473
474<h2 id="LuaJIT-1.1.0">LuaJIT 1.1.0 &mdash; 2006-03-13</h2>
475<ul>
476<li>Merged with Lua 5.1 (final).</li>
477
478<li>New JIT call frame setup:
479<ul>
480<li>The C stack is kept 16 byte aligned (faster).
481Mandatory for Mac OS X on Intel, too.</li>
482<li>Faster calling conventions for internal C helper functions.</li>
483<li>Better instruction scheduling for function prologue, OP_CALL and
484OP_RETURN.</li>
485</ul></li>
486
487<li>Miscellaneous optimizations:
488<ul>
489<li>Faster loads of FP constants. Remove narrow-to-wide store-to-load
490forwarding stalls.</li>
491<li>Use (scalar) SSE2 ops (if the CPU supports it) to speed up slot moves
492and FP to integer conversions.</li>
493<li>Optimized the two-argument form of <tt>OP_CONCAT</tt> (<tt>a..b</tt>).</li>
494<li>Inlined <tt>OP_MOD</tt> (<tt>a%b</tt>).
495With better accuracy than the C variant, too.</li>
496<li>Inlined <tt>OP_POW</tt> (<tt>a^b</tt>). Unroll <tt>x^k</tt> or
497use <tt>k^x = 2^(log2(k)*x)</tt> or call <tt>pow()</tt>.</li>
498</ul></li>
499
500<li>Changes in the optimizer:
501<ul>
502<li>Improved hinting for table keys derived from table values
503(<tt>t1[t2[x]]</tt>).</li>
504<li>Lookup hinting now works with arbitrary object types and
505supports index chains, too.</li>
506<li>Generate type hints for arithmetic and comparison operators,
507OP_LEN, OP_CONCAT and OP_FORPREP.</li>
508<li>Remove several hint definitions in favour of a generic COMBINE hint.</li>
509<li>Complete rewrite of <tt>jit.opt_inline</tt> module
510(ex <tt>jit.opt_lib</tt>).</li>
511</ul></li>
512
513<li>Use adaptive deoptimization:
514<ul>
515<li>If runtime verification of a contract fails, the affected
516instruction is recompiled and patched on-the-fly.
517Regular programs will trigger deoptimization only occasionally.</li>
518<li>This avoids generating code for uncommon fallback cases
519most of the time. Generated code is up to 30% smaller compared to
520LuaJIT&nbsp;1.0.3.</li>
521<li>Deoptimization is used for many opcodes and contracts:
522<ul>
523<li>OP_CALL, OP_TAILCALL: type mismatch for callable.</li>
524<li>Inlined calls: closure mismatch, parameter number and type mismatches.</li>
525<li>OP_GETTABLE, OP_SETTABLE: table or key type and range mismatches.</li>
526<li>All arithmetic and comparison operators, OP_LEN, OP_CONCAT,
527OP_FORPREP: operand type and range mismatches.</li>
528</ul></li>
529<li>Complete redesign of the debug and traceback info
530(bytecode &harr; mcode) to support deoptimization.
531Much more flexible and needs only 50% of the space.</li>
532<li>The modules <tt>jit.trace</tt>, <tt>jit.dumphints</tt> and
533<tt>jit.dump</tt> handle deoptimization.</li>
534</ul></li>
535
536<li>Inlined many popular library functions
537(for commonly used arguments only):
538<ul>
539<li>Most <tt>math.*</tt> functions (the 18 most used ones)
540[2x-10x faster].</li>
541<li><tt>string.len</tt>, <tt>string.sub</tt> and <tt>string.char</tt>
542[2x-10x faster].</li>
543<li><tt>table.insert</tt>, <tt>table.remove</tt> and <tt>table.getn</tt>
544[3x-5x faster].</li>
545<li><tt>coroutine.yield</tt> and <tt>coroutine.resume</tt>
546[3x-5x faster].</li>
547<li><tt>pairs</tt>, <tt>ipairs</tt> and the corresponding iterators
548[8x-15x faster].</li>
549</ul></li>
550
551<li>Changes in the core and loadable modules and the stand-alone executable:
552<ul>
553<li>Added <tt>jit.version</tt>, <tt>jit.version_num</tt>
554and <tt>jit.arch</tt>.</li>
555<li>Reorganized some internal API functions (<tt>jit.util.*mcode*</tt>).</li>
556<li>The <tt>-j dump</tt> output now shows JSUB names, too.</li>
557<li>New x86 disassembler module written in pure Lua. No dependency
558on ndisasm anymore. Flexible API, very compact (500 lines)
559and complete (x87, MMX, SSE, SSE2, SSE3, SSSE3, privileged instructions).</li>
560<li><tt>luajit -v</tt> prints the LuaJIT version and copyright
561on a separate line.</li>
562</ul></li>
563
564<li>Added SSE, SSE2, SSE3 and SSSE3 support to DynASM.</li>
565<li>Miscellaneous doc changes. Added a section about
566<a href="install.html#embedding">embedding LuaJIT</a>.</li>
567</ul>
568<p>
569This release is in sync with Coco 1.1.0 (see the
570<a href="http://coco.luajit.org/changes.html"><span class="ext">&raquo;</span>&nbsp;Coco Change History</a>).
571</p>
572</div>
573
574<div class="major" style="background: #ffffd0;">
575<h2 id="LuaJIT-1.0.3">LuaJIT 1.0.3 &mdash; 2005-09-08</h2>
576<ul>
577<li>Even more docs.</li>
578<li>Unified closure checks in <tt>jit.*</tt>.</li>
579<li>Fixed some range checks in <tt>jit.util.*</tt>.</li>
580<li>Fixed __newindex call originating from <tt>jit_settable_str()</tt>.</li>
581<li>Merged with Lua 5.1 alpha (including early bug fixes).</li>
582</ul>
583<p>
584This is the first public release of LuaJIT.
585</p>
586
587<h2 id="LuaJIT-1.0.2">LuaJIT 1.0.2 &mdash; 2005-09-02</h2>
588<ul>
589<li>Add support for flushing the Valgrind translation cache <br>
590(<tt>MYCFLAGS= -DUSE_VALGRIND</tt>).</li>
591<li>Add support for freeing executable mcode memory to the <tt>mmap()</tt>-based
592variant for POSIX systems.</li>
593<li>Reorganized the C&nbsp;function signature handling in
594<tt>jit.opt_lib</tt>.</li>
595<li>Changed to index-based hints for inlining C&nbsp;functions.
596Still no support in the backend for inlining.</li>
597<li>Hardcode <tt>HEAP_CREATE_ENABLE_EXECUTE</tt> value if undefined.</li>
598<li>Misc. changes to the <tt>jit.*</tt> modules.</li>
599<li>Misc. changes to the Makefiles.</li>
600<li>Lots of new docs.</li>
601<li>Complete doc reorg.</li>
602</ul>
603<p>
604Not released because Lua 5.1 alpha came out today.
605</p>
606
607<h2 id="LuaJIT-1.0.1">LuaJIT 1.0.1 &mdash; 2005-08-31</h2>
608<ul>
609<li>Missing GC step in <tt>OP_CONCAT</tt>.</li>
610<li>Fix result handling for C &ndash;> JIT calls.</li>
611<li>Detect CPU feature bits.</li>
612<li>Encode conditional moves (<tt>fucomip</tt>) only when supported.</li>
613<li>Add fallback instructions for FP compares.</li>
614<li>Add support for <tt>LUA_COMPAT_VARARG</tt>. Still disabled by default.</li>
615<li>MSVC needs a specific place for the <tt>CALLBACK</tt> attribute
616(David Burgess).</li>
617<li>Misc. doc updates.</li>
618</ul>
619<p>
620Interim non-public release.
621Special thanks to Adam D. Moss for reporting most of the bugs.
622</p>
623
624<h2 id="LuaJIT-1.0.0">LuaJIT 1.0.0 &mdash; 2005-08-29</h2>
625<p>
626This is the initial non-public release of LuaJIT.
627</p>
628</div>
629<br class="flush">
630</div>
631<div id="foot">
632<hr class="hide">
633Copyright &copy; 2005-2011 Mike Pall
634<span class="noprint">
635&middot;
636<a href="contact.html">Contact</a>
637</span>
638</div>
639</body>
640</html>
diff --git a/libraries/luajit-2.0/doc/contact.html b/libraries/luajit-2.0/doc/contact.html
new file mode 100644
index 0000000..a85c488
--- /dev/null
+++ b/libraries/luajit-2.0/doc/contact.html
@@ -0,0 +1,98 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
2<html>
3<head>
4<title>Contact</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>Contact</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_semantics.html">FFI Semantics</a>
37</li></ul>
38</li><li>
39<a href="ext_jit.html">jit.* Library</a>
40</li><li>
41<a href="ext_c_api.html">Lua/C API</a>
42</li></ul>
43</li><li>
44<a href="status.html">Status</a>
45<ul><li>
46<a href="changes.html">Changes</a>
47</li></ul>
48</li><li>
49<a href="faq.html">FAQ</a>
50</li><li>
51<a href="http://luajit.org/performance.html">Performance <span class="ext">&raquo;</span></a>
52</li><li>
53<a href="http://luajit.org/download.html">Download <span class="ext">&raquo;</span></a>
54</li></ul>
55</div>
56<div id="main">
57<p>
58Please send general questions to the
59<a href="http://www.lua.org/lua-l.html"><span class="ext">&raquo;</span>&nbsp;Lua mailing list</a>.
60You can also send any questions you have directly to me:
61</p>
62
63<script type="text/javascript">
64<!--
65var xS="@-:\" .0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ<abc>defghijklmnopqrstuvwxyz";function xD(s)
66{var len=s.length;var r="";for(var i=0;i<len;i++)
67{var c=s.charAt(i);var n=xS.indexOf(c);if(n!=-1)c=xS.charAt(69-n);r+=c;}
68document.write("<"+"p>"+r+"<"+"/p>\n");}
69//-->
70</script>
71<script type="text/javascript">
72<!--
73xD("fyZKB8xv\"FJytmz8.KAB0u52D")
74//--></script>
75<noscript>
76<p><img src="img/contact.png" alt="Contact info in image" width="170" height="13">
77</p>
78</noscript>
79
80<h2>Copyright</h2>
81<p>
82All documentation is
83Copyright &copy; 2005-2011 Mike Pall.
84</p>
85
86
87<br class="flush">
88</div>
89<div id="foot">
90<hr class="hide">
91Copyright &copy; 2005-2011 Mike Pall
92<span class="noprint">
93&middot;
94<a href="contact.html">Contact</a>
95</span>
96</div>
97</body>
98</html>
diff --git a/libraries/luajit-2.0/doc/ext_c_api.html b/libraries/luajit-2.0/doc/ext_c_api.html
new file mode 100644
index 0000000..35e2234
--- /dev/null
+++ b/libraries/luajit-2.0/doc/ext_c_api.html
@@ -0,0 +1,183 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
2<html>
3<head>
4<title>Lua/C API Extensions</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>Lua/C API Extensions</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_semantics.html">FFI Semantics</a>
37</li></ul>
38</li><li>
39<a href="ext_jit.html">jit.* Library</a>
40</li><li>
41<a class="current" href="ext_c_api.html">Lua/C API</a>
42</li></ul>
43</li><li>
44<a href="status.html">Status</a>
45<ul><li>
46<a href="changes.html">Changes</a>
47</li></ul>
48</li><li>
49<a href="faq.html">FAQ</a>
50</li><li>
51<a href="http://luajit.org/performance.html">Performance <span class="ext">&raquo;</span></a>
52</li><li>
53<a href="http://luajit.org/download.html">Download <span class="ext">&raquo;</span></a>
54</li></ul>
55</div>
56<div id="main">
57<p>
58LuaJIT adds some extensions to the standard Lua/C API. The LuaJIT include
59directory must be in the compiler search path (<tt>-I<i>path</i></tt>)
60to be able to include the required header for C code:
61</p>
62<pre class="code">
63#include "luajit.h"
64</pre>
65<p>
66Or for C++ code:
67</p>
68<pre class="code">
69#include "lua.hpp"
70</pre>
71
72<h2 id="luaJIT_setmode"><tt>luaJIT_setmode(L, idx, mode)</tt>
73&mdash; Control VM</h2>
74<p>
75This is a C API extension to allow control of the VM from C code. The
76full prototype of <tt>LuaJIT_setmode</tt> is:
77</p>
78<pre class="code">
79LUA_API int luaJIT_setmode(lua_State *L, int idx, int mode);
80</pre>
81<p>
82The returned status is either success (<tt>1</tt>) or failure (<tt>0</tt>).
83The second argument is either <tt>0</tt> or a stack index (similar to the
84other Lua/C API functions).
85</p>
86<p>
87The third argument specifies the mode, which is 'or'ed with a flag.
88The flag can be <tt>LUAJIT_MODE_OFF</tt> to turn a feature on,
89<tt>LUAJIT_MODE_ON</tt> to turn a feature off, or
90<tt>LUAJIT_MODE_FLUSH</tt> to flush cached code.
91</p>
92<p>
93The following modes are defined:
94</p>
95
96<h3 id="mode_engine"><tt>luaJIT_setmode(L, 0, LUAJIT_MODE_ENGINE|flag)</tt></h3>
97<p>
98Turn the whole JIT compiler on or off or flush the whole cache of compiled code.
99</p>
100
101<h3 id="mode_func"><tt>luaJIT_setmode(L, idx, LUAJIT_MODE_FUNC|flag)</tt><br>
102<tt>luaJIT_setmode(L, idx, LUAJIT_MODE_ALLFUNC|flag)</tt><br>
103<tt>luaJIT_setmode(L, idx, LUAJIT_MODE_ALLSUBFUNC|flag)</tt></h3>
104<p>
105This sets the mode for the function at the stack index <tt>idx</tt> or
106the parent of the calling function (<tt>idx = 0</tt>). It either
107enables JIT compilation for a function, disables it and flushes any
108already compiled code or only flushes already compiled code. This
109applies recursively to all sub-functions of the function with
110<tt>LUAJIT_MODE_ALLFUNC</tt> or only to the sub-functions with
111<tt>LUAJIT_MODE_ALLSUBFUNC</tt>.
112</p>
113
114<h3 id="mode_trace"><tt>luaJIT_setmode(L, trace,<br>
115&nbsp;&nbsp;LUAJIT_MODE_TRACE|LUAJIT_MODE_FLUSH)</tt></h3>
116<p>
117Flushes the specified root trace and all of its side traces from the cache.
118The code for the trace will be retained as long as there are any other
119traces which link to it.
120</p>
121
122<h3 id="mode_wrapcfunc"><tt>luaJIT_setmode(L, idx, LUAJIT_MODE_WRAPCFUNC|flag)</tt></h3>
123<p>
124This mode defines a wrapper function for calls to C functions. If
125called with <tt>LUAJIT_MODE_ON</tt>, the stack index at <tt>idx</tt>
126must be a <tt>lightuserdata</tt> object holding a pointer to the wrapper
127function. From now on all C functions are called through the wrapper
128function. If called with <tt>LUAJIT_MODE_OFF</tt> this mode is turned
129off and all C functions are directly called.
130</p>
131<p>
132The wrapper function can be used for debugging purposes or to catch
133and convert foreign exceptions. But please read the section on
134<a href="extensions.html#exceptions">C++&nbsp;exception interoperability</a>
135first. Recommended usage can be seen in this C++ code excerpt:
136</p>
137<pre class="code">
138#include &lt;exception&gt;
139#include "lua.hpp"
140
141// Catch C++ exceptions and convert them to Lua error messages.
142// Customize as needed for your own exception classes.
143static int wrap_exceptions(lua_State *L, lua_CFunction f)
144{
145 try {
146 return f(L); // Call wrapped function and return result.
147 } catch (const char *s) { // Catch and convert exceptions.
148 lua_pushstring(L, s);
149 } catch (std::exception& e) {
150 lua_pushstring(L, e.what());
151 } catch (...) {
152 lua_pushliteral(L, "caught (...)");
153 }
154 return lua_error(L); // Rethrow as a Lua error.
155}
156
157static int myinit(lua_State *L)
158{
159 ...
160 // Define wrapper function and enable it.
161 lua_pushlightuserdata(L, (void *)wrap_exceptions);
162 luaJIT_setmode(L, -1, LUAJIT_MODE_WRAPCFUNC|LUAJIT_MODE_ON);
163 lua_pop(L, 1);
164 ...
165}
166</pre>
167<p>
168Note that you can only define <b>a single global wrapper function</b>,
169so be careful when using this mechanism from multiple C++ modules.
170Also note that this mechanism is not without overhead.
171</p>
172<br class="flush">
173</div>
174<div id="foot">
175<hr class="hide">
176Copyright &copy; 2005-2011 Mike Pall
177<span class="noprint">
178&middot;
179<a href="contact.html">Contact</a>
180</span>
181</div>
182</body>
183</html>
diff --git a/libraries/luajit-2.0/doc/ext_ffi.html b/libraries/luajit-2.0/doc/ext_ffi.html
new file mode 100644
index 0000000..9b59a3f
--- /dev/null
+++ b/libraries/luajit-2.0/doc/ext_ffi.html
@@ -0,0 +1,332 @@
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 Library</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<style type="text/css">
12span.codemark { position:absolute; left: 16em; color: #4040c0; }
13span.mark { color: #4040c0; font-family: Courier New, Courier, monospace;
14 line-height: 1.1; }
15pre.mark { padding-left: 2em; }
16</style>
17</head>
18<body>
19<div id="site">
20<a href="http://luajit.org"><span>Lua<span id="logo">JIT</span></span></a>
21</div>
22<div id="head">
23<h1>FFI Library</h1>
24</div>
25<div id="nav">
26<ul><li>
27<a href="luajit.html">LuaJIT</a>
28<ul><li>
29<a href="install.html">Installation</a>
30</li><li>
31<a href="running.html">Running</a>
32</li></ul>
33</li><li>
34<a href="extensions.html">Extensions</a>
35<ul><li>
36<a class="current" href="ext_ffi.html">FFI Library</a>
37<ul><li>
38<a href="ext_ffi_tutorial.html">FFI Tutorial</a>
39</li><li>
40<a href="ext_ffi_api.html">ffi.* API</a>
41</li><li>
42<a href="ext_ffi_semantics.html">FFI Semantics</a>
43</li></ul>
44</li><li>
45<a href="ext_jit.html">jit.* Library</a>
46</li><li>
47<a href="ext_c_api.html">Lua/C API</a>
48</li></ul>
49</li><li>
50<a href="status.html">Status</a>
51<ul><li>
52<a href="changes.html">Changes</a>
53</li></ul>
54</li><li>
55<a href="faq.html">FAQ</a>
56</li><li>
57<a href="http://luajit.org/performance.html">Performance <span class="ext">&raquo;</span></a>
58</li><li>
59<a href="http://luajit.org/download.html">Download <span class="ext">&raquo;</span></a>
60</li></ul>
61</div>
62<div id="main">
63<p>
64
65The FFI library allows <b>calling external C&nbsp;functions</b> and
66<b>using C&nbsp;data structures</b> from pure Lua code.
67
68</p>
69<p>
70
71The FFI library largely obviates the need to write tedious manual
72Lua/C bindings in C. No need to learn a separate binding language
73&mdash; <b>it parses plain C&nbsp;declarations!</b> These can be
74cut-n-pasted from C&nbsp;header files or reference manuals. It's up to
75the task of binding large libraries without the need for dealing with
76fragile binding generators.
77
78</p>
79<p>
80The FFI library is tightly integrated into LuaJIT (it's not available
81as a separate module). The code generated by the JIT-compiler for
82accesses to C&nbsp;data structures from Lua code is on par with the
83code a C&nbsp;compiler would generate. Calls to C&nbsp;functions can
84be inlined in JIT-compiled code, unlike calls to functions bound via
85the classic Lua/C API.
86</p>
87<p>
88This page gives a short introduction to the usage of the FFI library.
89<em>Please use the FFI sub-topics in the navigation bar to learn more.</em>
90</p>
91
92<h2 id="call">Motivating Example: Calling External C Functions</h2>
93<p>
94It's really easy to call an external C&nbsp;library function:
95</p>
96<pre class="code mark">
97<span class="codemark">&#9312;
98&#9313;
99
100
101&#9314;</span>local ffi = require("ffi")
102ffi.cdef[[
103<span style="color:#00a000;">int printf(const char *fmt, ...);</span>
104]]
105ffi.C.printf("Hello %s!", "world")
106</pre>
107<p>
108So, let's pick that apart:
109</p>
110<p>
111<span class="mark">&#9312;</span> Load the FFI library.
112</p>
113<p>
114<span class="mark">&#9313;</span> Add a C&nbsp;declaration
115for the function. The part inside the double-brackets (in green) is
116just standard C&nbsp;syntax.
117</p>
118<p>
119<span class="mark">&#9314;</span> Call the named
120C&nbsp;function &mdash; Yes, it's that simple!
121</p>
122<p style="font-size: 8pt;">
123Actually, what goes on behind the scenes is far from simple: <span
124style="color:#4040c0;">&#9314;</span> makes use of the standard
125C&nbsp;library namespace <tt>ffi.C</tt>. Indexing this namespace with
126a symbol name (<tt>"printf"</tt>) automatically binds it to the the
127standard C&nbsp;library. The result is a special kind of object which,
128when called, runs the <tt>printf</tt> function. The arguments passed
129to this function are automatically converted from Lua objects to the
130corresponding C&nbsp;types.
131</p>
132<p>
133Ok, so maybe the use of <tt>printf()</tt> wasn't such a spectacular
134example. You could have done that with <tt>io.write()</tt> and
135<tt>string.format()</tt>, too. But you get the idea ...
136</p>
137<p>
138So here's something to pop up a message box on Windows:
139</p>
140<pre class="code">
141local ffi = require("ffi")
142ffi.cdef[[
143<span style="color:#00a000;">int MessageBoxA(void *w, const char *txt, const char *cap, int type);</span>
144]]
145ffi.C.MessageBoxA(nil, "Hello world!", "Test", 0)
146</pre>
147<p>
148Bing! Again, that was far too easy, no?
149</p>
150<p style="font-size: 8pt;">
151Compare this with the effort required to bind that function using the
152classic Lua/C API: create an extra C&nbsp;file, add a C&nbsp;function
153that retrieves and checks the argument types passed from Lua and calls
154the actual C&nbsp;function, add a list of module functions and their
155names, add a <tt>luaopen_*</tt> function and register all module
156functions, compile and link it into a shared library (DLL), move it to
157the proper path, add Lua code that loads the module aaaand ... finally
158call the binding function. Phew!
159</p>
160
161<h2 id="cdata">Motivating Example: Using C Data Structures</h2>
162<p>
163The FFI library allows you to create and access C&nbsp;data
164structures. Of course the main use for this is for interfacing with
165C&nbsp;functions. But they can be used stand-alone, too.
166</p>
167<p>
168Lua is built upon high-level data types. They are flexible, extensible
169and dynamic. That's why we all love Lua so much. Alas, this can be
170inefficient for certain tasks, where you'd really want a low-level
171data type. E.g. a large array of a fixed structure needs to be
172implemented with a big table holding lots of tiny tables. This imposes
173both a substantial memory overhead as well as a performance overhead.
174</p>
175<p>
176Here's a sketch of a library that operates on color images plus a
177simple benchmark. First, the plain Lua version:
178</p>
179<pre class="code">
180local floor = math.floor
181
182local function image_ramp_green(n)
183 local img = {}
184 local f = 255/(n-1)
185 for i=1,n do
186 img[i] = { red = 0, green = floor((i-1)*f), blue = 0, alpha = 255 }
187 end
188 return img
189end
190
191local function image_to_grey(img, n)
192 for i=1,n do
193 local y = floor(0.3*img[i].red + 0.59*img[i].green + 0.11*img[i].blue)
194 img[i].red = y; img[i].green = y; img[i].blue = y
195 end
196end
197
198local N = 400*400
199local img = image_ramp_green(N)
200for i=1,1000 do
201 image_to_grey(img, N)
202end
203</pre>
204<p>
205This creates a table with 160.000 pixels, each of which is a table
206holding four number values in the range of 0-255. First an image with
207a green ramp is created (1D for simplicity), then the image is
208converted to greyscale 1000 times. Yes, that's silly, but I was in
209need of a simple example ...
210</p>
211<p>
212And here's the FFI version. The modified parts have been marked in
213bold:
214</p>
215<pre class="code mark">
216<span class="codemark">&#9312;
217
218
219
220
221
222&#9313;
223
224&#9314;
225&#9315;
226
227
228
229
230
231
232&#9314;
233&#9316;</span><b>local ffi = require("ffi")
234ffi.cdef[[
235</b><span style="color:#00a000;">typedef struct { uint8_t red, green, blue, alpha; } rgba_pixel;</span><b>
236]]</b>
237
238local function image_ramp_green(n)
239 <b>local img = ffi.new("rgba_pixel[?]", n)</b>
240 local f = 255/(n-1)
241 for i=<b>0,n-1</b> do
242 <b>img[i].green = i*f</b>
243 <b>img[i].alpha = 255</b>
244 end
245 return img
246end
247
248local function image_to_grey(img, n)
249 for i=<b>0,n-1</b> do
250 local y = <b>0.3*img[i].red + 0.59*img[i].green + 0.11*img[i].blue</b>
251 img[i].red = y; img[i].green = y; img[i].blue = y
252 end
253end
254
255local N = 400*400
256local img = image_ramp_green(N)
257for i=1,1000 do
258 image_to_grey(img, N)
259end
260</pre>
261<p>
262Ok, so that wasn't too difficult:
263</p>
264<p>
265<span class="mark">&#9312;</span> First, load the FFI
266library and declare the low-level data type. Here we choose a
267<tt>struct</tt> which holds four byte fields, one for each component
268of a 4x8&nbsp;bit RGBA pixel.
269</p>
270<p>
271<span class="mark">&#9313;</span> Creating the data
272structure with <tt>ffi.new()</tt> is straightforward &mdash; the
273<tt>'?'</tt> is a placeholder for the number of elements of a
274variable-length array.
275</p>
276<p>
277<span class="mark">&#9314;</span> C&nbsp;arrays are
278zero-based, so the indexes have to run from <tt>0</tt> to
279<tt>n-1</tt>. One might want to allocate one more element instead to
280simplify converting legacy code.
281</p>
282<p>
283<span class="mark">&#9315;</span> Since <tt>ffi.new()</tt>
284zero-fills the array by default, we only need to set the green and the
285alpha fields.
286</p>
287<p>
288<span class="mark">&#9316;</span> The calls to
289<tt>math.floor()</tt> can be omitted here, because floating-point
290numbers are already truncated towards zero when converting them to an
291integer. This happens implicitly when the number is stored in the
292fields of each pixel.
293</p>
294<p>
295Now let's have a look at the impact of the changes: first, memory
296consumption for the image is down from 22&nbsp;Megabytes to
297640&nbsp;Kilobytes (400*400*4 bytes). That's a factor of 35x less! So,
298yes, tables do have a noticeable overhead. BTW: The original program
299would consume 40&nbsp;Megabytes in plain Lua (on x64).
300</p>
301<p>
302Next, performance: the pure Lua version runs in 9.57 seconds (52.9
303seconds with the Lua interpreter) and the FFI version runs in 0.48
304seconds on my machine (YMMV). That's a factor of 20x faster (110x
305faster than the Lua interpreter).
306</p>
307<p style="font-size: 8pt;">
308The avid reader may notice that converting the pure Lua version over
309to use array indexes for the colors (<tt>[1]</tt> instead of
310<tt>.red</tt>, <tt>[2]</tt> instead of <tt>.green</tt> etc.) ought to
311be more compact and faster. This is certainly true (by a factor of
312~1.7x). Switching to a struct-of-arrays would help, too.
313</p>
314<p style="font-size: 8pt;">
315However the resulting code would be less idiomatic and rather
316error-prone. And it still doesn't get even close to the performance of
317the FFI version of the code. Also, high-level data structures cannot
318be easily passed to other C&nbsp;functions, especially I/O functions,
319without undue conversion penalties.
320</p>
321<br class="flush">
322</div>
323<div id="foot">
324<hr class="hide">
325Copyright &copy; 2005-2011 Mike Pall
326<span class="noprint">
327&middot;
328<a href="contact.html">Contact</a>
329</span>
330</div>
331</body>
332</html>
diff --git a/libraries/luajit-2.0/doc/ext_ffi_api.html b/libraries/luajit-2.0/doc/ext_ffi_api.html
new file mode 100644
index 0000000..222c580
--- /dev/null
+++ b/libraries/luajit-2.0/doc/ext_ffi_api.html
@@ -0,0 +1,553 @@
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.* API Functions</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<style type="text/css">
12table.abitable { width: 30em; line-height: 1.2; }
13tr.abihead td { font-weight: bold; }
14td.abiparam { font-weight: bold; width: 6em; }
15</style>
16</head>
17<body>
18<div id="site">
19<a href="http://luajit.org"><span>Lua<span id="logo">JIT</span></span></a>
20</div>
21<div id="head">
22<h1><tt>ffi.*</tt> API Functions</h1>
23</div>
24<div id="nav">
25<ul><li>
26<a href="luajit.html">LuaJIT</a>
27<ul><li>
28<a href="install.html">Installation</a>
29</li><li>
30<a href="running.html">Running</a>
31</li></ul>
32</li><li>
33<a href="extensions.html">Extensions</a>
34<ul><li>
35<a href="ext_ffi.html">FFI Library</a>
36<ul><li>
37<a href="ext_ffi_tutorial.html">FFI Tutorial</a>
38</li><li>
39<a class="current" href="ext_ffi_api.html">ffi.* API</a>
40</li><li>
41<a href="ext_ffi_semantics.html">FFI Semantics</a>
42</li></ul>
43</li><li>
44<a href="ext_jit.html">jit.* Library</a>
45</li><li>
46<a href="ext_c_api.html">Lua/C API</a>
47</li></ul>
48</li><li>
49<a href="status.html">Status</a>
50<ul><li>
51<a href="changes.html">Changes</a>
52</li></ul>
53</li><li>
54<a href="faq.html">FAQ</a>
55</li><li>
56<a href="http://luajit.org/performance.html">Performance <span class="ext">&raquo;</span></a>
57</li><li>
58<a href="http://luajit.org/download.html">Download <span class="ext">&raquo;</span></a>
59</li></ul>
60</div>
61<div id="main">
62<p>
63This page describes the API functions provided by the FFI library in
64detail. It's recommended to read through the
65<a href="ext_ffi.html">introduction</a> and the
66<a href="ext_ffi_tutorial.html">FFI tutorial</a> first.
67</p>
68
69<h2 id="glossary">Glossary</h2>
70<ul>
71<li><b>cdecl</b> &mdash; An abstract C&nbsp;type declaration (a Lua
72string).</li>
73<li><b>ctype</b> &mdash; A C&nbsp;type object. This is a special kind of
74<b>cdata</b> returned by <tt>ffi.typeof()</tt>. It serves as a
75<b>cdata</b> <a href="#ffi_new">constructor</a> when called.</li>
76<li><b>cdata</b> &mdash; A C&nbsp;data object. It holds a value of the
77corresponding <b>ctype</b>.</li>
78<li><b>ct</b> &mdash; A C&nbsp;type specification which can be used for
79most of the API functions. Either a <b>cdecl</b>, a <b>ctype</b> or a
80<b>cdata</b> serving as a template type.</li>
81<li><b>cb</b> &mdash; A callback object. This is a C&nbsp;data object
82holding a special function pointer. Calling this function from
83C&nbsp;code runs an associated Lua function.</li>
84<li><b>VLA</b> &mdash; A variable-length array is declared with a
85<tt>?</tt> instead of the number of elements, e.g. <tt>"int[?]"</tt>.
86The number of elements (<tt>nelem</tt>) must be given when it's
87<a href="#ffi_new">created</a>.</li>
88<li><b>VLS</b> &mdash; A variable-length struct is a <tt>struct</tt> C
89type where the last element is a <b>VLA</b>. The same rules for
90declaration and creation apply.</li>
91</ul>
92
93<h2 id="decl">Declaring and Accessing External Symbols</h2>
94<p>
95External symbols must be declared first and can then be accessed by
96indexing a <a href="ext_ffi_semantics.html#clib">C&nbsp;library
97namespace</a>, which automatically binds the symbol to a specific
98library.
99</p>
100
101<h3 id="ffi_cdef"><tt>ffi.cdef(def)</tt></h3>
102<p>
103Adds multiple C&nbsp;declarations for types or external symbols (named
104variables or functions). <tt>def</tt> must be a Lua string. It's
105recommended to use the syntactic sugar for string arguments as
106follows:
107</p>
108<pre class="code">
109ffi.cdef[[
110<span style="color:#00a000;">typedef struct foo { int a, b; } foo_t; // Declare a struct and typedef.
111int dofoo(foo_t *f, int n); /* Declare an external C function. */</span>
112]]
113</pre>
114<p>
115The contents of the string (the part in green above) must be a
116sequence of
117<a href="ext_ffi_semantics.html#clang">C&nbsp;declarations</a>,
118separated by semicolons. The trailing semicolon for a single
119declaration may be omitted.
120</p>
121<p>
122Please note that external symbols are only <em>declared</em>, but they
123are <em>not bound</em> to any specific address, yet. Binding is
124achieved with C&nbsp;library namespaces (see below).
125</p>
126<p style="color: #c00000;">
127C&nbsp;declarations are not passed through a C&nbsp;pre-processor,
128yet. No pre-processor tokens are allowed, except for
129<tt>#pragma&nbsp;pack</tt>. Replace <tt>#define</tt> in existing
130C&nbsp;header files with <tt>enum</tt>, <tt>static&nbsp;const</tt>
131or <tt>typedef</tt> and/or pass the files through an external
132C&nbsp;pre-processor (once). Be careful not to include unneeded or
133redundant declarations from unrelated header files.
134</p>
135
136<h3 id="ffi_C"><tt>ffi.C</tt></h3>
137<p>
138This is the default C&nbsp;library namespace &mdash; note the
139uppercase <tt>'C'</tt>. It binds to the default set of symbols or
140libraries on the target system. These are more or less the same as a
141C&nbsp;compiler would offer by default, without specifying extra link
142libraries.
143</p>
144<p>
145On POSIX systems, this binds to symbols in the default or global
146namespace. This includes all exported symbols from the executable and
147any libraries loaded into the global namespace. This includes at least
148<tt>libc</tt>, <tt>libm</tt>, <tt>libdl</tt> (on Linux),
149<tt>libgcc</tt> (if compiled with GCC), as well as any exported
150symbols from the Lua/C&nbsp;API provided by LuaJIT itself.
151</p>
152<p>
153On Windows systems, this binds to symbols exported from the
154<tt>*.exe</tt>, the <tt>lua51.dll</tt> (i.e. the Lua/C&nbsp;API
155provided by LuaJIT itself), the C&nbsp;runtime library LuaJIT was linked
156with (<tt>msvcrt*.dll</tt>), <tt>kernel32.dll</tt>,
157<tt>user32.dll</tt> and <tt>gdi32.dll</tt>.
158</p>
159
160<h3 id="ffi_load"><tt>clib = ffi.load(name [,global])</tt></h3>
161<p>
162This loads the dynamic library given by <tt>name</tt> and returns
163a new C&nbsp;library namespace which binds to its symbols. On POSIX
164systems, if <tt>global</tt> is <tt>true</tt>, the library symbols are
165loaded into the global namespace, too.
166</p>
167<p>
168If <tt>name</tt> is a path, the library is loaded from this path.
169Otherwise <tt>name</tt> is canonicalized in a system-dependent way and
170searched in the default search path for dynamic libraries:
171</p>
172<p>
173On POSIX systems, if the name contains no dot, the extension
174<tt>.so</tt> is appended. Also, the <tt>lib</tt> prefix is prepended
175if necessary. So <tt>ffi.load("z")</tt> looks for <tt>"libz.so"</tt>
176in the default shared library search path.
177</p>
178<p>
179On Windows systems, if the name contains no dot, the extension
180<tt>.dll</tt> is appended. So <tt>ffi.load("ws2_32")</tt> looks for
181<tt>"ws2_32.dll"</tt> in the default DLL search path.
182</p>
183
184<h2 id="create">Creating cdata Objects</h2>
185<p>
186The following API functions create cdata objects (<tt>type()</tt>
187returns <tt>"cdata"</tt>). All created cdata objects are
188<a href="ext_ffi_semantics.html#gc">garbage collected</a>.
189</p>
190
191<h3 id="ffi_new"><tt>cdata = ffi.new(ct [,nelem] [,init...])<br>
192cdata = <em>ctype</em>([nelem,] [init...])</tt></h3>
193<p>
194Creates a cdata object for the given <tt>ct</tt>. VLA/VLS types
195require the <tt>nelem</tt> argument. The second syntax uses a ctype as
196a constructor and is otherwise fully equivalent.
197</p>
198<p>
199The cdata object is initialized according to the
200<a href="ext_ffi_semantics.html#init">rules for initializers</a>,
201using the optional <tt>init</tt> arguments. Excess initializers cause
202an error.
203</p>
204<p>
205Performance notice: if you want to create many objects of one kind,
206parse the cdecl only once and get its ctype with
207<tt>ffi.typeof()</tt>. Then use the ctype as a constructor repeatedly.
208</p>
209<p style="font-size: 8pt;">
210Please note that an anonymous <tt>struct</tt> declaration implicitly
211creates a new and distinguished ctype every time you use it for
212<tt>ffi.new()</tt>. This is probably <b>not</b> what you want,
213especially if you create more than one cdata object. Different anonymous
214<tt>structs</tt> are not considered assignment-compatible by the
215C&nbsp;standard, even though they may have the same fields! Also, they
216are considered different types by the JIT-compiler, which may cause an
217excessive number of traces. It's strongly suggested to either declare
218a named <tt>struct</tt> or <tt>typedef</tt> with <tt>ffi.cdef()</tt>
219or to create a single ctype object for an anonymous <tt>struct</tt>
220with <tt>ffi.typeof()</tt>.
221</p>
222
223<h3 id="ffi_typeof"><tt>ctype = ffi.typeof(ct)</tt></h3>
224<p>
225Creates a ctype object for the given <tt>ct</tt>.
226</p>
227<p>
228This function is especially useful to parse a cdecl only once and then
229use the resulting ctype object as a <a href="#ffi_new">constructor</a>.
230</p>
231
232<h3 id="ffi_cast"><tt>cdata = ffi.cast(ct, init)</tt></h3>
233<p>
234Creates a scalar cdata object for the given <tt>ct</tt>. The cdata
235object is initialized with <tt>init</tt> using the "cast" variant of
236the <a href="ext_ffi_semantics.html#convert">C&nbsp;type conversion
237rules</a>.
238</p>
239<p>
240This functions is mainly useful to override the pointer compatibility
241checks or to convert pointers to addresses or vice versa.
242</p>
243
244<h3 id="ffi_metatype"><tt>ctype = ffi.metatype(ct, metatable)</tt></h3>
245<p>
246Creates a ctype object for the given <tt>ct</tt> and associates it with
247a metatable. Only <tt>struct</tt>/<tt>union</tt> types, complex numbers
248and vectors are allowed. Other types may be wrapped in a
249<tt>struct</tt>, if needed.
250</p>
251<p>
252The association with a metatable is permanent and cannot be changed
253afterwards. Neither the contents of the <tt>metatable</tt> nor the
254contents of an <tt>__index</tt> table (if any) may be modified
255afterwards. The associated metatable automatically applies to all uses
256of this type, no matter how the objects are created or where they
257originate from. Note that pre-defined operations on types have
258precedence (e.g. declared field names cannot be overriden).
259</p>
260<p>
261All standard Lua metamethods are implemented. These are called directly,
262without shortcuts and on any mix of types. For binary operations, the
263left operand is checked first for a valid ctype metamethod. The
264<tt>__gc</tt> metamethod only applies to <tt>struct</tt>/<tt>union</tt>
265types and performs an implicit <a href="#ffi_gc"><tt>ffi.gc()</tt></a>
266call during creation of an instance.
267</p>
268
269<h3 id="ffi_gc"><tt>cdata = ffi.gc(cdata, finalizer)</tt></h3>
270<p>
271Associates a finalizer with a pointer or aggregate cdata object. The
272cdata object is returned unchanged.
273</p>
274<p>
275This function allows safe integration of unmanaged resources into the
276automatic memory management of the LuaJIT garbage collector. Typical
277usage:
278</p>
279<pre class="code">
280local p = ffi.gc(ffi.C.malloc(n), ffi.C.free)
281...
282p = nil -- Last reference to p is gone.
283-- GC will eventually run finalizer: ffi.C.free(p)
284</pre>
285<p>
286A cdata finalizer works like the <tt>__gc</tt> metamethod for userdata
287objects: when the last reference to a cdata object is gone, the
288associated finalizer is called with the cdata object as an argument. The
289finalizer can be a Lua function or a cdata function or cdata function
290pointer. An existing finalizer can be removed by setting a <tt>nil</tt>
291finalizer, e.g. right before explicitly deleting a resource:
292</p>
293<pre class="code">
294ffi.C.free(ffi.gc(p, nil)) -- Manually free the memory.
295</pre>
296
297<h2 id="info">C&nbsp;Type Information</h2>
298<p>
299The following API functions return information about C&nbsp;types.
300They are most useful for inspecting cdata objects.
301</p>
302
303<h3 id="ffi_sizeof"><tt>size = ffi.sizeof(ct [,nelem])</tt></h3>
304<p>
305Returns the size of <tt>ct</tt> in bytes. Returns <tt>nil</tt> if
306the size is not known (e.g. for <tt>"void"</tt> or function types).
307Requires <tt>nelem</tt> for VLA/VLS types, except for cdata objects.
308</p>
309
310<h3 id="ffi_alignof"><tt>align = ffi.alignof(ct)</tt></h3>
311<p>
312Returns the minimum required alignment for <tt>ct</tt> in bytes.
313</p>
314
315<h3 id="ffi_offsetof"><tt>ofs [,bpos,bsize] = ffi.offsetof(ct, field)</tt></h3>
316<p>
317Returns the offset (in bytes) of <tt>field</tt> relative to the start
318of <tt>ct</tt>, which must be a <tt>struct</tt>. Additionally returns
319the position and the field size (in bits) for bit fields.
320</p>
321
322<h3 id="ffi_istype"><tt>status = ffi.istype(ct, obj)</tt></h3>
323<p>
324Returns <tt>true</tt> if <tt>obj</tt> has the C&nbsp;type given by
325<tt>ct</tt>. Returns <tt>false</tt> otherwise.
326</p>
327<p>
328C&nbsp;type qualifiers (<tt>const</tt> etc.) are ignored. Pointers are
329checked with the standard pointer compatibility rules, but without any
330special treatment for <tt>void&nbsp;*</tt>. If <tt>ct</tt> specifies a
331<tt>struct</tt>/<tt>union</tt>, then a pointer to this type is accepted,
332too. Otherwise the types must match exactly.
333</p>
334<p>
335Note: this function accepts all kinds of Lua objects for the
336<tt>obj</tt> argument, but always returns <tt>false</tt> for non-cdata
337objects.
338</p>
339
340<h2 id="util">Utility Functions</h2>
341
342<h3 id="ffi_errno"><tt>err = ffi.errno([newerr])</tt></h3>
343<p>
344Returns the error number set by the last C&nbsp;function call which
345indicated an error condition. If the optional <tt>newerr</tt> argument
346is present, the error number is set to the new value and the previous
347value is returned.
348</p>
349<p>
350This function offers a portable and OS-independent way to get and set the
351error number. Note that only <em>some</em> C&nbsp;functions set the error
352number. And it's only significant if the function actually indicated an
353error condition (e.g. with a return value of <tt>-1</tt> or
354<tt>NULL</tt>). Otherwise, it may or may not contain any previously set
355value.
356</p>
357<p>
358You're advised to call this function only when needed and as close as
359possible after the return of the related C&nbsp;function. The
360<tt>errno</tt> value is preserved across hooks, memory allocations,
361invocations of the JIT compiler and other internal VM activity. The same
362applies to the value returned by <tt>GetLastError()</tt> on Windows, but
363you need to declare and call it yourself.
364</p>
365
366<h3 id="ffi_string"><tt>str = ffi.string(ptr [,len])</tt></h3>
367<p>
368Creates an interned Lua string from the data pointed to by
369<tt>ptr</tt>.
370</p>
371<p>
372If the optional argument <tt>len</tt> is missing, <tt>ptr</tt> is
373converted to a <tt>"char&nbsp;*"</tt> and the data is assumed to be
374zero-terminated. The length of the string is computed with
375<tt>strlen()</tt>.
376</p>
377<p>
378Otherwise <tt>ptr</tt> is converted to a <tt>"void&nbsp;*"</tt> and
379<tt>len</tt> gives the length of the data. The data may contain
380embedded zeros and need not be byte-oriented (though this may cause
381endianess issues).
382</p>
383<p>
384This function is mainly useful to convert (temporary)
385<tt>"const&nbsp;char&nbsp;*"</tt> pointers returned by
386C&nbsp;functions to Lua strings and store them or pass them to other
387functions expecting a Lua string. The Lua string is an (interned) copy
388of the data and bears no relation to the original data area anymore.
389Lua strings are 8&nbsp;bit clean and may be used to hold arbitrary,
390non-character data.
391</p>
392<p>
393Performance notice: it's faster to pass the length of the string, if
394it's known. E.g. when the length is returned by a C&nbsp;call like
395<tt>sprintf()</tt>.
396</p>
397
398<h3 id="ffi_copy"><tt>ffi.copy(dst, src, len)<br>
399ffi.copy(dst, str)</tt></h3>
400<p>
401Copies the data pointed to by <tt>src</tt> to <tt>dst</tt>.
402<tt>dst</tt> is converted to a <tt>"void&nbsp;*"</tt> and <tt>src</tt>
403is converted to a <tt>"const void&nbsp;*"</tt>.
404</p>
405<p>
406In the first syntax, <tt>len</tt> gives the number of bytes to copy.
407Caveat: if <tt>src</tt> is a Lua string, then <tt>len</tt> must not
408exceed <tt>#src+1</tt>.
409</p>
410<p>
411In the second syntax, the source of the copy must be a Lua string. All
412bytes of the string <em>plus a zero-terminator</em> are copied to
413<tt>dst</tt> (i.e. <tt>#src+1</tt> bytes).
414</p>
415<p>
416Performance notice: <tt>ffi.copy()</tt> may be used as a faster
417(inlinable) replacement for the C&nbsp;library functions
418<tt>memcpy()</tt>, <tt>strcpy()</tt> and <tt>strncpy()</tt>.
419</p>
420
421<h3 id="ffi_fill"><tt>ffi.fill(dst, len [,c])</tt></h3>
422<p>
423Fills the data pointed to by <tt>dst</tt> with <tt>len</tt> constant
424bytes, given by <tt>c</tt>. If <tt>c</tt> is omitted, the data is
425zero-filled.
426</p>
427<p>
428Performance notice: <tt>ffi.fill()</tt> may be used as a faster
429(inlinable) replacement for the C&nbsp;library function
430<tt>memset(dst,&nbsp;c,&nbsp;len)</tt>. Please note the different
431order of arguments!
432</p>
433
434<h2 id="target">Target-specific Information</h2>
435
436<h3 id="ffi_abi"><tt>status = ffi.abi(param)</tt></h3>
437<p>
438Returns <tt>true</tt> if <tt>param</tt> (a Lua string) applies for the
439target ABI (Application Binary Interface). Returns <tt>false</tt>
440otherwise. The following parameters are currently defined:
441</p>
442<table class="abitable">
443<tr class="abihead">
444<td class="abiparam">Parameter</td>
445<td class="abidesc">Description</td>
446</tr>
447<tr class="odd separate">
448<td class="abiparam">32bit</td><td class="abidesc">32 bit architecture</td></tr>
449<tr class="even">
450<td class="abiparam">64bit</td><td class="abidesc">64 bit architecture</td></tr>
451<tr class="odd separate">
452<td class="abiparam">le</td><td class="abidesc">Little-endian architecture</td></tr>
453<tr class="even">
454<td class="abiparam">be</td><td class="abidesc">Big-endian architecture</td></tr>
455<tr class="odd separate">
456<td class="abiparam">fpu</td><td class="abidesc">Target has a hardware FPU</td></tr>
457<tr class="even">
458<td class="abiparam">softfp</td><td class="abidesc">softfp calling conventions</td></tr>
459<tr class="odd">
460<td class="abiparam">hardfp</td><td class="abidesc">hardfp calling conventions</td></tr>
461<tr class="even separate">
462<td class="abiparam">eabi</td><td class="abidesc">EABI variant of the standard ABI</td></tr>
463<tr class="odd">
464<td class="abiparam">win</td><td class="abidesc">Windows variant of the standard ABI</td></tr>
465</table>
466
467<h3 id="ffi_os"><tt>ffi.os</tt></h3>
468<p>
469Contains the target OS name. Same contents as
470<a href="ext_jit.html#jit_os"><tt>jit.os</tt></a>.
471</p>
472
473<h3 id="ffi_arch"><tt>ffi.arch</tt></h3>
474<p>
475Contains the target architecture name. Same contents as
476<a href="ext_jit.html#jit_arch"><tt>jit.arch</tt></a>.
477</p>
478
479<h2 id="callback">Methods for Callbacks</h2>
480<p>
481The C&nbsp;types for <a href="ext_ffi_semantics.html#callback">callbacks</a>
482have some extra methods:
483</p>
484
485<h3 id="callback_free"><tt>cb:free()</tt></h3>
486<p>
487Free the resources associated with a callback. The associated Lua
488function is unanchored and may be garbage collected. The callback
489function pointer is no longer valid and must not be called anymore
490(it may be reused by a subsequently created callback).
491</p>
492
493<h3 id="callback_set"><tt>cb:set(func)</tt></h3>
494<p>
495Associate a new Lua function with a callback. The C&nbsp;type of the
496callback and the callback function pointer are unchanged.
497</p>
498<p>
499This method is useful to dynamically switch the receiver of callbacks
500without creating a new callback each time and registering it again (e.g.
501with a GUI library).
502</p>
503
504<h2 id="extended">Extended Standard Library Functions</h2>
505<p>
506The following standard library functions have been extended to work
507with cdata objects:
508</p>
509
510<h3 id="tonumber"><tt>n = tonumber(cdata)</tt></h3>
511<p>
512Converts a number cdata object to a <tt>double</tt> and returns it as
513a Lua number. This is particularly useful for boxed 64&nbsp;bit
514integer values. Caveat: this conversion may incur a precision loss.
515</p>
516
517<h3 id="tostring"><tt>s = tostring(cdata)</tt></h3>
518<p>
519Returns a string representation of the value of 64&nbsp;bit integers
520(<tt><b>"</b>nnn<b>LL"</b></tt> or <tt><b>"</b>nnn<b>ULL"</b></tt>) or
521complex numbers (<tt><b>"</b>re&plusmn;im<b>i"</b></tt>). Otherwise
522returns a string representation of the C&nbsp;type of a ctype object
523(<tt><b>"ctype&lt;</b>type<b>&gt;"</b></tt>) or a cdata object
524(<tt><b>"cdata&lt;</b>type<b>&gt;:&nbsp;</b>address"</tt>).
525</p>
526
527<h2 id="literals">Extensions to the Lua Parser</h2>
528<p>
529The parser for Lua source code treats numeric literals with the
530suffixes <tt>LL</tt> or <tt>ULL</tt> as signed or unsigned 64&nbsp;bit
531integers. Case doesn't matter, but uppercase is recommended for
532readability. It handles both decimal (<tt>42LL</tt>) and hexadecimal
533(<tt>0x2aLL</tt>) literals.
534</p>
535<p>
536The imaginary part of complex numbers can be specified by suffixing
537number literals with <tt>i</tt> or <tt>I</tt>, e.g. <tt>12.5i</tt>.
538Caveat: you'll need to use <tt>1i</tt> to get an imaginary part with
539the value one, since <tt>i</tt> itself still refers to a variable
540named <tt>i</tt>.
541</p>
542<br class="flush">
543</div>
544<div id="foot">
545<hr class="hide">
546Copyright &copy; 2005-2011 Mike Pall
547<span class="noprint">
548&middot;
549<a href="contact.html">Contact</a>
550</span>
551</div>
552</body>
553</html>
diff --git a/libraries/luajit-2.0/doc/ext_ffi_semantics.html b/libraries/luajit-2.0/doc/ext_ffi_semantics.html
new file mode 100644
index 0000000..661b0b4
--- /dev/null
+++ b/libraries/luajit-2.0/doc/ext_ffi_semantics.html
@@ -0,0 +1,1146 @@
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<style type="text/css">
12table.convtable { line-height: 1.2; }
13tr.convhead td { font-weight: bold; }
14td.convin { width: 11em; }
15td.convop { font-style: italic; width: 16em; }
16</style>
17</head>
18<body>
19<div id="site">
20<a href="http://luajit.org"><span>Lua<span id="logo">JIT</span></span></a>
21</div>
22<div id="head">
23<h1>FFI Semantics</h1>
24</div>
25<div id="nav">
26<ul><li>
27<a href="luajit.html">LuaJIT</a>
28<ul><li>
29<a href="install.html">Installation</a>
30</li><li>
31<a href="running.html">Running</a>
32</li></ul>
33</li><li>
34<a href="extensions.html">Extensions</a>
35<ul><li>
36<a href="ext_ffi.html">FFI Library</a>
37<ul><li>
38<a href="ext_ffi_tutorial.html">FFI Tutorial</a>
39</li><li>
40<a href="ext_ffi_api.html">ffi.* API</a>
41</li><li>
42<a class="current" href="ext_ffi_semantics.html">FFI Semantics</a>
43</li></ul>
44</li><li>
45<a href="ext_jit.html">jit.* Library</a>
46</li><li>
47<a href="ext_c_api.html">Lua/C API</a>
48</li></ul>
49</li><li>
50<a href="status.html">Status</a>
51<ul><li>
52<a href="changes.html">Changes</a>
53</li></ul>
54</li><li>
55<a href="faq.html">FAQ</a>
56</li><li>
57<a href="http://luajit.org/performance.html">Performance <span class="ext">&raquo;</span></a>
58</li><li>
59<a href="http://luajit.org/download.html">Download <span class="ext">&raquo;</span></a>
60</li></ul>
61</div>
62<div id="main">
63<p>
64This page describes the detailed semantics underlying the FFI library
65and its interaction with both Lua and C&nbsp;code.
66</p>
67<p>
68Given that the FFI library is designed to interface with C&nbsp;code
69and that declarations can be written in plain C&nbsp;syntax, <b>it
70closely follows the C&nbsp;language semantics</b>, wherever possible.
71Some minor concessions are needed for smoother interoperation with Lua
72language semantics.
73</p>
74<p>
75Please don't be overwhelmed by the contents of this page &mdash; this
76is a reference and you may need to consult it, if in doubt. It doesn't
77hurt to skim this page, but most of the semantics "just work" as you'd
78expect them to work. It should be straightforward to write
79applications using the LuaJIT FFI for developers with a C or C++
80background.
81</p>
82<p class="indent" style="color: #c00000;">
83Please note: this doesn't comprise the final specification for the FFI
84semantics, yet. Some semantics may need to be changed, based on your
85feedback. Please <a href="contact.html">report</a> any problems you may
86encounter or any improvements you'd like to see &mdash; thank you!
87</p>
88
89<h2 id="clang">C Language Support</h2>
90<p>
91The FFI library has a built-in C&nbsp;parser with a minimal memory
92footprint. It's used by the <a href="ext_ffi_api.html">ffi.* library
93functions</a> to declare C&nbsp;types or external symbols.
94</p>
95<p>
96It's only purpose is to parse C&nbsp;declarations, as found e.g. in
97C&nbsp;header files. Although it does evaluate constant expressions,
98it's <em>not</em> a C&nbsp;compiler. The body of <tt>inline</tt>
99C&nbsp;function definitions is simply ignored.
100</p>
101<p>
102Also, this is <em>not</em> a validating C&nbsp;parser. It expects and
103accepts correctly formed C&nbsp;declarations, but it may choose to
104ignore bad declarations or show rather generic error messages. If in
105doubt, please check the input against your favorite C&nbsp;compiler.
106</p>
107<p>
108The C&nbsp;parser complies to the <b>C99 language standard</b> plus
109the following extensions:
110</p>
111<ul>
112
113<li>The <tt>'\e'</tt> escape in character and string literals.</li>
114
115<li>The C99/C++ boolean type, declared with the keywords <tt>bool</tt>
116or <tt>_Bool</tt>.</li>
117
118<li>Complex numbers, declared with the keywords <tt>complex</tt> or
119<tt>_Complex</tt>.</li>
120
121<li>Two complex number types: <tt>complex</tt> (aka
122<tt>complex&nbsp;double</tt>) and <tt>complex&nbsp;float</tt>.</li>
123
124<li>Vector types, declared with the GCC <tt>mode</tt> or
125<tt>vector_size</tt> attribute.</li>
126
127<li>Unnamed ('transparent') <tt>struct</tt>/<tt>union</tt> fields
128inside a <tt>struct</tt>/<tt>union</tt>.</li>
129
130<li>Incomplete <tt>enum</tt> declarations, handled like incomplete
131<tt>struct</tt> declarations.</li>
132
133<li>Unnamed <tt>enum</tt> fields inside a
134<tt>struct</tt>/<tt>union</tt>. This is similar to a scoped C++
135<tt>enum</tt>, except that declared constants are visible in the
136global namespace, too.</li>
137
138<li>Scoped <tt>static&nbsp;const</tt> declarations inside a
139<tt>struct</tt>/<tt>union</tt> (from C++).</li>
140
141<li>Zero-length arrays (<tt>[0]</tt>), empty
142<tt>struct</tt>/<tt>union</tt>, variable-length arrays (VLA,
143<tt>[?]</tt>) and variable-length structs (VLS, with a trailing
144VLA).</li>
145
146<li>C++ reference types (<tt>int&nbsp;&amp;x</tt>).</li>
147
148<li>Alternate GCC keywords with '<tt>__</tt>', e.g.
149<tt>__const__</tt>.</li>
150
151<li>GCC <tt>__attribute__</tt> with the following attributes:
152<tt>aligned</tt>, <tt>packed</tt>, <tt>mode</tt>,
153<tt>vector_size</tt>, <tt>cdecl</tt>, <tt>fastcall</tt>,
154<tt>stdcall</tt>.</li>
155
156<li>The GCC <tt>__extension__</tt> keyword and the GCC
157<tt>__alignof__</tt> operator.</li>
158
159<li>GCC <tt>__asm__("symname")</tt> symbol name redirection for
160function declarations.</li>
161
162<li>MSVC keywords for fixed-length types: <tt>__int8</tt>,
163<tt>__int16</tt>, <tt>__int32</tt> and <tt>__int64</tt>.</li>
164
165<li>MSVC <tt>__cdecl</tt>, <tt>__fastcall</tt>, <tt>__stdcall</tt>,
166<tt>__ptr32</tt>, <tt>__ptr64</tt>, <tt>__declspec(align(n))</tt>
167and <tt>#pragma&nbsp;pack</tt>.</li>
168
169<li>All other GCC/MSVC-specific attributes are ignored.</li>
170
171</ul>
172<p>
173The following C&nbsp;types are pre-defined by the C&nbsp;parser (like
174a <tt>typedef</tt>, except re-declarations will be ignored):
175</p>
176<ul>
177
178<li>Vararg handling: <tt>va_list</tt>, <tt>__builtin_va_list</tt>,
179<tt>__gnuc_va_list</tt>.</li>
180
181<li>From <tt>&lt;stddef.h&gt;</tt>: <tt>ptrdiff_t</tt>,
182<tt>size_t</tt>, <tt>wchar_t</tt>.</li>
183
184<li>From <tt>&lt;stdint.h&gt;</tt>: <tt>int8_t</tt>, <tt>int16_t</tt>,
185<tt>int32_t</tt>, <tt>int64_t</tt>, <tt>uint8_t</tt>,
186<tt>uint16_t</tt>, <tt>uint32_t</tt>, <tt>uint64_t</tt>,
187<tt>intptr_t</tt>, <tt>uintptr_t</tt>.</li>
188
189</ul>
190<p>
191You're encouraged to use these types in preference to the
192compiler-specific extensions or the target-dependent standard types.
193E.g. <tt>char</tt> differs in signedness and <tt>long</tt> differs in
194size, depending on the target architecture and platform ABI.
195</p>
196<p>
197The following C&nbsp;features are <b>not</b> supported:
198</p>
199<ul>
200
201<li>A declaration must always have a type specifier; it doesn't
202default to an <tt>int</tt> type.</li>
203
204<li>Old-style empty function declarations (K&amp;R) are not allowed.
205All C&nbsp;functions must have a proper prototype declaration. A
206function declared without parameters (<tt>int&nbsp;foo();</tt>) is
207treated as a function taking zero arguments, like in C++.</li>
208
209<li>The <tt>long double</tt> C&nbsp;type is parsed correctly, but
210there's no support for the related conversions, accesses or arithmetic
211operations.</li>
212
213<li>Wide character strings and character literals are not
214supported.</li>
215
216<li><a href="#status">See below</a> for features that are currently
217not implemented.</li>
218
219</ul>
220
221<h2 id="convert">C Type Conversion Rules</h2>
222
223<h3 id="convert_tolua">Conversions from C&nbsp;types to Lua objects</h3>
224<p>
225These conversion rules apply for <em>read accesses</em> to
226C&nbsp;types: indexing pointers, arrays or
227<tt>struct</tt>/<tt>union</tt> types; reading external variables or
228constant values; retrieving return values from C&nbsp;calls:
229</p>
230<table class="convtable">
231<tr class="convhead">
232<td class="convin">Input</td>
233<td class="convop">Conversion</td>
234<td class="convout">Output</td>
235</tr>
236<tr class="odd separate">
237<td class="convin"><tt>int8_t</tt>, <tt>int16_t</tt></td><td class="convop">&rarr;<sup>sign-ext</sup> <tt>int32_t</tt> &rarr; <tt>double</tt></td><td class="convout">number</td></tr>
238<tr class="even">
239<td class="convin"><tt>uint8_t</tt>, <tt>uint16_t</tt></td><td class="convop">&rarr;<sup>zero-ext</sup> <tt>int32_t</tt> &rarr; <tt>double</tt></td><td class="convout">number</td></tr>
240<tr class="odd">
241<td class="convin"><tt>int32_t</tt>, <tt>uint32_t</tt></td><td class="convop">&rarr; <tt>double</tt></td><td class="convout">number</td></tr>
242<tr class="even">
243<td class="convin"><tt>int64_t</tt>, <tt>uint64_t</tt></td><td class="convop">boxed value</td><td class="convout">64 bit int cdata</td></tr>
244<tr class="odd separate">
245<td class="convin"><tt>double</tt>, <tt>float</tt></td><td class="convop">&rarr; <tt>double</tt></td><td class="convout">number</td></tr>
246<tr class="even separate">
247<td class="convin"><tt>bool</tt></td><td class="convop">0 &rarr; <tt>false</tt>, otherwise <tt>true</tt></td><td class="convout">boolean</td></tr>
248<tr class="odd separate">
249<td class="convin">Complex number</td><td class="convop">boxed value</td><td class="convout">complex cdata</td></tr>
250<tr class="even">
251<td class="convin">Vector</td><td class="convop">boxed value</td><td class="convout">vector cdata</td></tr>
252<tr class="odd">
253<td class="convin">Pointer</td><td class="convop">boxed value</td><td class="convout">pointer cdata</td></tr>
254<tr class="even separate">
255<td class="convin">Array</td><td class="convop">boxed reference</td><td class="convout">reference cdata</td></tr>
256<tr class="odd">
257<td class="convin"><tt>struct</tt>/<tt>union</tt></td><td class="convop">boxed reference</td><td class="convout">reference cdata</td></tr>
258</table>
259<p>
260Bitfields or <tt>enum</tt> types are treated like their underlying
261type.
262</p>
263<p>
264Reference types are dereferenced <em>before</em> a conversion can take
265place &mdash; the conversion is applied to the C&nbsp;type pointed to
266by the reference.
267</p>
268
269<h3 id="convert_fromlua">Conversions from Lua objects to C&nbsp;types</h3>
270<p>
271These conversion rules apply for <em>write accesses</em> to
272C&nbsp;types: indexing pointers, arrays or
273<tt>struct</tt>/<tt>union</tt> types; initializing cdata objects;
274casts to C&nbsp;types; writing to external variables; passing
275arguments to C&nbsp;calls:
276</p>
277<table class="convtable">
278<tr class="convhead">
279<td class="convin">Input</td>
280<td class="convop">Conversion</td>
281<td class="convout">Output</td>
282</tr>
283<tr class="odd separate">
284<td class="convin">number</td><td class="convop">&rarr;</td><td class="convout"><tt>double</tt></td></tr>
285<tr class="even">
286<td class="convin">boolean</td><td class="convop"><tt>false</tt> &rarr; 0, <tt>true</tt> &rarr; 1</td><td class="convout"><tt>bool</tt></td></tr>
287<tr class="odd separate">
288<td class="convin">nil</td><td class="convop"><tt>NULL</tt> &rarr;</td><td class="convout"><tt>(void *)</tt></td></tr>
289<tr class="even">
290<td class="convin">userdata</td><td class="convop">userdata payload &rarr;</td><td class="convout"><tt>(void *)</tt></td></tr>
291<tr class="odd">
292<td class="convin">lightuserdata</td><td class="convop">lightuserdata address &rarr;</td><td class="convout"><tt>(void *)</tt></td></tr>
293<tr class="even separate">
294<td class="convin">string</td><td class="convop">match against <tt>enum</tt> constant</td><td class="convout"><tt>enum</tt></td></tr>
295<tr class="odd">
296<td class="convin">string</td><td class="convop">copy string data + zero-byte</td><td class="convout"><tt>int8_t[]</tt>, <tt>uint8_t[]</tt></td></tr>
297<tr class="even">
298<td class="convin">string</td><td class="convop">string data &rarr;</td><td class="convout"><tt>const char[]</tt></td></tr>
299<tr class="odd separate">
300<td class="convin">function</td><td class="convop"><a href="#callback">create callback</a> &rarr;</td><td class="convout">C function type</td></tr>
301<tr class="even separate">
302<td class="convin">table</td><td class="convop"><a href="#init_table">table initializer</a></td><td class="convout">Array</td></tr>
303<tr class="odd">
304<td class="convin">table</td><td class="convop"><a href="#init_table">table initializer</a></td><td class="convout"><tt>struct</tt>/<tt>union</tt></td></tr>
305<tr class="even separate">
306<td class="convin">cdata</td><td class="convop">cdata payload &rarr;</td><td class="convout">C type</td></tr>
307</table>
308<p>
309If the result type of this conversion doesn't match the
310C&nbsp;type of the destination, the
311<a href="#convert_between">conversion rules between C&nbsp;types</a>
312are applied.
313</p>
314<p>
315Reference types are immutable after initialization ("no re-seating of
316references"). For initialization purposes or when passing values to
317reference parameters, they are treated like pointers. Note that unlike
318in C++, there's no way to implement automatic reference generation of
319variables under the Lua language semantics. If you want to call a
320function with a reference parameter, you need to explicitly pass a
321one-element array.
322</p>
323
324<h3 id="convert_between">Conversions between C&nbsp;types</h3>
325<p>
326These conversion rules are more or less the same as the standard
327C&nbsp;conversion rules. Some rules only apply to casts, or require
328pointer or type compatibility:
329</p>
330<table class="convtable">
331<tr class="convhead">
332<td class="convin">Input</td>
333<td class="convop">Conversion</td>
334<td class="convout">Output</td>
335</tr>
336<tr class="odd separate">
337<td class="convin">Signed integer</td><td class="convop">&rarr;<sup>narrow or sign-extend</sup></td><td class="convout">Integer</td></tr>
338<tr class="even">
339<td class="convin">Unsigned integer</td><td class="convop">&rarr;<sup>narrow or zero-extend</sup></td><td class="convout">Integer</td></tr>
340<tr class="odd">
341<td class="convin">Integer</td><td class="convop">&rarr;<sup>round</sup></td><td class="convout"><tt>double</tt>, <tt>float</tt></td></tr>
342<tr class="even">
343<td class="convin"><tt>double</tt>, <tt>float</tt></td><td class="convop">&rarr;<sup>trunc</sup> <tt>int32_t</tt> &rarr;<sup>narrow</sup></td><td class="convout"><tt>(u)int8_t</tt>, <tt>(u)int16_t</tt></td></tr>
344<tr class="odd">
345<td class="convin"><tt>double</tt>, <tt>float</tt></td><td class="convop">&rarr;<sup>trunc</sup></td><td class="convout"><tt>(u)int32_t</tt>, <tt>(u)int64_t</tt></td></tr>
346<tr class="even">
347<td class="convin"><tt>double</tt>, <tt>float</tt></td><td class="convop">&rarr;<sup>round</sup></td><td class="convout"><tt>float</tt>, <tt>double</tt></td></tr>
348<tr class="odd separate">
349<td class="convin">Number</td><td class="convop">n == 0 &rarr; 0, otherwise 1</td><td class="convout"><tt>bool</tt></td></tr>
350<tr class="even">
351<td class="convin"><tt>bool</tt></td><td class="convop"><tt>false</tt> &rarr; 0, <tt>true</tt> &rarr; 1</td><td class="convout">Number</td></tr>
352<tr class="odd separate">
353<td class="convin">Complex number</td><td class="convop">convert real part</td><td class="convout">Number</td></tr>
354<tr class="even">
355<td class="convin">Number</td><td class="convop">convert real part, imag = 0</td><td class="convout">Complex number</td></tr>
356<tr class="odd">
357<td class="convin">Complex number</td><td class="convop">convert real and imag part</td><td class="convout">Complex number</td></tr>
358<tr class="even separate">
359<td class="convin">Number</td><td class="convop">convert scalar and replicate</td><td class="convout">Vector</td></tr>
360<tr class="odd">
361<td class="convin">Vector</td><td class="convop">copy (same size)</td><td class="convout">Vector</td></tr>
362<tr class="even separate">
363<td class="convin"><tt>struct</tt>/<tt>union</tt></td><td class="convop">take base address (compat)</td><td class="convout">Pointer</td></tr>
364<tr class="odd">
365<td class="convin">Array</td><td class="convop">take base address (compat)</td><td class="convout">Pointer</td></tr>
366<tr class="even">
367<td class="convin">Function</td><td class="convop">take function address</td><td class="convout">Function pointer</td></tr>
368<tr class="odd separate">
369<td class="convin">Number</td><td class="convop">convert via <tt>uintptr_t</tt> (cast)</td><td class="convout">Pointer</td></tr>
370<tr class="even">
371<td class="convin">Pointer</td><td class="convop">convert address (compat/cast)</td><td class="convout">Pointer</td></tr>
372<tr class="odd">
373<td class="convin">Pointer</td><td class="convop">convert address (cast)</td><td class="convout">Integer</td></tr>
374<tr class="even">
375<td class="convin">Array</td><td class="convop">convert base address (cast)</td><td class="convout">Integer</td></tr>
376<tr class="odd separate">
377<td class="convin">Array</td><td class="convop">copy (compat)</td><td class="convout">Array</td></tr>
378<tr class="even">
379<td class="convin"><tt>struct</tt>/<tt>union</tt></td><td class="convop">copy (identical type)</td><td class="convout"><tt>struct</tt>/<tt>union</tt></td></tr>
380</table>
381<p>
382Bitfields or <tt>enum</tt> types are treated like their underlying
383type.
384</p>
385<p>
386Conversions not listed above will raise an error. E.g. it's not
387possible to convert a pointer to a complex number or vice versa.
388</p>
389
390<h3 id="convert_vararg">Conversions for vararg C&nbsp;function arguments</h3>
391<p>
392The following default conversion rules apply when passing Lua objects
393to the variable argument part of vararg C&nbsp;functions:
394</p>
395<table class="convtable">
396<tr class="convhead">
397<td class="convin">Input</td>
398<td class="convop">Conversion</td>
399<td class="convout">Output</td>
400</tr>
401<tr class="odd separate">
402<td class="convin">number</td><td class="convop">&rarr;</td><td class="convout"><tt>double</tt></td></tr>
403<tr class="even">
404<td class="convin">boolean</td><td class="convop"><tt>false</tt> &rarr; 0, <tt>true</tt> &rarr; 1</td><td class="convout"><tt>bool</tt></td></tr>
405<tr class="odd separate">
406<td class="convin">nil</td><td class="convop"><tt>NULL</tt> &rarr;</td><td class="convout"><tt>(void *)</tt></td></tr>
407<tr class="even">
408<td class="convin">userdata</td><td class="convop">userdata payload &rarr;</td><td class="convout"><tt>(void *)</tt></td></tr>
409<tr class="odd">
410<td class="convin">lightuserdata</td><td class="convop">lightuserdata address &rarr;</td><td class="convout"><tt>(void *)</tt></td></tr>
411<tr class="even separate">
412<td class="convin">string</td><td class="convop">string data &rarr;</td><td class="convout"><tt>const char *</tt></td></tr>
413<tr class="odd separate">
414<td class="convin"><tt>float</tt> cdata</td><td class="convop">&rarr;</td><td class="convout"><tt>double</tt></td></tr>
415<tr class="even">
416<td class="convin">Array cdata</td><td class="convop">take base address</td><td class="convout">Element pointer</td></tr>
417<tr class="odd">
418<td class="convin"><tt>struct</tt>/<tt>union</tt> cdata</td><td class="convop">take base address</td><td class="convout"><tt>struct</tt>/<tt>union</tt> pointer</td></tr>
419<tr class="even">
420<td class="convin">Function cdata</td><td class="convop">take function address</td><td class="convout">Function pointer</td></tr>
421<tr class="odd">
422<td class="convin">Any other cdata</td><td class="convop">no conversion</td><td class="convout">C type</td></tr>
423</table>
424<p>
425To pass a Lua object, other than a cdata object, as a specific type,
426you need to override the conversion rules: create a temporary cdata
427object with a constructor or a cast and initialize it with the value
428to pass:
429</p>
430<p>
431Assuming <tt>x</tt> is a Lua number, here's how to pass it as an
432integer to a vararg function:
433</p>
434<pre class="code">
435ffi.cdef[[
436int printf(const char *fmt, ...);
437]]
438ffi.C.printf("integer value: %d\n", ffi.new("int", x))
439</pre>
440<p>
441If you don't do this, the default Lua number &rarr; <tt>double</tt>
442conversion rule applies. A vararg C&nbsp;function expecting an integer
443will see a garbled or uninitialized value.
444</p>
445
446<h2 id="init">Initializers</h2>
447<p>
448Creating a cdata object with
449<a href="ext_ffi_api.html#ffi_new"><tt>ffi.new()</tt></a> or the
450equivalent constructor syntax always initializes its contents, too.
451Different rules apply, depending on the number of optional
452initializers and the C&nbsp;types involved:
453</p>
454<ul>
455<li>If no initializers are given, the object is filled with zero bytes.</li>
456
457<li>Scalar types (numbers and pointers) accept a single initializer.
458The Lua object is <a href="#convert_fromlua">converted to the scalar
459C&nbsp;type</a>.</li>
460
461<li>Valarrays (complex numbers and vectors) are treated like scalars
462when a single initializer is given. Otherwise they are treated like
463regular arrays.</li>
464
465<li>Aggregate types (arrays and structs) accept either a single
466<a href="#init_table">table initializer</a> or a flat list of
467initializers.</li>
468
469<li>The elements of an array are initialized, starting at index zero.
470If a single initializer is given for an array, it's repeated for all
471remaining elements. This doesn't happen if two or more initializers
472are given: all remaining uninitialized elements are filled with zero
473bytes.</li>
474
475<li>Byte arrays may also be initialized with a Lua string. This copies
476the whole string plus a terminating zero-byte. The copy stops early only
477if the array has a known, fixed size.</li>
478
479<li>The fields of a <tt>struct</tt> are initialized in the order of
480their declaration. Uninitialized fields are filled with zero
481bytes.</li>
482
483<li>Only the first field of a <tt>union</tt> can be initialized with a
484flat initializer.</li>
485
486<li>Elements or fields which are aggregates themselves are initialized
487with a <em>single</em> initializer, but this may be a table
488initializer or a compatible aggregate.</li>
489
490<li>Excess initializers cause an error.</li>
491
492</ul>
493
494<h2 id="init_table">Table Initializers</h2>
495<p>
496The following rules apply if a Lua table is used to initialize an
497Array or a <tt>struct</tt>/<tt>union</tt>:
498</p>
499<ul>
500
501<li>If the table index <tt>[0]</tt> is non-<tt>nil</tt>, then the
502table is assumed to be zero-based. Otherwise it's assumed to be
503one-based.</li>
504
505<li>Array elements, starting at index zero, are initialized one-by-one
506with the consecutive table elements, starting at either index
507<tt>[0]</tt> or <tt>[1]</tt>. This process stops at the first
508<tt>nil</tt> table element.</li>
509
510<li>If exactly one array element was initialized, it's repeated for
511all the remaining elements. Otherwise all remaining uninitialized
512elements are filled with zero bytes.</li>
513
514<li>The above logic only applies to arrays with a known fixed size.
515A VLA is only initialized with the element(s) given in the table.
516Depending on the use case, you may need to explicitly add a
517<tt>NULL</tt> or <tt>0</tt> terminator to a VLA.</li>
518
519<li>If the table has a non-empty hash part, a
520<tt>struct</tt>/<tt>union</tt> is initialized by looking up each field
521name (as a string key) in the table. Each non-<tt>nil</tt> value is
522used to initialize the corresponding field.</li>
523
524<li>Otherwise a <tt>struct</tt>/<tt>union</tt> is initialized in the
525order of the declaration of its fields. Each field is initialized with
526the consecutive table elements, starting at either index <tt>[0]</tt>
527or <tt>[1]</tt>. This process stops at the first <tt>nil</tt> table
528element.</li>
529
530<li>Uninitialized fields of a <tt>struct</tt> are filled with zero
531bytes, except for the trailing VLA of a VLS.</li>
532
533<li>Initialization of a <tt>union</tt> stops after one field has been
534initialized. If no field has been initialized, the <tt>union</tt> is
535filled with zero bytes.</li>
536
537<li>Elements or fields which are aggregates themselves are initialized
538with a <em>single</em> initializer, but this may be a nested table
539initializer (or a compatible aggregate).</li>
540
541<li>Excess initializers for an array cause an error. Excess
542initializers for a <tt>struct</tt>/<tt>union</tt> are ignored.
543Unrelated table entries are ignored, too.</li>
544
545</ul>
546<p>
547Example:
548</p>
549<pre class="code">
550local ffi = require("ffi")
551
552ffi.cdef[[
553struct foo { int a, b; };
554union bar { int i; double d; };
555struct nested { int x; struct foo y; };
556]]
557
558ffi.new("int[3]", {}) --> 0, 0, 0
559ffi.new("int[3]", {1}) --> 1, 1, 1
560ffi.new("int[3]", {1,2}) --> 1, 2, 0
561ffi.new("int[3]", {1,2,3}) --> 1, 2, 3
562ffi.new("int[3]", {[0]=1}) --> 1, 1, 1
563ffi.new("int[3]", {[0]=1,2}) --> 1, 2, 0
564ffi.new("int[3]", {[0]=1,2,3}) --> 1, 2, 3
565ffi.new("int[3]", {[0]=1,2,3,4}) --> error: too many initializers
566
567ffi.new("struct foo", {}) --> a = 0, b = 0
568ffi.new("struct foo", {1}) --> a = 1, b = 0
569ffi.new("struct foo", {1,2}) --> a = 1, b = 2
570ffi.new("struct foo", {[0]=1,2}) --> a = 1, b = 2
571ffi.new("struct foo", {b=2}) --> a = 0, b = 2
572ffi.new("struct foo", {a=1,b=2,c=3}) --> a = 1, b = 2 'c' is ignored
573
574ffi.new("union bar", {}) --> i = 0, d = 0.0
575ffi.new("union bar", {1}) --> i = 1, d = ?
576ffi.new("union bar", {[0]=1,2}) --> i = 1, d = ? '2' is ignored
577ffi.new("union bar", {d=2}) --> i = ?, d = 2.0
578
579ffi.new("struct nested", {1,{2,3}}) --> x = 1, y.a = 2, y.b = 3
580ffi.new("struct nested", {x=1,y={2,3}}) --> x = 1, y.a = 2, y.b = 3
581</pre>
582
583<h2 id="cdata_ops">Operations on cdata Objects</h2>
584<p>
585All of the standard Lua operators can be applied to cdata objects or a
586mix of a cdata object and another Lua object. The following list shows
587the valid combinations. All other combinations currently raise an
588error.
589</p>
590<p>
591Reference types are dereferenced <em>before</em> performing each of
592the operations below &mdash; the operation is applied to the
593C&nbsp;type pointed to by the reference.
594</p>
595<p>
596The pre-defined operations are always tried first before deferring to a
597metamethod for a ctype (if defined).
598</p>
599
600<h3 id="cdata_array">Indexing a cdata object</h3>
601<ul>
602
603<li><b>Indexing a pointer/array</b>: a cdata pointer/array can be
604indexed by a cdata number or a Lua number. The element address is
605computed as the base address plus the number value multiplied by the
606element size in bytes. A read access loads the element value and
607<a href="#convert_tolua">converts it to a Lua object</a>. A write
608access <a href="#convert_fromlua">converts a Lua object to the element
609type</a> and stores the converted value to the element. An error is
610raised if the element size is undefined or a write access to a
611constant element is attempted.</li>
612
613<li><b>Dereferencing a <tt>struct</tt>/<tt>union</tt> field</b>: a
614cdata <tt>struct</tt>/<tt>union</tt> or a pointer to a
615<tt>struct</tt>/<tt>union</tt> can be dereferenced by a string key,
616giving the field name. The field address is computed as the base
617address plus the relative offset of the field. A read access loads the
618field value and <a href="#convert_tolua">converts it to a Lua
619object</a>. A write access <a href="#convert_fromlua">converts a Lua
620object to the field type</a> and stores the converted value to the
621field. An error is raised if a write access to a constant
622<tt>struct</tt>/<tt>union</tt> or a constant field is attempted.</li>
623
624<li><b>Indexing a complex number</b>: a complex number can be indexed
625either by a cdata number or a Lua number with the values 0 or 1, or by
626the strings <tt>"re"</tt> or <tt>"im"</tt>. A read access loads the
627real part (<tt>[0]</tt>, <tt>.re</tt>) or the imaginary part
628(<tt>[1]</tt>, <tt>.im</tt>) part of a complex number and
629<a href="#convert_tolua">converts it to a Lua number</a>. The
630sub-parts of a complex number are immutable &mdash; assigning to an
631index of a complex number raises an error. Accessing out-of-bound
632indexes returns unspecified results, but is guaranteed not to trigger
633memory access violations.</li>
634
635<li><b>Indexing a vector</b>: a vector is treated like an array for
636indexing purposes, except the vector elements are immutable &mdash;
637assigning to an index of a vector raises an error.</li>
638
639</ul>
640<p>
641Note: since there's (deliberately) no address-of operator, a cdata
642object holding a value type is effectively immutable after
643initialization. The JIT compiler benefits from this fact when applying
644certain optimizations.
645</p>
646<p>
647As a consequence of this, the <em>elements</em> of complex numbers and
648vectors are immutable. But the elements of an aggregate holding these
649types <em>may</em> be modified of course. I.e. you cannot assign to
650<tt>foo.c.im</tt>, but you can assign a (newly created) complex number
651to <tt>foo.c</tt>.
652</p>
653
654<h3 id="cdata_call">Calling a cdata object</h3>
655<ul>
656
657<li><b>Constructor</b>: a ctype object can be called and used as a
658<a href="ext_ffi_api.html#ffi_new">constructor</a>.</li>
659
660<li><b>C&nbsp;function call</b>: a cdata function or cdata function
661pointer can be called. The passed arguments are
662<a href="#convert_fromlua">converted to the C&nbsp;types</a> of the
663parameters given by the function declaration. Arguments passed to the
664variable argument part of vararg C&nbsp;function use
665<a href="#convert_vararg">special conversion rules</a>. This
666C&nbsp;function is called and the return value (if any) is
667<a href="#convert_tolua">converted to a Lua object</a>.<br>
668On Windows/x86 systems, <tt>__stdcall</tt> functions are automatically
669detected and a function declared as <tt>__cdecl</tt> (the default) is
670silently fixed up after the first call.</li>
671
672</ul>
673
674<h3 id="cdata_arith">Arithmetic on cdata objects</h3>
675<ul>
676
677<li><b>Pointer arithmetic</b>: a cdata pointer/array and a cdata
678number or a Lua number can be added or subtracted. The number must be
679on the right hand side for a subtraction. The result is a pointer of
680the same type with an address plus or minus the number value
681multiplied by the element size in bytes. An error is raised if the
682element size is undefined.</li>
683
684<li><b>Pointer difference</b>: two compatible cdata pointers/arrays
685can be subtracted. The result is the difference between their
686addresses, divided by the element size in bytes. An error is raised if
687the element size is undefined or zero.</li>
688
689<li><b>64&nbsp;bit integer arithmetic</b>: the standard arithmetic
690operators (<tt>+&nbsp;-&nbsp;*&nbsp;/&nbsp;%&nbsp;^</tt> and unary
691minus) can be applied to two cdata numbers, or a cdata number and a
692Lua number. If one of them is an <tt>uint64_t</tt>, the other side is
693converted to an <tt>uint64_t</tt> and an unsigned arithmetic operation
694is performed. Otherwise both sides are converted to an
695<tt>int64_t</tt> and a signed arithmetic operation is performed. The
696result is a boxed 64&nbsp;bit cdata object.<br>
697
698These rules ensure that 64&nbsp;bit integers are "sticky". Any
699expression involving at least one 64&nbsp;bit integer operand results
700in another one. The undefined cases for the division, modulo and power
701operators return <tt>2LL&nbsp;^&nbsp;63</tt> or
702<tt>2ULL&nbsp;^&nbsp;63</tt>.<br>
703
704You'll have to explicitly convert a 64&nbsp;bit integer to a Lua
705number (e.g. for regular floating-point calculations) with
706<tt>tonumber()</tt>. But note this may incur a precision loss.</li>
707
708</ul>
709
710<h3 id="cdata_comp">Comparisons of cdata objects</h3>
711<ul>
712
713<li><b>Pointer comparison</b>: two compatible cdata pointers/arrays
714can be compared. The result is the same as an unsigned comparison of
715their addresses. <tt>nil</tt> is treated like a <tt>NULL</tt> pointer,
716which is compatible with any other pointer type.</li>
717
718<li><b>64&nbsp;bit integer comparison</b>: two cdata numbers, or a
719cdata number and a Lua number can be compared with each other. If one
720of them is an <tt>uint64_t</tt>, the other side is converted to an
721<tt>uint64_t</tt> and an unsigned comparison is performed. Otherwise
722both sides are converted to an <tt>int64_t</tt> and a signed
723comparison is performed.</li>
724
725</ul>
726
727<h3 id="cdata_key">cdata objects as table keys</h3>
728<p>
729Lua tables may be indexed by cdata objects, but this doesn't provide
730any useful semantics &mdash; <b>cdata objects are unsuitable as table
731keys!</b>
732</p>
733<p>
734A cdata object is treated like any other garbage-collected object and
735is hashed and compared by its address for table indexing. Since
736there's no interning for cdata value types, the same value may be
737boxed in different cdata objects with different addresses. Thus
738<tt>t[1LL+1LL]</tt> and <tt>t[2LL]</tt> usually <b>do not</b> point to
739the same hash slot and they certainly <b>do not</b> point to the same
740hash slot as <tt>t[2]</tt>.
741</p>
742<p>
743It would seriously drive up implementation complexity and slow down
744the common case, if one were to add extra handling for by-value
745hashing and comparisons to Lua tables. Given the ubiquity of their use
746inside the VM, this is not acceptable.
747</p>
748<p>
749There are three viable alternatives, if you really need to use cdata
750objects as keys:
751</p>
752<ul>
753
754<li>If you can get by with the precision of Lua numbers
755(52&nbsp;bits), then use <tt>tonumber()</tt> on a cdata number or
756combine multiple fields of a cdata aggregate to a Lua number. Then use
757the resulting Lua number as a key when indexing tables.<br>
758One obvious benefit: <tt>t[tonumber(2LL)]</tt> <b>does</b> point to
759the same slot as <tt>t[2]</tt>.</li>
760
761<li>Otherwise use either <tt>tostring()</tt> on 64&nbsp;bit integers
762or complex numbers or combine multiple fields of a cdata aggregate to
763a Lua string (e.g. with
764<a href="ext_ffi_api.html#ffi_string"><tt>ffi.string()</tt></a>). Then
765use the resulting Lua string as a key when indexing tables.</li>
766
767<li>Create your own specialized hash table implementation using the
768C&nbsp;types provided by the FFI library, just like you would in
769C&nbsp;code. Ultimately this may give much better performance than the
770other alternatives or what a generic by-value hash table could
771possibly provide.</li>
772
773</ul>
774
775<h2 id="gc">Garbage Collection of cdata Objects</h2>
776<p>
777All explicitly (<tt>ffi.new()</tt>, <tt>ffi.cast()</tt> etc.) or
778implicitly (accessors) created cdata objects are garbage collected.
779You need to ensure to retain valid references to cdata objects
780somewhere on a Lua stack, an upvalue or in a Lua table while they are
781still in use. Once the last reference to a cdata object is gone, the
782garbage collector will automatically free the memory used by it (at
783the end of the next GC cycle).
784</p>
785<p>
786Please note that pointers themselves are cdata objects, however they
787are <b>not</b> followed by the garbage collector. So e.g. if you
788assign a cdata array to a pointer, you must keep the cdata object
789holding the array alive as long as the pointer is still in use:
790</p>
791<pre class="code">
792ffi.cdef[[
793typedef struct { int *a; } foo_t;
794]]
795
796local s = ffi.new("foo_t", ffi.new("int[10]")) -- <span style="color:#c00000;">WRONG!</span>
797
798local a = ffi.new("int[10]") -- <span style="color:#00a000;">OK</span>
799local s = ffi.new("foo_t", a)
800-- Now do something with 's', but keep 'a' alive until you're done.
801</pre>
802<p>
803Similar rules apply for Lua strings which are implicitly converted to
804<tt>"const&nbsp;char&nbsp;*"</tt>: the string object itself must be
805referenced somewhere or it'll be garbage collected eventually. The
806pointer will then point to stale data, which may have already been
807overwritten. Note that <em>string literals</em> are automatically kept
808alive as long as the function containing it (actually its prototype)
809is not garbage collected.
810</p>
811<p>
812Objects which are passed as an argument to an external C&nbsp;function
813are kept alive until the call returns. So it's generally safe to
814create temporary cdata objects in argument lists. This is a common
815idiom for <a href="#convert_vararg">passing specific C&nbsp;types to
816vararg functions</a>.
817</p>
818<p>
819Memory areas returned by C functions (e.g. from <tt>malloc()</tt>)
820must be manually managed, of course (or use
821<a href="ext_ffi_api.html#ffi_gc"><tt>ffi.gc()</tt></a>). Pointers to
822cdata objects are indistinguishable from pointers returned by C
823functions (which is one of the reasons why the GC cannot follow them).
824</p>
825
826<h2 id="callback">Callbacks</h2>
827<p>
828The LuaJIT FFI automatically generates special callback functions
829whenever a Lua function is converted to a C&nbsp;function pointer. This
830associates the generated callback function pointer with the C&nbsp;type
831of the function pointer and the Lua function object (closure).
832</p>
833<p>
834This can happen implicitly due to the usual conversions, e.g. when
835passing a Lua function to a function pointer argument. Or you can use
836<tt>ffi.cast()</tt> to explicitly cast a Lua function to a
837C&nbsp;function pointer.
838</p>
839<p>
840Currently only certain C&nbsp;function types can be used as callback
841functions. Neither C&nbsp;vararg functions nor functions with
842pass-by-value aggregate argument or result types are supported. There
843are no restrictions for the kind of Lua functions that can be called
844from the callback &mdash; no checks for the proper number of arguments
845are made. The return value of the Lua function will be converted to the
846result type and an error will be thrown for invalid conversions.
847</p>
848<p>
849It's allowed to throw errors across a callback invocation, but it's not
850advisable in general. Do this only if you know the C&nbsp;function, that
851called the callback, copes with the forced stack unwinding and doesn't
852leak resources.
853</p>
854
855<h3 id="callback_resources">Callback resource handling</h3>
856<p>
857Callbacks take up resources &mdash; you can only have a limited number
858of them at the same time (500&nbsp;-&nbsp;1000, depending on the
859architecture). The associated Lua functions are anchored to prevent
860garbage collection, too.
861</p>
862<p>
863<b>Callbacks due to implicit conversions are permanent!</b> There is no
864way to guess their lifetime, since the C&nbsp;side might store the
865function pointer for later use (typical for GUI toolkits). The associated
866resources cannot be reclaimed until termination:
867</p>
868<pre class="code">
869ffi.cdef[[
870typedef int (__stdcall *WNDENUMPROC)(void *hwnd, intptr_t l);
871int EnumWindows(WNDENUMPROC func, intptr_t l);
872]]
873
874-- Implicit conversion to a callback via function pointer argument.
875local count = 0
876ffi.C.EnumWindows(function(hwnd, l)
877 count = count + 1
878 return true
879end, 0)
880-- The callback is permanent and its resources cannot be reclaimed!
881-- Ok, so this may not be a problem, if you do this only once.
882</pre>
883<p>
884Note: this example shows that you <em>must</em> properly declare
885<tt>__stdcall</tt> callbacks on Windows/x86 systems. The calling
886convention cannot be automatically detected, unlike for
887<tt>__stdcall</tt> calls <em>to</em> Windows functions.
888</p>
889<p>
890For some use cases it's necessary to free up the resources or to
891dynamically redirect callbacks. Use an explicit cast to a
892C&nbsp;function pointer and keep the resulting cdata object. Then use
893the <a href="ext_ffi_api.html#callback_free"><tt>cb:free()</tt></a>
894or <a href="ext_ffi_api.html#callback_set"><tt>cb:set()</tt></a> methods
895on the cdata object:
896</p>
897<pre class="code">
898-- Explicitly convert to a callback via cast.
899local count = 0
900local cb = ffi.cast("WNDENUMPROC", function(hwnd, l)
901 count = count + 1
902 return true
903end)
904
905-- Pass it to a C function.
906ffi.C.EnumWindows(cb, 0)
907-- EnumWindows doesn't need the callback after it returns, so free it.
908
909cb:free()
910-- The callback function pointer is no longer valid and its resources
911-- will be reclaimed. The created Lua closure will be garbage collected.
912</pre>
913
914<h3 id="callback_performance">Callback performance</h3>
915<p>
916<b>Callbacks are slow!</b> First, the C&nbsp;to Lua transition itself
917has an unavoidable cost, similar to a <tt>lua_call()</tt> or
918<tt>lua_pcall()</tt>. Argument and result marshalling add to that cost.
919And finally, neither the C&nbsp;compiler nor LuaJIT can inline or
920optimize across the language barrier and hoist repeated computations out
921of a callback function.
922</p>
923<p>
924Do not use callbacks for performance-sensitive work: e.g. consider a
925numerical integration routine which takes a user-defined function to
926integrate over. It's a bad idea to call a user-defined Lua function from
927C&nbsp;code millions of times. The callback overhead will be absolutely
928detrimental for performance.
929</p>
930<p>
931It's considerably faster to write the numerical integration routine
932itself in Lua &mdash; the JIT compiler will be able to inline the
933user-defined function and optimize it together with its calling context,
934with very competitive performance.
935</p>
936<p>
937As a general guideline: <b>use callbacks only when you must</b>, because
938of existing C&nbsp;APIs. E.g. callback performance is irrelevant for a
939GUI application, which waits for user input most of the time, anyway.
940</p>
941<p>
942For new designs <b>avoid push-style APIs</b> (C&nbsp;function repeatedly
943calling a callback for each result). Instead <b>use pull-style APIs</b>
944(call a C&nbsp;function repeatedly to get a new result). Calls from Lua
945to C via the FFI are much faster than the other way round. Most well-designed
946libraries already use pull-style APIs (read/write, get/put).
947</p>
948
949<h2 id="clib">C Library Namespaces</h2>
950<p>
951A C&nbsp;library namespace is a special kind of object which allows
952access to the symbols contained in shared libraries or the default
953symbol namespace. The default
954<a href="ext_ffi_api.html#ffi_C"><tt>ffi.C</tt></a> namespace is
955automatically created when the FFI library is loaded. C&nbsp;library
956namespaces for specific shared libraries may be created with the
957<a href="ext_ffi_api.html#ffi_load"><tt>ffi.load()</tt></a> API
958function.
959</p>
960<p>
961Indexing a C&nbsp;library namespace object with a symbol name (a Lua
962string) automatically binds it to the library. First the symbol type
963is resolved &mdash; it must have been declared with
964<a href="ext_ffi_api.html#ffi_cdef"><tt>ffi.cdef</tt></a>. Then the
965symbol address is resolved by searching for the symbol name in the
966associated shared libraries or the default symbol namespace. Finally,
967the resulting binding between the symbol name, the symbol type and its
968address is cached. Missing symbol declarations or nonexistent symbol
969names cause an error.
970</p>
971<p>
972This is what happens on a <b>read access</b> for the different kinds of
973symbols:
974</p>
975<ul>
976
977<li>External functions: a cdata object with the type of the function
978and its address is returned.</li>
979
980<li>External variables: the symbol address is dereferenced and the
981loaded value is <a href="#convert_tolua">converted to a Lua object</a>
982and returned.</li>
983
984<li>Constant values (<tt>static&nbsp;const</tt> or <tt>enum</tt>
985constants): the constant is <a href="#convert_tolua">converted to a
986Lua object</a> and returned.</li>
987
988</ul>
989<p>
990This is what happens on a <b>write access</b>:
991</p>
992<ul>
993
994<li>External variables: the value to be written is
995<a href="#convert_fromlua">converted to the C&nbsp;type</a> of the
996variable and then stored at the symbol address.</li>
997
998<li>Writing to constant variables or to any other symbol type causes
999an error, like any other attempted write to a constant location.</li>
1000
1001</ul>
1002<p>
1003C&nbsp;library namespaces themselves are garbage collected objects. If
1004the last reference to the namespace object is gone, the garbage
1005collector will eventually release the shared library reference and
1006remove all memory associated with the namespace. Since this may
1007trigger the removal of the shared library from the memory of the
1008running process, it's generally <em>not safe</em> to use function
1009cdata objects obtained from a library if the namespace object may be
1010unreferenced.
1011</p>
1012<p>
1013Performance notice: the JIT compiler specializes to the identity of
1014namespace objects and to the strings used to index it. This
1015effectively turns function cdata objects into constants. It's not
1016useful and actually counter-productive to explicitly cache these
1017function objects, e.g. <tt>local strlen = ffi.C.strlen</tt>. OTOH it
1018<em>is</em> useful to cache the namespace itself, e.g. <tt>local C =
1019ffi.C</tt>.
1020</p>
1021
1022<h2 id="policy">No Hand-holding!</h2>
1023<p>
1024The FFI library has been designed as <b>a low-level library</b>. The
1025goal is to interface with C&nbsp;code and C&nbsp;data types with a
1026minimum of overhead. This means <b>you can do anything you can do
1027from&nbsp;C</b>: access all memory, overwrite anything in memory, call
1028machine code at any memory address and so on.
1029</p>
1030<p>
1031The FFI library provides <b>no memory safety</b>, unlike regular Lua
1032code. It will happily allow you to dereference a <tt>NULL</tt>
1033pointer, to access arrays out of bounds or to misdeclare
1034C&nbsp;functions. If you make a mistake, your application might crash,
1035just like equivalent C&nbsp;code would.
1036</p>
1037<p>
1038This behavior is inevitable, since the goal is to provide full
1039interoperability with C&nbsp;code. Adding extra safety measures, like
1040bounds checks, would be futile. There's no way to detect
1041misdeclarations of C&nbsp;functions, since shared libraries only
1042provide symbol names, but no type information. Likewise there's no way
1043to infer the valid range of indexes for a returned pointer.
1044</p>
1045<p>
1046Again: the FFI library is a low-level library. This implies it needs
1047to be used with care, but it's flexibility and performance often
1048outweigh this concern. If you're a C or C++ developer, it'll be easy
1049to apply your existing knowledge. OTOH writing code for the FFI
1050library is not for the faint of heart and probably shouldn't be the
1051first exercise for someone with little experience in Lua, C or C++.
1052</p>
1053<p>
1054As a corollary of the above, the FFI library is <b>not safe for use by
1055untrusted Lua code</b>. If you're sandboxing untrusted Lua code, you
1056definitely don't want to give this code access to the FFI library or
1057to <em>any</em> cdata object (except 64&nbsp;bit integers or complex
1058numbers). Any properly engineered Lua sandbox needs to provide safety
1059wrappers for many of the standard Lua library functions &mdash;
1060similar wrappers need to be written for high-level operations on FFI
1061data types, too.
1062</p>
1063
1064<h2 id="status">Current Status</h2>
1065<p>
1066The initial release of the FFI library has some limitations and is
1067missing some features. Most of these will be fixed in future releases.
1068</p>
1069<p>
1070<a href="#clang">C language support</a> is
1071currently incomplete:
1072</p>
1073<ul>
1074<li>C&nbsp;declarations are not passed through a C&nbsp;pre-processor,
1075yet.</li>
1076<li>The C&nbsp;parser is able to evaluate most constant expressions
1077commonly found in C&nbsp;header files. However it doesn't handle the
1078full range of C&nbsp;expression semantics and may fail for some
1079obscure constructs.</li>
1080<li><tt>static const</tt> declarations only work for integer types
1081up to 32&nbsp;bits. Neither declaring string constants nor
1082floating-point constants is supported.</li>
1083<li>Packed <tt>struct</tt> bitfields that cross container boundaries
1084are not implemented.</li>
1085<li>Native vector types may be defined with the GCC <tt>mode</tt> or
1086<tt>vector_size</tt> attribute. But no operations other than loading,
1087storing and initializing them are supported, yet.</li>
1088<li>The <tt>volatile</tt> type qualifier is currently ignored by
1089compiled code.</li>
1090<li><a href="ext_ffi_api.html#ffi_cdef"><tt>ffi.cdef</tt></a> silently
1091ignores all re-declarations.</li>
1092</ul>
1093<p>
1094The JIT compiler already handles a large subset of all FFI operations.
1095It automatically falls back to the interpreter for unimplemented
1096operations (you can check for this with the
1097<a href="running.html#opt_j"><tt>-jv</tt></a> command line option).
1098The following operations are currently not compiled and may exhibit
1099suboptimal performance, especially when used in inner loops:
1100</p>
1101<ul>
1102<li>Array/<tt>struct</tt> copies and bulk initializations.</li>
1103<li>Bitfield accesses and initializations.</li>
1104<li>Vector operations.</li>
1105<li>Table initializers.</li>
1106<li>Initialization of nested <tt>struct</tt>/<tt>union</tt> types.</li>
1107<li>Allocations of variable-length arrays or structs.</li>
1108<li>Allocations of C&nbsp;types with a size &gt; 64&nbsp;bytes or an
1109alignment &gt; 8&nbsp;bytes.</li>
1110<li>Conversions from lightuserdata to <tt>void&nbsp;*</tt>.</li>
1111<li>Pointer differences for element sizes that are not a power of
1112two.</li>
1113<li>Calls to C&nbsp;functions with aggregates passed or returned by
1114value.</li>
1115<li>Calls to ctype metamethods which are not plain functions.</li>
1116<li>ctype <tt>__newindex</tt> tables and non-string lookups in ctype
1117<tt>__index</tt> tables.</li>
1118<li><tt>tostring()</tt> for cdata types.</li>
1119<li>Calls to the following <a href="ext_ffi_api.html">ffi.* API</a>
1120functions: <tt>cdef</tt>, <tt>load</tt>, <tt>typeof</tt>,
1121<tt>metatype</tt>, <tt>gc</tt>, <tt>sizeof</tt>, <tt>alignof</tt>,
1122<tt>offsetof</tt>.</li>
1123</ul>
1124<p>
1125Other missing features:
1126</p>
1127<ul>
1128<li>Bit operations for 64&nbsp;bit types.</li>
1129<li>Arithmetic for <tt>complex</tt> numbers.</li>
1130<li>Passing structs by value to vararg C&nbsp;functions.</li>
1131<li><a href="extensions.html#exceptions">C++ exception interoperability</a>
1132does not extend to C&nbsp;functions called via the FFI, if the call is
1133compiled.</li>
1134</ul>
1135<br class="flush">
1136</div>
1137<div id="foot">
1138<hr class="hide">
1139Copyright &copy; 2005-2011 Mike Pall
1140<span class="noprint">
1141&middot;
1142<a href="contact.html">Contact</a>
1143</span>
1144</div>
1145</body>
1146</html>
diff --git a/libraries/luajit-2.0/doc/ext_ffi_tutorial.html b/libraries/luajit-2.0/doc/ext_ffi_tutorial.html
new file mode 100644
index 0000000..fb46a84
--- /dev/null
+++ b/libraries/luajit-2.0/doc/ext_ffi_tutorial.html
@@ -0,0 +1,598 @@
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 Tutorial</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<style type="text/css">
12span.codemark { position:absolute; left: 16em; color: #4040c0; }
13span.mark { color: #4040c0; font-family: Courier New, Courier, monospace;
14 line-height: 1.1; }
15pre.mark { padding-left: 2em; }
16table.idiomtable { line-height: 1.2; }
17table.idiomtable tt { font-size: 100%; }
18table.idiomtable td { vertical-align: top; }
19tr.idiomhead td { font-weight: bold; }
20td.idiomc { width: 12em; }
21td.idiomlua { width: 14em; }
22td.idiomlua b { font-weight: normal; color: #2142bf; }
23</style>
24</head>
25<body>
26<div id="site">
27<a href="http://luajit.org"><span>Lua<span id="logo">JIT</span></span></a>
28</div>
29<div id="head">
30<h1>FFI Tutorial</h1>
31</div>
32<div id="nav">
33<ul><li>
34<a href="luajit.html">LuaJIT</a>
35<ul><li>
36<a href="install.html">Installation</a>
37</li><li>
38<a href="running.html">Running</a>
39</li></ul>
40</li><li>
41<a href="extensions.html">Extensions</a>
42<ul><li>
43<a href="ext_ffi.html">FFI Library</a>
44<ul><li>
45<a class="current" href="ext_ffi_tutorial.html">FFI Tutorial</a>
46</li><li>
47<a href="ext_ffi_api.html">ffi.* API</a>
48</li><li>
49<a href="ext_ffi_semantics.html">FFI Semantics</a>
50</li></ul>
51</li><li>
52<a href="ext_jit.html">jit.* Library</a>
53</li><li>
54<a href="ext_c_api.html">Lua/C API</a>
55</li></ul>
56</li><li>
57<a href="status.html">Status</a>
58<ul><li>
59<a href="changes.html">Changes</a>
60</li></ul>
61</li><li>
62<a href="faq.html">FAQ</a>
63</li><li>
64<a href="http://luajit.org/performance.html">Performance <span class="ext">&raquo;</span></a>
65</li><li>
66<a href="http://luajit.org/download.html">Download <span class="ext">&raquo;</span></a>
67</li></ul>
68</div>
69<div id="main">
70<p>
71This page is intended to give you an overview of the features of the FFI
72library by presenting a few use cases and guidelines.
73</p>
74<p>
75This page makes no attempt to explain all of the FFI library, though.
76You'll want to have a look at the <a href="ext_ffi_api.html">ffi.* API
77function reference</a> and the <a href="ext_ffi_semantics.html">FFI
78semantics</a> to learn more.
79</p>
80
81<h2 id="load">Loading the FFI Library</h2>
82<p>
83The FFI library is built into LuaJIT by default, but it's not loaded
84and initialized by default. The suggested way to use the FFI library
85is to add the following to the start of every Lua file that needs one
86of its functions:
87</p>
88<pre class="code">
89local ffi = require("ffi")
90</pre>
91<p>
92Please note this doesn't define an <tt>ffi</tt> variable in the table
93of globals &mdash; you really need to use the local variable. The
94<tt>require</tt> function ensures the library is only loaded once.
95</p>
96
97<h2 id="sleep">Accessing Standard System Functions</h2>
98<p>
99The following code explains how to access standard system functions.
100We slowly print two lines of dots by sleeping for 10&nbsp;milliseconds
101after each dot:
102</p>
103<pre class="code mark">
104<span class="codemark">&nbsp;
105&#9312;
106
107
108
109
110
111&#9313;
112&#9314;
113&#9315;
114
115
116
117&#9316;
118
119
120
121
122
123&#9317;</span>local ffi = require("ffi")
124ffi.cdef[[
125<span style="color:#00a000;">void Sleep(int ms);
126int poll(struct pollfd *fds, unsigned long nfds, int timeout);</span>
127]]
128
129local sleep
130if ffi.os == "Windows" then
131 function sleep(s)
132 ffi.C.Sleep(s*1000)
133 end
134else
135 function sleep(s)
136 ffi.C.poll(nil, 0, s*1000)
137 end
138end
139
140for i=1,160 do
141 io.write("."); io.flush()
142 sleep(0.01)
143end
144io.write("\n")
145</pre>
146<p>
147Here's the step-by-step explanation:
148</p>
149<p>
150<span class="mark">&#9312;</span> This defines the
151C&nbsp;library functions we're going to use. The part inside the
152double-brackets (in green) is just standard C&nbsp;syntax. You can
153usually get this info from the C&nbsp;header files or the
154documentation provided by each C&nbsp;library or C&nbsp;compiler.
155</p>
156<p>
157<span class="mark">&#9313;</span> The difficulty we're
158facing here, is that there are different standards to choose from.
159Windows has a simple <tt>Sleep()</tt> function. On other systems there
160are a variety of functions available to achieve sub-second sleeps, but
161with no clear consensus. Thankfully <tt>poll()</tt> can be used for
162this task, too, and it's present on most non-Windows systems. The
163check for <tt>ffi.os</tt> makes sure we use the Windows-specific
164function only on Windows systems.
165</p>
166<p>
167<span class="mark">&#9314;</span> Here we're wrapping the
168call to the C&nbsp;function in a Lua function. This isn't strictly
169necessary, but it's helpful to deal with system-specific issues only
170in one part of the code. The way we're wrapping it ensures the check
171for the OS is only done during initialization and not for every call.
172</p>
173<p>
174<span class="mark">&#9315;</span> A more subtle point is
175that we defined our <tt>sleep()</tt> function (for the sake of this
176example) as taking the number of seconds, but accepting fractional
177seconds. Multiplying this by 1000 gets us milliseconds, but that still
178leaves it a Lua number, which is a floating-point value. Alas, the
179<tt>Sleep()</tt> function only accepts an integer value. Luckily for
180us, the FFI library automatically performs the conversion when calling
181the function (truncating the FP value towards zero, like in C).
182</p>
183<p style="font-size: 8pt;">
184Some readers will notice that <tt>Sleep()</tt> is part of
185<tt>KERNEL32.DLL</tt> and is also a <tt>stdcall</tt> function. So how
186can this possibly work? The FFI library provides the <tt>ffi.C</tt>
187default C&nbsp;library namespace, which allows calling functions from
188the default set of libraries, like a C&nbsp;compiler would. Also, the
189FFI library automatically detects <tt>stdcall</tt> functions, so you
190don't need to declare them as such.
191</p>
192<p>
193<span class="mark">&#9316;</span> The <tt>poll()</tt>
194function takes a couple more arguments we're not going to use. You can
195simply use <tt>nil</tt> to pass a <tt>NULL</tt> pointer and <tt>0</tt>
196for the <tt>nfds</tt> parameter. Please note that the
197number&nbsp;<tt>0</tt> <em>does not convert to a pointer value</em>,
198unlike in C++. You really have to pass pointers to pointer arguments
199and numbers to number arguments.
200</p>
201<p style="font-size: 8pt;">
202The page on <a href="ext_ffi_semantics.html">FFI semantics</a> has all
203of the gory details about
204<a href="ext_ffi_semantics.html#convert">conversions between Lua
205objects and C&nbsp;types</a>. For the most part you don't have to deal
206with this, as it's performed automatically and it's carefully designed
207to bridge the semantic differences between Lua and C.
208</p>
209<p>
210<span class="mark">&#9317;</span> Now that we have defined
211our own <tt>sleep()</tt> function, we can just call it from plain Lua
212code. That wasn't so bad, huh? Turning these boring animated dots into
213a fascinating best-selling game is left as an exercise for the reader.
214:-)
215</p>
216
217<h2 id="zlib">Accessing the zlib Compression Library</h2>
218<p>
219The following code shows how to access the <a
220href="http://zlib.net/">zlib</a> compression library from Lua code.
221We'll define two convenience wrapper functions that take a string and
222compress or uncompress it to another string:
223</p>
224<pre class="code mark">
225<span class="codemark">&nbsp;
226&#9312;
227
228
229
230
231
232
233&#9313;
234
235
236&#9314;
237
238&#9315;
239
240
241&#9316;
242
243
244&#9317;
245
246
247
248
249
250
251
252&#9318;</span>local ffi = require("ffi")
253ffi.cdef[[
254<span style="color:#00a000;">unsigned long compressBound(unsigned long sourceLen);
255int compress2(uint8_t *dest, unsigned long *destLen,
256 const uint8_t *source, unsigned long sourceLen, int level);
257int uncompress(uint8_t *dest, unsigned long *destLen,
258 const uint8_t *source, unsigned long sourceLen);</span>
259]]
260local zlib = ffi.load(ffi.os == "Windows" and "zlib1" or "z")
261
262local function compress(txt)
263 local n = zlib.compressBound(#txt)
264 local buf = ffi.new("uint8_t[?]", n)
265 local buflen = ffi.new("unsigned long[1]", n)
266 local res = zlib.compress2(buf, buflen, txt, #txt, 9)
267 assert(res == 0)
268 return ffi.string(buf, buflen[0])
269end
270
271local function uncompress(comp, n)
272 local buf = ffi.new("uint8_t[?]", n)
273 local buflen = ffi.new("unsigned long[1]", n)
274 local res = zlib.uncompress(buf, buflen, comp, #comp)
275 assert(res == 0)
276 return ffi.string(buf, buflen[0])
277end
278
279-- Simple test code.
280local txt = string.rep("abcd", 1000)
281print("Uncompressed size: ", #txt)
282local c = compress(txt)
283print("Compressed size: ", #c)
284local txt2 = uncompress(c, #txt)
285assert(txt2 == txt)
286</pre>
287<p>
288Here's the step-by-step explanation:
289</p>
290<p>
291<span class="mark">&#9312;</span> This defines some of the
292C&nbsp;functions provided by zlib. For the sake of this example, some
293type indirections have been reduced and it uses the pre-defined
294fixed-size integer types, while still adhering to the zlib API/ABI.
295</p>
296<p>
297<span class="mark">&#9313;</span> This loads the zlib shared
298library. On POSIX systems it's named <tt>libz.so</tt> and usually
299comes pre-installed. Since <tt>ffi.load()</tt> automatically adds any
300missing standard prefixes/suffixes, we can simply load the
301<tt>"z"</tt> library. On Windows it's named <tt>zlib1.dll</tt> and
302you'll have to download it first from the
303<a href="http://zlib.net/"><span class="ext">&raquo;</span>&nbsp;zlib site</a>. The check for
304<tt>ffi.os</tt> makes sure we pass the right name to
305<tt>ffi.load()</tt>.
306</p>
307<p>
308<span class="mark">&#9314;</span> First, the maximum size of
309the compression buffer is obtained by calling the
310<tt>zlib.compressBound</tt> function with the length of the
311uncompressed string. The next line allocates a byte buffer of this
312size. The <tt>[?]</tt> in the type specification indicates a
313variable-length array (VLA). The actual number of elements of this
314array is given as the 2nd argument to <tt>ffi.new()</tt>.
315</p>
316<p>
317<span class="mark">&#9315;</span> This may look strange at
318first, but have a look at the declaration of the <tt>compress2</tt>
319function from zlib: the destination length is defined as a pointer!
320This is because you pass in the maximum buffer size and get back the
321actual length that was used.
322</p>
323<p>
324In C you'd pass in the address of a local variable
325(<tt>&amp;buflen</tt>). But since there's no address-of operator in
326Lua, we'll just pass in a one-element array. Conveniently it can be
327initialized with the maximum buffer size in one step. Calling the
328actual <tt>zlib.compress2</tt> function is then straightforward.
329</p>
330<p>
331<span class="mark">&#9316;</span> We want to return the
332compressed data as a Lua string, so we'll use <tt>ffi.string()</tt>.
333It needs a pointer to the start of the data and the actual length. The
334length has been returned in the <tt>buflen</tt> array, so we'll just
335get it from there.
336</p>
337<p style="font-size: 8pt;">
338Note that since the function returns now, the <tt>buf</tt> and
339<tt>buflen</tt> variables will eventually be garbage collected. This
340is fine, because <tt>ffi.string()</tt> has copied the contents to a
341newly created (interned) Lua string. If you plan to call this function
342lots of times, consider reusing the buffers and/or handing back the
343results in buffers instead of strings. This will reduce the overhead
344for garbage collection and string interning.
345</p>
346<p>
347<span class="mark">&#9317;</span> The <tt>uncompress</tt>
348functions does the exact opposite of the <tt>compress</tt> function.
349The compressed data doesn't include the size of the original string,
350so this needs to be passed in. Otherwise no surprises here.
351</p>
352<p>
353<span class="mark">&#9318;</span> The code, that makes use
354of the functions we just defined, is just plain Lua code. It doesn't
355need to know anything about the LuaJIT FFI &mdash; the convenience
356wrapper functions completely hide it.
357</p>
358<p>
359One major advantage of the LuaJIT FFI is that you are now able to
360write those wrappers <em>in Lua</em>. And at a fraction of the time it
361would cost you to create an extra C&nbsp;module using the Lua/C API.
362Many of the simpler C&nbsp;functions can probably be used directly
363from your Lua code, without any wrappers.
364</p>
365<p style="font-size: 8pt;">
366Side note: the zlib API uses the <tt>long</tt> type for passing
367lengths and sizes around. But all those zlib functions actually only
368deal with 32&nbsp;bit values. This is an unfortunate choice for a
369public API, but may be explained by zlib's history &mdash; we'll just
370have to deal with it.
371</p>
372<p style="font-size: 8pt;">
373First, you should know that a <tt>long</tt> is a 64&nbsp;bit type e.g.
374on POSIX/x64 systems, but a 32&nbsp;bit type on Windows/x64 and on
37532&nbsp;bit systems. Thus a <tt>long</tt> result can be either a plain
376Lua number or a boxed 64&nbsp;bit integer cdata object, depending on
377the target system.
378</p>
379<p style="font-size: 8pt;">
380Ok, so the <tt>ffi.*</tt> functions generally accept cdata objects
381wherever you'd want to use a number. That's why we get a away with
382passing <tt>n</tt> to <tt>ffi.string()</tt> above. But other Lua
383library functions or modules don't know how to deal with this. So for
384maximum portability one needs to use <tt>tonumber()</tt> on returned
385<tt>long</tt> results before passing them on. Otherwise the
386application might work on some systems, but would fail in a POSIX/x64
387environment.
388</p>
389
390<h2 id="metatype">Defining Metamethods for a C&nbsp;Type</h2>
391<p>
392The following code explains how to define metamethods for a C type.
393We define a simple point type and add some operations to it:
394</p>
395<pre class="code mark">
396<span class="codemark">&nbsp;
397&#9312;
398
399
400
401&#9313;
402
403&#9314;
404
405&#9315;
406
407
408
409&#9316;
410
411&#9317;</span>local ffi = require("ffi")
412ffi.cdef[[
413<span style="color:#00a000;">typedef struct { double x, y; } point_t;</span>
414]]
415
416local point
417local mt = {
418 __add = function(a, b) return point(a.x+b.x, a.y+b.y) end,
419 __len = function(a) return math.sqrt(a.x*a.x + a.y*a.y) end,
420 __index = {
421 area = function(a) return a.x*a.x + a.y*a.y end,
422 },
423}
424point = ffi.metatype("point_t", mt)
425
426local a = point(3, 4)
427print(a.x, a.y) --> 3 4
428print(#a) --> 5
429print(a:area()) --> 25
430local b = a + point(0.5, 8)
431print(#b) --> 12.5
432</pre>
433<p>
434Here's the step-by-step explanation:
435</p>
436<p>
437<span class="mark">&#9312;</span> This defines the C&nbsp;type for a
438two-dimensional point object.
439</p>
440<p>
441<span class="mark">&#9313;</span> We have to declare the variable
442holding the point constructor first, because it's used inside of a
443metamethod.
444</p>
445<p>
446<span class="mark">&#9314;</span> Let's define an <tt>__add</tt>
447metamethod which adds the coordinates of two points and creates a new
448point object. For simplicity, this function assumes that both arguments
449are points. But it could be any mix of objects, if at least one operand
450is of the required type (e.g. adding a point plus a number or vice
451versa). Our <tt>__len</tt> metamethod returns the distance of a point to
452the origin.
453</p>
454<p>
455<span class="mark">&#9315;</span> If we run out of operators, we can
456define named methods, too. Here the <tt>__index</tt> table defines an
457<tt>area</tt> function. For custom indexing needs, one might want to
458define <tt>__index</tt> and <tt>__newindex</tt> <em>functions</em> instead.
459</p>
460<p>
461<span class="mark">&#9316;</span> This associates the metamethods with
462our C&nbsp;type. This only needs to be done once. For convenience, a
463constructor is returned by
464<a href="ext_ffi_api.html#ffi_metatype"><tt>ffi.metatype()</tt></a>.
465We're not required to use it, though. The original C&nbsp;type can still
466be used e.g. to create an array of points. The metamethods automatically
467apply to any and all uses of this type.
468</p>
469<p>
470Please note that the association with a metatable is permanent and
471<b>the metatable must not be modified afterwards!</b> Ditto for the
472<tt>__index</tt> table.
473</p>
474<p>
475<span class="mark">&#9317;</span> Here are some simple usage examples
476for the point type and their expected results. The pre-defined
477operations (such as <tt>a.x</tt>) can be freely mixed with the newly
478defined metamethods. Note that <tt>area</tt> is a method and must be
479called with the Lua syntax for methods: <tt>a:area()</tt>, not
480<tt>a.area()</tt>.
481</p>
482<p>
483The C&nbsp;type metamethod mechanism is most useful when used in
484conjunction with C&nbsp;libraries that are written in an object-oriented
485style. Creators return a pointer to a new instance and methods take an
486instance pointer as the first argument. Sometimes you can just point
487<tt>__index</tt> to the library namespace and <tt>__gc</tt> to the
488destructor and you're done. But often enough you'll want to add
489convenience wrappers, e.g. to return actual Lua strings or when
490returning multiple values.
491</p>
492<p>
493Some C libraries only declare instance pointers as an opaque
494<tt>void&nbsp;*</tt> type. In this case you can use a fake type for all
495declarations, e.g. a pointer to a named (incomplete) struct will do:
496<tt>typedef struct foo_type *foo_handle</tt>. The C&nbsp;side doesn't
497know what you declare with the LuaJIT FFI, but as long as the underlying
498types are compatible, everything still works.
499</p>
500
501<h2 id="idioms">Translating C&nbsp;Idioms</h2>
502<p>
503Here's a list of common C&nbsp;idioms and their translation to the
504LuaJIT FFI:
505</p>
506<table class="idiomtable">
507<tr class="idiomhead">
508<td class="idiomdesc">Idiom</td>
509<td class="idiomc">C&nbsp;code</td>
510<td class="idiomlua">Lua code</td>
511</tr>
512<tr class="odd separate">
513<td class="idiomdesc">Pointer dereference<br><tt>int *p;</tt></td><td class="idiomc"><tt>x = *p;<br>*p = y;</tt></td><td class="idiomlua"><tt>x = <b>p[0]</b><br><b>p[0]</b> = y</tt></td></tr>
514<tr class="even">
515<td class="idiomdesc">Pointer indexing<br><tt>int i, *p;</tt></td><td class="idiomc"><tt>x = p[i];<br>p[i+1] = y;</tt></td><td class="idiomlua"><tt>x = p[i]<br>p[i+1] = y</tt></td></tr>
516<tr class="odd">
517<td class="idiomdesc">Array indexing<br><tt>int i, a[];</tt></td><td class="idiomc"><tt>x = a[i];<br>a[i+1] = y;</tt></td><td class="idiomlua"><tt>x = a[i]<br>a[i+1] = y</tt></td></tr>
518<tr class="even separate">
519<td class="idiomdesc"><tt>struct</tt>/<tt>union</tt> dereference<br><tt>struct foo s;</tt></td><td class="idiomc"><tt>x = s.field;<br>s.field = y;</tt></td><td class="idiomlua"><tt>x = s.field<br>s.field = y</tt></td></tr>
520<tr class="odd">
521<td class="idiomdesc"><tt>struct</tt>/<tt>union</tt> pointer deref.<br><tt>struct foo *sp;</tt></td><td class="idiomc"><tt>x = sp->field;<br>sp->field = y;</tt></td><td class="idiomlua"><tt>x = <b>s.field</b><br><b>s.field</b> = y</tt></td></tr>
522<tr class="even separate">
523<td class="idiomdesc">Pointer arithmetic<br><tt>int i, *p;</tt></td><td class="idiomc"><tt>x = p + i;<br>y = p - i;</tt></td><td class="idiomlua"><tt>x = p + i<br>y = p - i</tt></td></tr>
524<tr class="odd">
525<td class="idiomdesc">Pointer difference<br><tt>int *p1, *p2;</tt></td><td class="idiomc"><tt>x = p1 - p2;</tt></td><td class="idiomlua"><tt>x = p1 - p2</tt></td></tr>
526<tr class="even">
527<td class="idiomdesc">Array element pointer<br><tt>int i, a[];</tt></td><td class="idiomc"><tt>x = &amp;a[i];</tt></td><td class="idiomlua"><tt>x = <b>a+i</b></tt></td></tr>
528<tr class="odd">
529<td class="idiomdesc">Cast pointer to address<br><tt>int *p;</tt></td><td class="idiomc"><tt>x = (intptr_t)p;</tt></td><td class="idiomlua"><tt>x = <b>tonumber(<br>&nbsp;ffi.cast("intptr_t",<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;p))</b></tt></td></tr>
530<tr class="even separate">
531<td class="idiomdesc">Functions with outargs<br><tt>void foo(int *inoutlen);</tt></td><td class="idiomc"><tt>int len = x;<br>foo(&amp;len);<br>y = len;</tt></td><td class="idiomlua"><tt><b>local len =<br>&nbsp;&nbsp;ffi.new("int[1]", x)<br>foo(len)<br>y = len[0]</b></tt></td></tr>
532<tr class="odd">
533<td class="idiomdesc"><a href="ext_ffi_semantics.html#convert_vararg">Vararg conversions</a><br><tt>int printf(char *fmt, ...);</tt></td><td class="idiomc"><tt>printf("%g", 1.0);<br>printf("%d", 1);<br>&nbsp;</tt></td><td class="idiomlua"><tt>printf("%g", 1);<br>printf("%d",<br>&nbsp;&nbsp;<b>ffi.new("int", 1)</b>)</tt></td></tr>
534</table>
535
536<h2 id="cache">To Cache or Not to Cache</h2>
537<p>
538It's a common Lua idiom to cache library functions in local variables
539or upvalues, e.g.:
540</p>
541<pre class="code">
542local byte, char = string.byte, string.char
543local function foo(x)
544 return char(byte(x)+1)
545end
546</pre>
547<p>
548This replaces several hash-table lookups with a (faster) direct use of
549a local or an upvalue. This is less important with LuaJIT, since the
550JIT compiler optimizes hash-table lookups a lot and is even able to
551hoist most of them out of the inner loops. It can't eliminate
552<em>all</em> of them, though, and it saves some typing for often-used
553functions. So there's still a place for this, even with LuaJIT.
554</p>
555<p>
556The situation is a bit different with C&nbsp;function calls via the
557FFI library. The JIT compiler has special logic to eliminate <em>all
558of the lookup overhead</em> for functions resolved from a
559<a href="ext_ffi_semantics.html#clib">C&nbsp;library namespace</a>!
560Thus it's not helpful and actually counter-productive to cache
561individual C&nbsp;functions like this:
562</p>
563<pre class="code">
564local <b>funca</b>, <b>funcb</b> = ffi.C.funcb, ffi.C.funcb -- <span style="color:#c00000;">Not helpful!</span>
565local function foo(x, n)
566 for i=1,n do <b>funcb</b>(<b>funca</b>(x, i), 1) end
567end
568</pre>
569<p>
570This turns them into indirect calls and generates bigger and slower
571machine code. Instead you'll want to cache the namespace itself and
572rely on the JIT compiler to eliminate the lookups:
573</p>
574<pre class="code">
575local <b>C</b> = ffi.C -- <span style="color:#00a000;">Instead use this!</span>
576local function foo(x, n)
577 for i=1,n do <b>C.funcb</b>(<b>C.funca</b>(x, i), 1) end
578end
579</pre>
580<p>
581This generates both shorter and faster code. So <b>don't cache
582C&nbsp;functions</b>, but <b>do</b> cache namespaces! Most often the
583namespace is already in a local variable at an outer scope, e.g. from
584<tt>local&nbsp;lib&nbsp;=&nbsp;ffi.load(...)</tt>. Note that copying
585it to a local variable in the function scope is unnecessary.
586</p>
587<br class="flush">
588</div>
589<div id="foot">
590<hr class="hide">
591Copyright &copy; 2005-2011 Mike Pall
592<span class="noprint">
593&middot;
594<a href="contact.html">Contact</a>
595</span>
596</div>
597</body>
598</html>
diff --git a/libraries/luajit-2.0/doc/ext_jit.html b/libraries/luajit-2.0/doc/ext_jit.html
new file mode 100644
index 0000000..e8f5518
--- /dev/null
+++ b/libraries/luajit-2.0/doc/ext_jit.html
@@ -0,0 +1,195 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
2<html>
3<head>
4<title>jit.* Library</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><tt>jit.*</tt> Library</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_semantics.html">FFI Semantics</a>
37</li></ul>
38</li><li>
39<a class="current" href="ext_jit.html">jit.* Library</a>
40</li><li>
41<a href="ext_c_api.html">Lua/C API</a>
42</li></ul>
43</li><li>
44<a href="status.html">Status</a>
45<ul><li>
46<a href="changes.html">Changes</a>
47</li></ul>
48</li><li>
49<a href="faq.html">FAQ</a>
50</li><li>
51<a href="http://luajit.org/performance.html">Performance <span class="ext">&raquo;</span></a>
52</li><li>
53<a href="http://luajit.org/download.html">Download <span class="ext">&raquo;</span></a>
54</li></ul>
55</div>
56<div id="main">
57<p>
58The functions in this built-in module control the behavior of the JIT
59compiler engine. Note that JIT-compilation is fully automatic &mdash;
60you probably won't need to use any of the following functions unless
61you have special needs.
62</p>
63
64<h3 id="jit_onoff"><tt>jit.on()<br>
65jit.off()</tt></h3>
66<p>
67Turns the whole JIT compiler on (default) or off.
68</p>
69<p>
70These functions are typically used with the command line options
71<tt>-j on</tt> or <tt>-j off</tt>.
72</p>
73
74<h3 id="jit_flush"><tt>jit.flush()</tt></h3>
75<p>
76Flushes the whole cache of compiled code.
77</p>
78
79<h3 id="jit_onoff_func"><tt>jit.on(func|true [,true|false])<br>
80jit.off(func|true [,true|false])<br>
81jit.flush(func|true [,true|false])</tt></h3>
82<p>
83<tt>jit.on</tt> enables JIT compilation for a Lua function (this is
84the default).
85</p>
86<p>
87<tt>jit.off</tt> disables JIT compilation for a Lua function and
88flushes any already compiled code from the code cache.
89</p>
90<p>
91<tt>jit.flush</tt> flushes the code, but doesn't affect the
92enable/disable status.
93</p>
94<p>
95The current function, i.e. the Lua function calling this library
96function, can also be specified by passing <tt>true</tt> as the first
97argument.
98</p>
99<p>
100If the second argument is <tt>true</tt>, JIT compilation is also
101enabled, disabled or flushed recursively for all sub-functions of a
102function. With <tt>false</tt> only the sub-functions are affected.
103</p>
104<p>
105The <tt>jit.on</tt> and <tt>jit.off</tt> functions only set a flag
106which is checked when the function is about to be compiled. They do
107not trigger immediate compilation.
108</p>
109<p>
110Typical usage is <tt>jit.off(true, true)</tt> in the main chunk
111of a module to turn off JIT compilation for the whole module for
112debugging purposes.
113</p>
114
115<h3 id="jit_flush_tr"><tt>jit.flush(tr)</tt></h3>
116<p>
117Flushes the root trace, specified by its number, and all of its side
118traces from the cache. The code for the trace will be retained as long
119as there are any other traces which link to it.
120</p>
121
122<h3 id="jit_status"><tt>status, ... = jit.status()</tt></h3>
123<p>
124Returns the current status of the JIT compiler. The first result is
125either <tt>true</tt> or <tt>false</tt> if the JIT compiler is turned
126on or off. The remaining results are strings for CPU-specific features
127and enabled optimizations.
128</p>
129
130<h3 id="jit_version"><tt>jit.version</tt></h3>
131<p>
132Contains the LuaJIT version string.
133</p>
134
135<h3 id="jit_version_num"><tt>jit.version_num</tt></h3>
136<p>
137Contains the version number of the LuaJIT core. Version xx.yy.zz
138is represented by the decimal number xxyyzz.
139</p>
140
141<h3 id="jit_os"><tt>jit.os</tt></h3>
142<p>
143Contains the target OS name:
144"Windows", "Linux", "OSX", "BSD", "POSIX" or "Other".
145</p>
146
147<h3 id="jit_arch"><tt>jit.arch</tt></h3>
148<p>
149Contains the target architecture name:
150"x86", "x64" or "ppcspe".
151</p>
152
153<h2 id="jit_opt"><tt>jit.opt.*</tt> &mdash; JIT compiler optimization control</h2>
154<p>
155This sub-module provides the backend for the <tt>-O</tt> command line
156option.
157</p>
158<p>
159You can also use it programmatically, e.g.:
160</p>
161<pre class="code">
162jit.opt.start(2) -- same as -O2
163jit.opt.start("-dce")
164jit.opt.start("hotloop=10", "hotexit=2")
165</pre>
166<p>
167Unlike in LuaJIT 1.x, the module is built-in and
168<b>optimization is turned on by default!</b>
169It's no longer necessary to run <tt>require("jit.opt").start()</tt>,
170which was one of the ways to enable optimization.
171</p>
172
173<h2 id="jit_util"><tt>jit.util.*</tt> &mdash; JIT compiler introspection</h2>
174<p>
175This sub-module holds functions to introspect the bytecode, generated
176traces, the IR and the generated machine code. The functionality
177provided by this module is still in flux and therefore undocumented.
178</p>
179<p>
180The debug modules <tt>-jbc</tt>, <tt>-jv</tt> and <tt>-jdump</tt> make
181extensive use of these functions. Please check out their source code,
182if you want to know more.
183</p>
184<br class="flush">
185</div>
186<div id="foot">
187<hr class="hide">
188Copyright &copy; 2005-2011 Mike Pall
189<span class="noprint">
190&middot;
191<a href="contact.html">Contact</a>
192</span>
193</div>
194</body>
195</html>
diff --git a/libraries/luajit-2.0/doc/extensions.html b/libraries/luajit-2.0/doc/extensions.html
new file mode 100644
index 0000000..b0e1164
--- /dev/null
+++ b/libraries/luajit-2.0/doc/extensions.html
@@ -0,0 +1,336 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
2<html>
3<head>
4<title>Extensions</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<style type="text/css">
12table.exc {
13 line-height: 1.2;
14}
15tr.exchead td {
16 font-weight: bold;
17}
18td.excplatform {
19 width: 48%;
20}
21td.exccompiler {
22 width: 29%;
23}
24td.excinterop {
25 width: 23%;
26}
27</style>
28</head>
29<body>
30<div id="site">
31<a href="http://luajit.org"><span>Lua<span id="logo">JIT</span></span></a>
32</div>
33<div id="head">
34<h1>Extensions</h1>
35</div>
36<div id="nav">
37<ul><li>
38<a href="luajit.html">LuaJIT</a>
39<ul><li>
40<a href="install.html">Installation</a>
41</li><li>
42<a href="running.html">Running</a>
43</li></ul>
44</li><li>
45<a class="current" href="extensions.html">Extensions</a>
46<ul><li>
47<a href="ext_ffi.html">FFI Library</a>
48<ul><li>
49<a href="ext_ffi_tutorial.html">FFI Tutorial</a>
50</li><li>
51<a href="ext_ffi_api.html">ffi.* API</a>
52</li><li>
53<a href="ext_ffi_semantics.html">FFI Semantics</a>
54</li></ul>
55</li><li>
56<a href="ext_jit.html">jit.* Library</a>
57</li><li>
58<a href="ext_c_api.html">Lua/C API</a>
59</li></ul>
60</li><li>
61<a href="status.html">Status</a>
62<ul><li>
63<a href="changes.html">Changes</a>
64</li></ul>
65</li><li>
66<a href="faq.html">FAQ</a>
67</li><li>
68<a href="http://luajit.org/performance.html">Performance <span class="ext">&raquo;</span></a>
69</li><li>
70<a href="http://luajit.org/download.html">Download <span class="ext">&raquo;</span></a>
71</li></ul>
72</div>
73<div id="main">
74<p>
75LuaJIT is fully upwards-compatible with Lua 5.1. It supports all
76<a href="http://www.lua.org/manual/5.1/manual.html#5"><span class="ext">&raquo;</span>&nbsp;standard Lua
77library functions</a> and the full set of
78<a href="http://www.lua.org/manual/5.1/manual.html#3"><span class="ext">&raquo;</span>&nbsp;Lua/C API
79functions</a>.
80</p>
81<p>
82LuaJIT is also fully ABI-compatible to Lua 5.1 at the linker/dynamic
83loader level. This means you can compile a C&nbsp;module against the
84standard Lua headers and load the same shared library from either Lua
85or LuaJIT.
86</p>
87<p>
88LuaJIT extends the standard Lua VM with new functionality and adds
89several extension modules. Please note that this page is only about
90<em>functional</em> enhancements and not about performance enhancements,
91such as the optimized VM, the faster interpreter or the JIT compiler.
92</p>
93
94<h2 id="modules">Extensions Modules</h2>
95<p>
96LuaJIT comes with several built-in extension modules:
97</p>
98
99<h3 id="bit"><tt>bit.*</tt> &mdash; Bitwise operations</h3>
100<p>
101LuaJIT supports all bitwise operations as defined by
102<a href="http://bitop.luajit.org"><span class="ext">&raquo;</span>&nbsp;Lua BitOp</a>:
103</p>
104<pre class="code">
105bit.tobit bit.tohex bit.bnot bit.band bit.bor bit.bxor
106bit.lshift bit.rshift bit.arshift bit.rol bit.ror bit.bswap
107</pre>
108<p>
109This module is a LuaJIT built-in &mdash; you don't need to download or
110install Lua BitOp. The Lua BitOp site has full documentation for all
111<a href="http://bitop.luajit.org/api.html"><span class="ext">&raquo;</span>&nbsp;Lua BitOp API functions</a>.
112</p>
113<p>
114Please make sure to <tt>require</tt> the module before using any of
115its functions:
116</p>
117<pre class="code">
118local bit = require("bit")
119</pre>
120<p>
121An already installed Lua BitOp module is ignored by LuaJIT.
122This way you can use bit operations from both Lua and LuaJIT on a
123shared installation.
124</p>
125
126<h3 id="ffi"><tt>ffi.*</tt> &mdash; FFI library</h3>
127<p>
128The <a href="ext_ffi.html">FFI library</a> allows calling external
129C&nbsp;functions and the use of C&nbsp;data structures from pure Lua
130code.
131</p>
132
133<h3 id="jit"><tt>jit.*</tt> &mdash; JIT compiler control</h3>
134<p>
135The functions in this module
136<a href="ext_jit.html">control the behavior of the JIT compiler engine</a>.
137</p>
138
139<h3 id="c_api">C API extensions</h3>
140<p>
141LuaJIT adds some
142<a href="ext_c_api.html">extra functions to the Lua/C API</a>.
143</p>
144
145<h2 id="library">Enhanced Standard Library Functions</h2>
146
147<h3 id="xpcall"><tt>xpcall(f, err [,args...])</tt> passes arguments</h3>
148<p>
149Unlike the standard implementation in Lua 5.1, <tt>xpcall()</tt>
150passes any arguments after the error function to the function
151which is called in a protected context.
152</p>
153
154<h3 id="load"><tt>loadfile()</tt> etc. handle UTF-8 source code</h3>
155<p>
156Non-ASCII characters are handled transparently by the Lua source code parser.
157This allows the use of UTF-8 characters in identifiers and strings.
158A UTF-8 BOM is skipped at the start of the source code.
159</p>
160
161<h3 id="tostring"><tt>tostring()</tt> etc. canonicalize NaN and &plusmn;Inf</h3>
162<p>
163All number-to-string conversions consistently convert non-finite numbers
164to the same strings on all platforms. NaN results in <tt>"nan"</tt>,
165positive infinity results in <tt>"inf"</tt> and negative infinity results
166in <tt>"-inf"</tt>.
167</p>
168
169<h3 id="string_dump"><tt>string.dump(f [,strip])</tt> generates portable bytecode</h3>
170<p>
171An extra argument has been added to <tt>string.dump()</tt>. If set to
172<tt>true</tt>, 'stripped' bytecode without debug information is
173generated. This speeds up later bytecode loading and reduces memory
174usage. See also the
175<a href="running.html#opt_b"><tt>-b</tt> command line option</a>.
176</p>
177<p>
178The generated bytecode is portable and can be loaded on any architecture
179that LuaJIT supports, independent of word size or endianess. However the
180bytecode compatibility versions must match. Bytecode stays compatible
181for dot releases (x.y.0 &rarr; x.y.1), but may change with major or
182minor releases (2.0 &rarr; 2.1) or between any beta release. Foreign
183bytecode (e.g. from Lua 5.1) is incompatible and cannot be loaded.
184</p>
185
186<h3 id="math_random">Enhanced PRNG for <tt>math.random()</tt></h3>
187<p>
188LuaJIT uses a Tausworthe PRNG with period 2^223 to implement
189<tt>math.random()</tt> and <tt>math.randomseed()</tt>. The quality of
190the PRNG results is much superior compared to the standard Lua
191implementation which uses the platform-specific ANSI rand().
192</p>
193<p>
194The PRNG generates the same sequences from the same seeds on all
195platforms and makes use of all bits in the seed argument.
196<tt>math.random()</tt> without arguments generates 52 pseudo-random bits
197for every call. The result is uniformly distributed between 0 and 1.
198It's correctly scaled up and rounded for <tt>math.random(n&nbsp;[,m])</tt> to
199preserve uniformity.
200</p>
201
202<h3 id="io"><tt>io.*</tt> functions handle 64&nbsp;bit file offsets</h3>
203<p>
204The file I/O functions in the standard <tt>io.*</tt> library handle
20564&nbsp;bit file offsets. In particular this means it's possible
206to open files larger than 2&nbsp;Gigabytes and to reposition or obtain
207the current file position for offsets beyond 2&nbsp;GB
208(<tt>fp:seek()</tt> method).
209</p>
210
211<h3 id="debug_meta"><tt>debug.*</tt> functions identify metamethods</h3>
212<p>
213<tt>debug.getinfo()</tt> and <tt>lua_getinfo()</tt> also return information
214about invoked metamethods. The <tt>namewhat</tt> field is set to
215<tt>"metamethod"</tt> and the <tt>name</tt> field has the name of
216the corresponding metamethod (e.g. <tt>"__index"</tt>).
217</p>
218
219<h2 id="resumable">Fully Resumable VM</h2>
220<p>
221The LuaJIT 2.x VM is fully resumable. This means you can yield from a
222coroutine even across contexts, where this would not possible with
223the standard Lua&nbsp;5.1 VM: e.g. you can yield across <tt>pcall()</tt>
224and <tt>xpcall()</tt>, across iterators and across metamethods.
225</p>
226<p>
227Note however that LuaJIT 2.x doesn't use
228<a href="http://coco.luajit.org/"><span class="ext">&raquo;</span>&nbsp;Coco</a> anymore. This means the
229overhead for creating coroutines is much smaller and no extra
230C&nbsp;stacks need to be allocated. OTOH you can no longer yield
231across arbitrary C&nbsp;functions. Keep this in mind when
232upgrading from LuaJIT 1.x.
233</p>
234
235<h2 id="exceptions">C++ Exception Interoperability</h2>
236<p>
237LuaJIT has built-in support for interoperating with C++&nbsp;exceptions.
238The available range of features depends on the target platform and
239the toolchain used to compile LuaJIT:
240</p>
241<table class="exc">
242<tr class="exchead">
243<td class="excplatform">Platform</td>
244<td class="exccompiler">Compiler</td>
245<td class="excinterop">Interoperability</td>
246</tr>
247<tr class="odd separate">
248<td class="excplatform">POSIX/x64, DWARF2 unwinding</td>
249<td class="exccompiler">GCC 4.3+</td>
250<td class="excinterop"><b style="color: #00a000;">Full</b></td>
251</tr>
252<tr class="even">
253<td class="excplatform">Other platforms, DWARF2 unwinding</td>
254<td class="exccompiler">GCC</td>
255<td class="excinterop"><b style="color: #c06000;">Limited</b></td>
256</tr>
257<tr class="odd">
258<td class="excplatform">Windows/x64</td>
259<td class="exccompiler">MSVC or WinSDK</td>
260<td class="excinterop"><b style="color: #00a000;">Full</b></td>
261</tr>
262<tr class="even">
263<td class="excplatform">Windows/x86</td>
264<td class="exccompiler">Any</td>
265<td class="excinterop"><b style="color: #a00000;">No</b></td>
266</tr>
267<tr class="odd">
268<td class="excplatform">Other platforms</td>
269<td class="exccompiler">Other compilers</td>
270<td class="excinterop"><b style="color: #a00000;">No</b></td>
271</tr>
272</table>
273<p>
274<b style="color: #00a000;">Full interoperability</b> means:
275</p>
276<ul>
277<li>C++&nbsp;exceptions can be caught on the Lua side with <tt>pcall()</tt>,
278<tt>lua_pcall()</tt> etc.</li>
279<li>C++&nbsp;exceptions will be converted to the generic Lua error
280<tt>"C++&nbsp;exception"</tt>, unless you use the
281<a href="ext_c_api.html#mode_wrapcfunc">C&nbsp;call wrapper</a> feature.</li>
282<li>It's safe to throw C++&nbsp;exceptions across non-protected Lua frames
283on the C&nbsp;stack. The contents of the C++&nbsp;exception object
284pass through unmodified.</li>
285<li>Lua errors can be caught on the C++ side with <tt>catch(...)</tt>.
286The corresponding Lua error message can be retrieved from the Lua stack.</li>
287<li>Throwing Lua errors across C++ frames is safe. C++ destructors
288will be called.</li>
289</ul>
290<p>
291<b style="color: #c06000;">Limited interoperability</b> means:
292</p>
293<ul>
294<li>C++&nbsp;exceptions can be caught on the Lua side with <tt>pcall()</tt>,
295<tt>lua_pcall()</tt> etc.</li>
296<li>C++&nbsp;exceptions will be converted to the generic Lua error
297<tt>"C++&nbsp;exception"</tt>, unless you use the
298<a href="ext_c_api.html#mode_wrapcfunc">C&nbsp;call wrapper</a> feature.</li>
299<li>C++&nbsp;exceptions will be caught by non-protected Lua frames and
300are rethrown as a generic Lua error. The C++&nbsp;exception object will
301be destroyed.</li>
302<li>Lua errors <b>cannot</b> be caught on the C++ side.</li>
303<li>Throwing Lua errors across C++ frames will <b>not</b> call
304C++ destructors.</li>
305</ul>
306
307<p>
308<b style="color: #a00000;">No interoperability</b> means:
309</p>
310<ul>
311<li>It's <b>not</b> safe to throw C++&nbsp;exceptions across Lua frames.</li>
312<li>C++&nbsp;exceptions <b>cannot</b> be caught on the Lua side.</li>
313<li>Lua errors <b>cannot</b> be caught on the C++ side.</li>
314<li>Throwing Lua errors across C++ frames will <b>not</b> call
315C++ destructors.</li>
316<li>Additionally, on Windows/x86 with SEH-based C++&nbsp;exceptions:
317it's <b>not</b> safe to throw a Lua error across any frames containing
318a C++ function with any try/catch construct or using variables with
319(implicit) destructors. This also applies to any functions which may be
320inlined in such a function. It doesn't matter whether <tt>lua_error()</tt>
321is called inside or outside of a try/catch or whether any object actually
322needs to be destroyed: the SEH chain is corrupted and this will eventually
323lead to the termination of the process.</li>
324</ul>
325<br class="flush">
326</div>
327<div id="foot">
328<hr class="hide">
329Copyright &copy; 2005-2011 Mike Pall
330<span class="noprint">
331&middot;
332<a href="contact.html">Contact</a>
333</span>
334</div>
335</body>
336</html>
diff --git a/libraries/luajit-2.0/doc/faq.html b/libraries/luajit-2.0/doc/faq.html
new file mode 100644
index 0000000..b28a72c
--- /dev/null
+++ b/libraries/luajit-2.0/doc/faq.html
@@ -0,0 +1,180 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
2<html>
3<head>
4<title>Frequently Asked Questions (FAQ)</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<style type="text/css">
12dd { margin-left: 1.5em; }
13</style>
14</head>
15<body>
16<div id="site">
17<a href="http://luajit.org"><span>Lua<span id="logo">JIT</span></span></a>
18</div>
19<div id="head">
20<h1>Frequently Asked Questions (FAQ)</h1>
21</div>
22<div id="nav">
23<ul><li>
24<a href="luajit.html">LuaJIT</a>
25<ul><li>
26<a href="install.html">Installation</a>
27</li><li>
28<a href="running.html">Running</a>
29</li></ul>
30</li><li>
31<a href="extensions.html">Extensions</a>
32<ul><li>
33<a href="ext_ffi.html">FFI Library</a>
34<ul><li>
35<a href="ext_ffi_tutorial.html">FFI Tutorial</a>
36</li><li>
37<a href="ext_ffi_api.html">ffi.* API</a>
38</li><li>
39<a href="ext_ffi_semantics.html">FFI Semantics</a>
40</li></ul>
41</li><li>
42<a href="ext_jit.html">jit.* Library</a>
43</li><li>
44<a href="ext_c_api.html">Lua/C API</a>
45</li></ul>
46</li><li>
47<a href="status.html">Status</a>
48<ul><li>
49<a href="changes.html">Changes</a>
50</li></ul>
51</li><li>
52<a class="current" href="faq.html">FAQ</a>
53</li><li>
54<a href="http://luajit.org/performance.html">Performance <span class="ext">&raquo;</span></a>
55</li><li>
56<a href="http://luajit.org/download.html">Download <span class="ext">&raquo;</span></a>
57</li></ul>
58</div>
59<div id="main">
60<dl>
61<dt>Q: Where can I learn more about Lua and LuaJIT?</dt>
62<dd>
63<ul style="padding: 0;">
64<li>The <a href="http://lua.org"><span class="ext">&raquo;</span>&nbsp;main Lua.org site</a> has complete
65<a href="http://www.lua.org/docs.html"><span class="ext">&raquo;</span>&nbsp;documentation</a> of the language
66and links to books and papers about Lua.</li>
67<li>The community-managed <a href="http://lua-users.org/wiki/"><span class="ext">&raquo;</span>&nbsp;Lua Wiki</a>
68has information about diverse topics.</li>
69<li>The primary source of information for the latest developments surrounding
70Lua is the <a href="http://www.lua.org/lua-l.html"><span class="ext">&raquo;</span>&nbsp;Lua mailing list</a>.
71You can check out the <a href="http://lua-users.org/lists/lua-l/"><span class="ext">&raquo;</span>&nbsp;mailing
72list archive</a> or
73<a href="http://bazar2.conectiva.com.br/mailman/listinfo/lua"><span class="ext">&raquo;</span>&nbsp;subscribe</a>
74to the list (you need to be subscribed before posting).<br>
75This is also the place where announcements and discussions about LuaJIT
76take place.</li>
77</ul>
78</dl>
79
80<dl>
81<dt>Q: Where can I learn more about the compiler technology used by LuaJIT?</dt>
82<dd>
83I'm planning to write more documentation about the internals of LuaJIT.
84In the meantime, please use the following Google Scholar searches
85to find relevant papers:<br>
86Search for: <a href="http://scholar.google.com/scholar?q=Trace+Compiler"><span class="ext">&raquo;</span>&nbsp;Trace Compiler</a><br>
87Search for: <a href="http://scholar.google.com/scholar?q=JIT+Compiler"><span class="ext">&raquo;</span>&nbsp;JIT Compiler</a><br>
88Search for: <a href="http://scholar.google.com/scholar?q=Dynamic+Language+Optimizations"><span class="ext">&raquo;</span>&nbsp;Dynamic Language Optimizations</a><br>
89Search for: <a href="http://scholar.google.com/scholar?q=SSA+Form"><span class="ext">&raquo;</span>&nbsp;SSA Form</a><br>
90Search for: <a href="http://scholar.google.com/scholar?q=Linear+Scan+Register+Allocation"><span class="ext">&raquo;</span>&nbsp;Linear Scan Register Allocation</a><br>
91Here is a list of the <a href="http://article.gmane.org/gmane.comp.lang.lua.general/58908"><span class="ext">&raquo;</span>&nbsp;innovative features in LuaJIT</a>.<br>
92And, you know, reading the source is of course the only way to enlightenment. :-)
93</dd>
94</dl>
95
96<dl>
97<dt>Q: Why do I get this error: "attempt to index global 'arg' (a nil value)"?<br>
98Q: My vararg functions fail after switching to LuaJIT!</dt>
99<dd>LuaJIT is compatible to the Lua 5.1 language standard. It doesn't
100support the implicit <tt>arg</tt> parameter for old-style vararg
101functions from Lua 5.0.<br>Please convert your code to the
102<a href="http://www.lua.org/manual/5.1/manual.html#2.5.9"><span class="ext">&raquo;</span>&nbsp;Lua 5.1
103vararg syntax</a>.</dd>
104</dl>
105
106<dl>
107<dt>Q: Why do I get this error: "bad FPU precision"?<br>
108<dt>Q: I get weird behavior after initializing Direct3D.<br>
109<dt>Q: Some FPU operations crash after I load a Delphi DLL.<br>
110</dt>
111<dd>
112
113DirectX/Direct3D (up to version 9) sets the x87 FPU to single-precision
114mode by default. This violates the Windows ABI and interferes with the
115operation of many programs &mdash; LuaJIT is affected, too. Please make
116sure you always use the <tt>D3DCREATE_FPU_PRESERVE</tt> flag when
117initializing Direct3D.<br>
118
119Direct3D version 10 or higher do not show this behavior anymore.
120Consider testing your application with older versions, too.<br>
121
122Similarly, the Borland/Delphi runtime modifies the FPU control word and
123enables FP exceptions. Of course this violates the Windows ABI, too.
124Please check the Delphi docs for the Set8087CW method.
125
126</dl>
127
128<dl>
129<dt>Q: Sometimes Ctrl-C fails to stop my Lua program. Why?</dt>
130<dd>The interrupt signal handler sets a Lua debug hook. But this is
131currently ignored by compiled code (this will eventually be fixed). If
132your program is running in a tight loop and never falls back to the
133interpreter, the debug hook never runs and can't throw the
134"interrupted!" error.<br> In the meantime you have to press Ctrl-C
135twice to get stop your program. That's similar to when it's stuck
136running inside a C function under the Lua interpreter.</dd>
137</dl>
138
139<dl>
140<dt>Q: Why doesn't my favorite power-patch for Lua apply against LuaJIT?</dt>
141<dd>Because it's a completely redesigned VM and has very little code
142in common with Lua anymore. Also, if the patch introduces changes to
143the Lua semantics, these would need to be reflected everywhere in the
144VM, from the interpreter up to all stages of the compiler.<br> Please
145use only standard Lua language constructs. For many common needs you
146can use source transformations or use wrapper or proxy functions.
147The compiler will happily optimize away such indirections.</dd>
148</dl>
149
150<dl>
151<dt>Q: Lua runs everywhere. Why doesn't LuaJIT support my CPU?</dt>
152<dd>Because it's a compiler &mdash; it needs to generate native
153machine code. This means the code generator must be ported to each
154architecture. And the fast interpreter is written in assembler and
155must be ported, too. This is quite an undertaking.<br>
156The <a href="install.html">install documentation</a> shows the supported
157architectures. Other architectures will follow based on sufficient user
158demand and/or sponsoring.</dd>
159</dl>
160
161<dl>
162<dt>Q: When will feature X be added? When will the next version be released?</dt>
163<dd>When it's ready.<br>
164C'mon, it's open source &mdash; I'm doing it on my own time and you're
165getting it for free. You can either contribute a patch or sponsor
166the development of certain features, if they are important to you.
167</dd>
168</dl>
169<br class="flush">
170</div>
171<div id="foot">
172<hr class="hide">
173Copyright &copy; 2005-2011 Mike Pall
174<span class="noprint">
175&middot;
176<a href="contact.html">Contact</a>
177</span>
178</div>
179</body>
180</html>
diff --git a/libraries/luajit-2.0/doc/img/contact.png b/libraries/luajit-2.0/doc/img/contact.png
new file mode 100644
index 0000000..9c73dc5
--- /dev/null
+++ b/libraries/luajit-2.0/doc/img/contact.png
Binary files differ
diff --git a/libraries/luajit-2.0/doc/install.html b/libraries/luajit-2.0/doc/install.html
new file mode 100644
index 0000000..07c55fa
--- /dev/null
+++ b/libraries/luajit-2.0/doc/install.html
@@ -0,0 +1,543 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
2<html>
3<head>
4<title>Installation</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<style type="text/css">
12table.compat {
13 line-height: 1.2;
14 width: 600px;
15}
16table.compat td {
17 border: 1px solid #bfcfff;
18 font-size: 90%;
19 height: 2.5em;
20}
21table.compat tr.compathead td {
22 font-weight: bold;
23 border-bottom: 2px solid #bfcfff;
24}
25tr.compathead td.compatos {
26 vertical-align: top;
27}
28table.compat td.compatcpu {
29 width: 16%;
30 border-right: 2px solid #bfcfff;
31}
32td.compatos {
33 width: 21%;
34 vertical-align: middle;
35}
36td.compatno {
37 background-color: #d0d0d0;
38}
39</style>
40</head>
41<body>
42<div id="site">
43<a href="http://luajit.org"><span>Lua<span id="logo">JIT</span></span></a>
44</div>
45<div id="head">
46<h1>Installation</h1>
47</div>
48<div id="nav">
49<ul><li>
50<a href="luajit.html">LuaJIT</a>
51<ul><li>
52<a class="current" href="install.html">Installation</a>
53</li><li>
54<a href="running.html">Running</a>
55</li></ul>
56</li><li>
57<a href="extensions.html">Extensions</a>
58<ul><li>
59<a href="ext_ffi.html">FFI Library</a>
60<ul><li>
61<a href="ext_ffi_tutorial.html">FFI Tutorial</a>
62</li><li>
63<a href="ext_ffi_api.html">ffi.* API</a>
64</li><li>
65<a href="ext_ffi_semantics.html">FFI Semantics</a>
66</li></ul>
67</li><li>
68<a href="ext_jit.html">jit.* Library</a>
69</li><li>
70<a href="ext_c_api.html">Lua/C API</a>
71</li></ul>
72</li><li>
73<a href="status.html">Status</a>
74<ul><li>
75<a href="changes.html">Changes</a>
76</li></ul>
77</li><li>
78<a href="faq.html">FAQ</a>
79</li><li>
80<a href="http://luajit.org/performance.html">Performance <span class="ext">&raquo;</span></a>
81</li><li>
82<a href="http://luajit.org/download.html">Download <span class="ext">&raquo;</span></a>
83</li></ul>
84</div>
85<div id="main">
86<p>
87LuaJIT is only distributed as a source package. This page explains
88how to build and install LuaJIT with different operating systems
89and C&nbsp;compilers.
90</p>
91<p>
92For the impatient (on POSIX systems):
93</p>
94<pre class="code">
95make &amp;&amp; sudo make install
96</pre>
97<p>
98LuaJIT currently builds out-of-the box on most systems.
99Here's the compatibility matrix for the supported combinations of
100operating systems, CPUs and compilers:
101</p>
102<table class="compat">
103<tr class="compathead">
104<td class="compatcpu">CPU / OS</td>
105<td class="compatos"><a href="#posix">Linux</a> or<br><a href="#android">Android</a></td>
106<td class="compatos"><a href="#posix">*BSD, Other</a></td>
107<td class="compatos"><a href="#posix">OSX 10.3+</a> or<br><a href="#ios">iOS 3.0+</a></td>
108<td class="compatos"><a href="#windows">Windows<br>XP/Vista/7</a></td>
109</tr>
110<tr class="odd separate">
111<td class="compatcpu">x86 (32 bit)</td>
112<td class="compatos">GCC 4.x<br>GCC 3.4</td>
113<td class="compatos">GCC 4.x<br>GCC 3.4</td>
114<td class="compatos">GCC 4.x<br>GCC 3.4</td>
115<td class="compatos">MSVC, MSVC/EE<br>WinSDK<br>MinGW, Cygwin</td>
116</tr>
117<tr class="even">
118<td class="compatcpu">x64 (64 bit)</td>
119<td class="compatos">GCC 4.x</td>
120<td class="compatos compatno">&nbsp;</td>
121<td class="compatos">GCC 4.x</td>
122<td class="compatos">MSVC + SDK v7.0<br>WinSDK v7.0</td>
123</tr>
124<tr class="odd">
125<td class="compatcpu"><a href="#android">ARMv5+<br>ARM9E+</a></td>
126<td class="compatos">GCC 4.2+</td>
127<td class="compatos">GCC 4.2+</td>
128<td class="compatos">GCC 4.2+</td>
129<td class="compatos compatno">&nbsp;</td>
130</tr>
131<tr class="even">
132<td class="compatcpu"><a href="#ppc">PPC</a></td>
133<td class="compatos">GCC 4.3+</td>
134<td class="compatos">GCC 4.3+</td>
135<td class="compatos compatno">&nbsp;</td>
136<td class="compatos compatno">&nbsp;</td>
137</tr>
138<tr class="odd">
139<td class="compatcpu"><a href="#ppc">PPC/e500v2</a></td>
140<td class="compatos">GCC 4.3+</td>
141<td class="compatos">GCC 4.3+</td>
142<td class="compatos compatno">&nbsp;</td>
143<td class="compatos compatno">&nbsp;</td>
144</tr>
145</table>
146
147<h2>Configuring LuaJIT</h2>
148<p>
149The standard configuration should work fine for most installations.
150Usually there is no need to tweak the settings. The following files
151hold all user-configurable settings:
152</p>
153<ul>
154<li><tt>src/luaconf.h</tt> sets some configuration variables.</li>
155<li><tt>Makefile</tt> has settings for <b>installing</b> LuaJIT (POSIX
156only).</li>
157<li><tt>src/Makefile</tt> has settings for <b>compiling</b> LuaJIT
158under POSIX, MinGW or Cygwin.</li>
159<li><tt>src/msvcbuild.bat</tt> has settings for compiling LuaJIT with
160MSVC or WinSDK.</li>
161</ul>
162<p>
163Please read the instructions given in these files, before changing
164any settings.
165</p>
166
167<h2 id="posix">POSIX Systems (Linux, OSX, *BSD etc.)</h2>
168<h3>Prerequisites</h3>
169<p>
170Depending on your distribution, you may need to install a package for
171GCC, the development headers and/or a complete SDK. E.g. on a current
172Debian/Ubuntu, install <tt>libc6-dev</tt> with the package manager.
173</p>
174<p>
175Download the current source package of LuaJIT (pick the .tar.gz),
176if you haven't already done so. Move it to a directory of your choice,
177open a terminal window and change to this directory. Now unpack the archive
178and change to the newly created directory:
179</p>
180<pre class="code">
181tar zxf LuaJIT-2.0.0-beta9.tar.gz
182cd LuaJIT-2.0.0-beta9</pre>
183<h3>Building LuaJIT</h3>
184<p>
185The supplied Makefiles try to auto-detect the settings needed for your
186operating system and your compiler. They need to be run with GNU Make,
187which is probably the default on your system, anyway. Simply run:
188</p>
189<pre class="code">
190make
191</pre>
192<p>
193This always builds a native x86, x64 or PPC binary, depending on the host OS
194you're running this command on. Check the section on
195<a href="#cross">cross-compilation</a> for more options.
196</p>
197<p>
198By default, modules are only searched under the prefix <tt>/usr/local</tt>.
199You can add an extra prefix to the search paths by appending the
200<tt>PREFIX</tt> option, e.g.:
201</p>
202<pre class="code">
203make PREFIX=/home/myself/lj2
204</pre>
205<p>
206Note for OSX: <tt>MACOSX_DEPLOYMENT_TARGET</tt> is set to <tt>10.4</tt>
207in <tt>src/Makefile</tt>. Change it, if you want to build on an older version.
208</p>
209<h3>Installing LuaJIT</h3>
210<p>
211The top-level Makefile installs LuaJIT by default under
212<tt>/usr/local</tt>, i.e. the executable ends up in
213<tt>/usr/local/bin</tt> and so on. You need root privileges
214to write to this path. So, assuming sudo is installed on your system,
215run the following command and enter your sudo password:
216</p>
217<pre class="code">
218sudo make install
219</pre>
220<p>
221Otherwise specify the directory prefix as an absolute path, e.g.:
222</p>
223<pre class="code">
224make install PREFIX=/home/myself/lj2
225</pre>
226<p>
227Obviously the prefixes given during build and installation need to be the same.
228</p>
229<p style="color: #c00000;">
230Note: to avoid overwriting a previous version, the beta test releases
231only install the LuaJIT executable under the versioned name (i.e.
232<tt>luajit-2.0.0-beta9</tt>). You probably want to create a symlink
233for convenience, with a command like this:
234</p>
235<pre class="code" style="color: #c00000;">
236sudo ln -sf luajit-2.0.0-beta9&nbsp;/usr/local/bin/luajit
237</pre>
238
239<h2 id="windows">Windows Systems</h2>
240<h3>Prerequisites</h3>
241<p>
242Either install one of the open source SDKs
243(<a href="http://mingw.org/"><span class="ext">&raquo;</span>&nbsp;MinGW</a> or
244<a href="http://www.cygwin.com/"><span class="ext">&raquo;</span>&nbsp;Cygwin</a>), which come with a modified
245GCC plus the required development headers.
246</p>
247<p>
248Or install Microsoft's Visual C++ (MSVC). The freely downloadable
249<a href="http://www.microsoft.com/Express/VC/"><span class="ext">&raquo;</span>&nbsp;Express Edition</a>
250works just fine, but only contains an x86 compiler.
251</p>
252<p>
253The freely downloadable
254<a href="http://msdn.microsoft.com/en-us/windowsserver/bb980924.aspx"><span class="ext">&raquo;</span>&nbsp;Windows SDK</a>
255only comes with command line tools, but this is all you need to build LuaJIT.
256It contains x86 and x64 compilers.
257</p>
258<p>
259Next, download the source package and unpack it using an archive manager
260(e.g. the Windows Explorer) to a directory of your choice.
261</p>
262<h3>Building with MSVC</h3>
263<p>
264Open a "Visual Studio .NET Command Prompt", <tt>cd</tt> to the
265directory where you've unpacked the sources and run these commands:
266</p>
267<pre class="code">
268cd src
269msvcbuild
270</pre>
271<p>
272Then follow the installation instructions below.
273</p>
274<h3>Building with the Windows SDK</h3>
275<p>
276Open a "Windows SDK Command Shell" and select the x86 compiler:
277</p>
278<pre class="code">
279setenv /release /x86
280</pre>
281<p>
282Or select the x64 compiler:
283</p>
284<pre class="code">
285setenv /release /x64
286</pre>
287<p>
288Then <tt>cd</tt> to the directory where you've unpacked the sources
289and run these commands:
290</p>
291<pre class="code">
292cd src
293msvcbuild
294</pre>
295<p>
296Then follow the installation instructions below.
297</p>
298<h3>Building with MinGW or Cygwin</h3>
299<p>
300Open a command prompt window and make sure the MinGW or Cygwin programs
301are in your path. Then <tt>cd</tt> to the directory where
302you've unpacked the sources and run this command for MinGW:
303</p>
304<pre class="code">
305mingw32-make
306</pre>
307<p>
308Or this command for Cygwin:
309</p>
310<pre class="code">
311make
312</pre>
313<p>
314Then follow the installation instructions below.
315</p>
316<h3>Installing LuaJIT</h3>
317<p>
318Copy <tt>luajit.exe</tt> and <tt>lua51.dll</tt> (built in the <tt>src</tt>
319directory) to a newly created directory (any location is ok).
320Add <tt>lua</tt> and <tt>lua\jit</tt> directories below it and copy
321all Lua files from the <tt>lib</tt> directory of the distribution
322to the latter directory.
323</p>
324<p>
325There are no hardcoded
326absolute path names &mdash; all modules are loaded relative to the
327directory where <tt>luajit.exe</tt> is installed
328(see <tt>src/luaconf.h</tt>).
329</p>
330
331<h2 id="cross">Cross-compiling LuaJIT</h2>
332<p>
333The build system has limited support for cross-compilation. For details
334check the comments in <tt>src/Makefile</tt>. Here are some popular examples:
335</p>
336<p>
337You can cross-compile to a <b>32 bit binary on a multilib x64 OS</b> by
338installing the multilib development packages (e.g. <tt>libc6-dev-i386</tt>
339on Debian/Ubuntu) and running:
340</p>
341<pre class="code">
342make CC="gcc -m32"
343</pre>
344<p>
345You can cross-compile for a <b>Windows target on Debian/Ubuntu</b> by
346installing the <tt>mingw32</tt> package and running:
347</p>
348<pre class="code">
349make HOST_CC="gcc -m32" CROSS=i586-mingw32msvc- TARGET_SYS=Windows
350</pre>
351<p>
352You can cross-compile for an <b>ARM target</b> on an x86 or x64 host
353system using a standard GNU cross-compile toolchain (Binutils, GCC,
354EGLIBC). The <tt>CROSS</tt> prefix may vary depending on the
355<tt>--target</tt> of the toolchain:
356</p>
357<pre class="code">
358make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabi-
359</pre>
360<p>
361You can cross-compile for <b id="android">Android (ARM)</b> using the <a href="http://developer.android.com/sdk/ndk/index.html"><span class="ext">&raquo;</span>&nbsp;Android NDK</a>.
362The environment variables need to match the install locations and the
363desired target platform. E.g. Android&nbsp;2.2 corresponds to ABI level&nbsp;8:
364</p>
365<pre class="code">
366NDK=/opt/android/ndk
367NDKABI=8
368NDKVER=$NDK/toolchains/arm-linux-androideabi-4.4.3
369NDKP=$NDKVER/prebuilt/linux-x86/bin/arm-linux-androideabi-
370NDKF="--sysroot $NDK/platforms/android-$NDKABI/arch-arm"
371make HOST_CC="gcc -m32" CROSS=$NDKP TARGET_FLAGS="$NDKF"
372</pre>
373<p>
374You can cross-compile for <b id="ios">iOS 3.0+</b> (iPhone/iPad) using the <a href="http://developer.apple.com/devcenter/ios/index.action"><span class="ext">&raquo;</span>&nbsp;iOS SDK</a>.
375The environment variables need to match the iOS SDK version:
376</p>
377<p style="font-size: 8pt;">
378Note: <b>the JIT compiler is disabled for iOS</b>, because regular iOS Apps
379are not allowed to generate code at runtime. You'll only get the performance
380of the LuaJIT interpreter on iOS. This is still faster than plain Lua, but
381much slower than the JIT compiler. Please complain to Apple, not me.
382Or use Android. :-p
383</p>
384<pre class="code">
385ISDK=/Developer/Platforms/iPhoneOS.platform/Developer
386ISDKVER=iPhoneOS4.3.sdk
387ISDKP=$ISDK/usr/bin/
388ISDKF="-arch armv6 -isysroot $ISDK/SDKs/$ISDKVER"
389make HOST_CC="gcc -m32 -arch i386" CROSS=$ISDKP TARGET_FLAGS="$ISDKF" \
390 TARGET_SYS=iOS
391</pre>
392<p>
393You can cross-compile for a <b id="ppc">PPC target</b> or a
394<b>PPC/e500v2 target</b> on x86 or x64 host systems using a standard
395GNU cross-compile toolchain (Binutils, GCC, EGLIBC).
396The <tt>CROSS</tt> prefix may vary depending on the <tt>--target</tt>
397of the toolchain:
398</p>
399<pre class="code">
400# PPC
401make HOST_CC="gcc -m32" CROSS=powerpc-linux-gnu-
402</pre>
403<pre class="code">
404# PPC/e500v2
405make HOST_CC="gcc -m32" CROSS=powerpc-e500v2-linux-gnuspe-
406</pre>
407<p>
408Whenever the <b>host OS and the target OS differ</b>, you need to specify
409<tt>TARGET_SYS</tt> or you'll get assembler or linker errors. E.g. if
410you're compiling on a Windows or OSX host for embedded Linux or Android,
411you need to add <tt>TARGET_SYS=Linux</tt> to the examples above. For a
412minimal target OS, you may need to disable the built-in allocator in
413<tt>src/Makefile</tt> and use <tt>TARGET_SYS=Other</tt>.
414</p>
415
416<h2 id="embed">Embedding LuaJIT</h2>
417<p>
418LuaJIT is API-compatible with Lua 5.1. If you've already embedded Lua
419into your application, you probably don't need to do anything to switch
420to LuaJIT, except link with a different library:
421</p>
422<ul>
423<li>It's strongly suggested to build LuaJIT separately using the supplied
424build system. Please do <em>not</em> attempt to integrate the individual
425source files into your build tree. You'll most likely get the internal build
426dependencies wrong or mess up the compiler flags. Treat LuaJIT like any
427other external library and link your application with either the dynamic
428or static library, depending on your needs.</li>
429<li>If you want to load C modules compiled for plain Lua
430with <tt>require()</tt>, you need to make sure the public symbols
431(e.g. <tt>lua_pushnumber</tt>) are exported, too:
432<ul><li>On POSIX systems you can either link to the shared library
433or link the static library into your application. In the latter case
434you'll need to export all public symbols from your main executable
435(e.g. <tt>-Wl,-E</tt> on Linux) and add the external dependencies
436(e.g. <tt>-lm -ldl</tt> on Linux).</li>
437<li>Since Windows symbols are bound to a specific DLL name, you need to
438link to the <tt>lua51.dll</tt> created by the LuaJIT build (do not rename
439the DLL). You may link LuaJIT statically on Windows only if you don't
440intend to load Lua/C modules at runtime.
441</li></ul>
442</li>
443<li>
444If you're building a 64 bit application on OSX which links directly or
445indirectly against LuaJIT, you need to link your main executable
446with these flags:
447<pre class="code">
448-pagezero_size 10000 -image_base 100000000
449</pre>
450Also, it's recommended to <tt>rebase</tt> all (self-compiled) shared libraries
451which are loaded at runtime on OSX/x64 (e.g. C extension modules for Lua).
452See: <tt>man rebase</tt>
453</li>
454</ul>
455<p>Additional hints for initializing LuaJIT using the C API functions:</p>
456<ul>
457<li>Here's a
458<a href="http://lua-users.org/wiki/SimpleLuaApiExample"><span class="ext">&raquo;</span>&nbsp;simple example</a>
459for embedding Lua or LuaJIT into your application.</li>
460<li>Make sure you use <tt>luaL_newstate</tt>. Avoid using
461<tt>lua_newstate</tt>, since this uses the (slower) default memory
462allocator from your system (no support for this on x64).</li>
463<li>Make sure you use <tt>luaL_openlibs</tt> and not the old Lua 5.0 style
464of calling <tt>luaopen_base</tt> etc. directly.</li>
465<li>To change or extend the list of standard libraries to load, copy
466<tt>src/lib_init.c</tt> to your project and modify it accordingly.
467Make sure the <tt>jit</tt> library is loaded or the JIT compiler
468will not be activated.</li>
469<li>The <tt>bit.*</tt> module for bitwise operations
470is already built-in. There's no need to statically link
471<a href="http://bitop.luajit.org/"><span class="ext">&raquo;</span>&nbsp;Lua BitOp</a> to your application.</li>
472</ul>
473
474<h2 id="distro">Hints for Distribution Maintainers</h2>
475<p>
476The LuaJIT build system has extra provisions for the needs of most
477POSIX-based distributions. If you're a package maintainer for
478a distribution, <em>please</em> make use of these features and
479avoid patching, subverting, autotoolizing or messing up the build system
480in unspeakable ways.
481</p>
482<p>
483There should be absolutely no need to patch <tt>luaconf.h</tt> or any
484of the Makefiles. And please do not hand-pick files for your packages &mdash;
485simply use whatever <tt>make install</tt> creates. There's a reason
486for all of the files <em>and</em> directories it creates.
487</p>
488<p>
489The build system uses GNU make and auto-detects most settings based on
490the host you're building it on. This should work fine for native builds,
491even when sandboxed. You may need to pass some of the following flags to
492<em>both</em> the <tt>make</tt> and the <tt>make install</tt> command lines
493for a regular distribution build:
494</p>
495<ul>
496<li><tt>PREFIX</tt> overrides the installation path and should usually
497be set to <tt>/usr</tt>. Setting this also changes the module paths and
498the <tt>-rpath</tt> of the shared library.</li>
499<li><tt>DESTDIR</tt> is an absolute path which allows you to install
500to a shadow tree instead of the root tree of the build system.</li>
501<li>Have a look at the top-level <tt>Makefile</tt> and <tt>src/Makefile</tt>
502for additional variables to tweak. The following variables <em>may</em> be
503overridden, but it's <em>not</em> recommended, except for special needs
504like cross-builds:
505<tt>BUILDMODE, CC, HOST_CC, STATIC_CC, DYNAMIC_CC, CFLAGS, HOST_CFLAGS,
506TARGET_CFLAGS, LDFLAGS, HOST_LDFLAGS, TARGET_LDFLAGS, TARGET_SHLDFLAGS,
507TARGET_FLAGS, LIBS, HOST_LIBS, TARGET_LIBS, CROSS, HOST_SYS, TARGET_SYS
508</tt></li>
509</ul>
510<p>
511The build system has a special target for an amalgamated build, i.e.
512<tt>make amalg</tt>. This compiles the LuaJIT core as one huge C file
513and allows GCC to generate faster and shorter code. Alas, this requires
514lots of memory during the build. This may be a problem for some users,
515that's why it's not enabled by default. But it shouldn't be a problem for
516most build farms. It's recommended that binary distributions use this
517target for their LuaJIT builds.
518</p>
519<p>
520The tl;dr version of the above:
521</p>
522<pre class="code">
523make amalg PREFIX=/usr && \
524make install PREFIX=/usr DESTDIR=/tmp/buildroot
525</pre>
526<p>
527Finally, if you encounter any difficulties, please
528<a href="contact.html">contact me</a> first, instead of releasing a broken
529package onto unsuspecting users. Because they'll usually gonna complain
530to me (the upstream) and not you (the package maintainer), anyway.
531</p>
532<br class="flush">
533</div>
534<div id="foot">
535<hr class="hide">
536Copyright &copy; 2005-2011 Mike Pall
537<span class="noprint">
538&middot;
539<a href="contact.html">Contact</a>
540</span>
541</div>
542</body>
543</html>
diff --git a/libraries/luajit-2.0/doc/luajit.html b/libraries/luajit-2.0/doc/luajit.html
new file mode 100644
index 0000000..9725f5c
--- /dev/null
+++ b/libraries/luajit-2.0/doc/luajit.html
@@ -0,0 +1,142 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
2<html>
3<head>
4<title>LuaJIT</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<meta name="description" content="LuaJIT is a Just-In-Time (JIT) compiler for the Lua language.">
12</head>
13<body>
14<div id="site">
15<a href="http://luajit.org"><span>Lua<span id="logo">JIT</span></span></a>
16</div>
17<div id="head">
18<h1>LuaJIT</h1>
19</div>
20<div id="nav">
21<ul><li>
22<a class="current" href="luajit.html">LuaJIT</a>
23<ul><li>
24<a href="install.html">Installation</a>
25</li><li>
26<a href="running.html">Running</a>
27</li></ul>
28</li><li>
29<a href="extensions.html">Extensions</a>
30<ul><li>
31<a href="ext_ffi.html">FFI Library</a>
32<ul><li>
33<a href="ext_ffi_tutorial.html">FFI Tutorial</a>
34</li><li>
35<a href="ext_ffi_api.html">ffi.* API</a>
36</li><li>
37<a href="ext_ffi_semantics.html">FFI Semantics</a>
38</li></ul>
39</li><li>
40<a href="ext_jit.html">jit.* Library</a>
41</li><li>
42<a href="ext_c_api.html">Lua/C API</a>
43</li></ul>
44</li><li>
45<a href="status.html">Status</a>
46<ul><li>
47<a href="changes.html">Changes</a>
48</li></ul>
49</li><li>
50<a href="faq.html">FAQ</a>
51</li><li>
52<a href="http://luajit.org/performance.html">Performance <span class="ext">&raquo;</span></a>
53</li><li>
54<a href="http://luajit.org/download.html">Download <span class="ext">&raquo;</span></a>
55</li></ul>
56</div>
57<div id="main">
58<p>
59LuaJIT is a <b>Just-In-Time Compiler</b> for the Lua<sup>*</sup>
60programming language.
61</p>
62<p>
63LuaJIT is Copyright &copy; 2005-2011 Mike Pall.
64LuaJIT is open source software, released under the
65<a href="http://www.opensource.org/licenses/mit-license.php"><span class="ext">&raquo;</span>&nbsp;MIT license</a>.
66</p>
67<p class="indent" style="color: #606060;">
68* Lua is a powerful, dynamic and light-weight programming language
69designed for extending applications. Lua is also frequently used as a
70general-purpose, stand-alone language. More information about
71Lua can be found at: <a href="http://www.lua.org/"><span class="ext">&raquo;</span>&nbsp;http://www.lua.org/</a>
72</p>
73<h2>Compatibility</h2>
74<p>
75LuaJIT implements the full set of language features defined by Lua 5.1.
76The virtual machine (VM) is <b>API- and ABI-compatible</b> to the
77standard Lua interpreter and can be deployed as a drop-in replacement.
78</p>
79<p>
80LuaJIT offers more performance, at the expense of portability. It
81currently runs on all popular operating systems based on
82<b>x86</b> or <b>x64</b> CPUs (Linux, Windows, OSX etc.) or embedded
83systems based on <b>ARM</b> (Android, iOS) or <b>PPC</b> CPUs.
84Other platforms will be supported in the future, based on user demand
85and sponsoring.
86</p>
87
88<h2>Overview</h2>
89<p>
90LuaJIT has been successfully used as a <b>scripting middleware</b> in
91games, 3D modellers, numerical simulations, trading platforms and many
92other specialty applications. It combines high flexibility with high
93performance and an unmatched <b>low memory footprint</b>: less than
94<b>125K</b> for the VM plus less than <b>85K</b> for the JIT compiler (on x86).
95</p>
96<p>
97LuaJIT has been in continuous development since 2005. It's widely
98considered to be <b>one of the fastest dynamic language
99implementations</b>. It has outperformed other dynamic languages on many
100cross-language benchmarks since its first release &mdash; often by a
101substantial margin. In 2009 other dynamic language VMs started to catch up
102with the performance of LuaJIT 1.x. Well, I couldn't let that slide. ;-)
103</p>
104<p>
1052009 also marks the first release of the long-awaited <b>LuaJIT 2.0</b>.
106The whole VM has been rewritten from the ground up and relentlessly
107optimized for performance. It combines a high-speed interpreter,
108written in assembler, with a state-of-the-art JIT compiler.
109</p>
110<p>
111An innovative <b>trace compiler</b> is integrated with advanced,
112SSA-based optimizations and a highly tuned code generation backend. This
113allows a substantial reduction of the overhead associated with dynamic
114language features.
115</p>
116<p>
117It's destined to break into the <a href="http://luajit.org/performance.html"><span class="ext">&raquo;</span>&nbsp;performance</a>
118range traditionally reserved for offline, static language compilers.
119</p>
120
121<h2>More ...</h2>
122<p>
123Click on the LuaJIT sub-topics in the navigation bar to learn more
124about LuaJIT.
125</p>
126<p><p>
127Click on the Logo in the upper left corner to visit
128the LuaJIT project page on the web. All other links to online
129resources are marked with a '<span class="ext">&raquo;</span>'.
130</p>
131<br class="flush">
132</div>
133<div id="foot">
134<hr class="hide">
135Copyright &copy; 2005-2011 Mike Pall
136<span class="noprint">
137&middot;
138<a href="contact.html">Contact</a>
139</span>
140</div>
141</body>
142</html>
diff --git a/libraries/luajit-2.0/doc/running.html b/libraries/luajit-2.0/doc/running.html
new file mode 100644
index 0000000..e2afdee
--- /dev/null
+++ b/libraries/luajit-2.0/doc/running.html
@@ -0,0 +1,313 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
2<html>
3<head>
4<title>Running LuaJIT</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<style type="text/css">
12table.opt {
13 line-height: 1.2;
14}
15tr.opthead td {
16 font-weight: bold;
17}
18td.flag_name {
19 width: 4em;
20}
21td.flag_level {
22 width: 2em;
23 text-align: center;
24}
25td.param_name {
26 width: 6em;
27}
28td.param_default {
29 width: 4em;
30 text-align: right;
31}
32</style>
33</head>
34<body>
35<div id="site">
36<a href="http://luajit.org"><span>Lua<span id="logo">JIT</span></span></a>
37</div>
38<div id="head">
39<h1>Running LuaJIT</h1>
40</div>
41<div id="nav">
42<ul><li>
43<a href="luajit.html">LuaJIT</a>
44<ul><li>
45<a href="install.html">Installation</a>
46</li><li>
47<a class="current" href="running.html">Running</a>
48</li></ul>
49</li><li>
50<a href="extensions.html">Extensions</a>
51<ul><li>
52<a href="ext_ffi.html">FFI Library</a>
53<ul><li>
54<a href="ext_ffi_tutorial.html">FFI Tutorial</a>
55</li><li>
56<a href="ext_ffi_api.html">ffi.* API</a>
57</li><li>
58<a href="ext_ffi_semantics.html">FFI Semantics</a>
59</li></ul>
60</li><li>
61<a href="ext_jit.html">jit.* Library</a>
62</li><li>
63<a href="ext_c_api.html">Lua/C API</a>
64</li></ul>
65</li><li>
66<a href="status.html">Status</a>
67<ul><li>
68<a href="changes.html">Changes</a>
69</li></ul>
70</li><li>
71<a href="faq.html">FAQ</a>
72</li><li>
73<a href="http://luajit.org/performance.html">Performance <span class="ext">&raquo;</span></a>
74</li><li>
75<a href="http://luajit.org/download.html">Download <span class="ext">&raquo;</span></a>
76</li></ul>
77</div>
78<div id="main">
79<p>
80LuaJIT has only a single stand-alone executable, called <tt>luajit</tt> on
81POSIX systems or <tt>luajit.exe</tt> on Windows. It can be used to run simple
82Lua statements or whole Lua applications from the command line. It has an
83interactive mode, too.
84</p>
85<p class="indent" style="color: #c00000;">
86Note: the beta test releases only install under the versioned name on
87POSIX systems (to avoid overwriting a previous version). You either need
88to type <tt>luajit-2.0.0-beta9</tt> to start it or create a symlink
89with a command like this:
90</p>
91<pre class="code" style="color: #c00000;">
92sudo ln -sf luajit-2.0.0-beta9&nbsp;/usr/local/bin/luajit
93</pre>
94<p>
95Unlike previous versions <b>optimization is turned on by default</b> in
96LuaJIT 2.0!<br>It's no longer necessary to use <tt>luajit&nbsp;-O</tt>.
97</p>
98
99<h2 id="options">Command Line Options</h2>
100<p>
101The <tt>luajit</tt> stand-alone executable is just a slightly modified
102version of the regular <tt>lua</tt> stand-alone executable.
103It supports the same basic options, too. <tt>luajit&nbsp;-h</tt>
104prints a short list of the available options. Please have a look at the
105<a href="http://www.lua.org/manual/5.1/manual.html#6"><span class="ext">&raquo;</span>&nbsp;Lua manual</a>
106for details.
107</p>
108<p>
109LuaJIT has some additional options:
110</p>
111
112<h3 id="opt_b"><tt>-b[options] input output</tt></h3>
113<p>
114This option saves or lists bytecode. The following additional options
115are accepted:
116</p>
117<ul>
118<li><tt>-l</tt> &mdash; Only list bytecode.</li>
119<li><tt>-s</tt> &mdash; Strip debug info (this is the default).</li>
120<li><tt>-g</tt> &mdash; Keep debug info.</li>
121<li><tt>-n name</tt> &mdash; Set module name (default: auto-detect from input name)</li>
122<li><tt>-t type</tt> &mdash; Set output file type (default: auto-detect from output name).</li>
123<li><tt>-a arch</tt> &mdash; Override architecture for object files (default: native).</li>
124<li><tt>-o os</tt> &mdash; Override OS for object files (default: native).</li>
125<li><tt>-e chunk</tt> &mdash; Use chunk string as input.</li>
126<li><tt>-</tt> (a single minus sign) &mdash; Use stdin as input and/or stdout as output.</li>
127</ul>
128<p>
129The output file type is auto-detected from the extension of the output
130file name:
131</p>
132<ul>
133<li><tt>c</tt> &mdash; C source file, exported bytecode data.</li>
134<li><tt>h</tt> &mdash; C header file, static bytecode data.</li>
135<li><tt>obj</tt> or <tt>o</tt> &mdash; Object file, exported bytecode data
136(OS- and architecture-specific).</li>
137<li><tt>raw</tt> or any other extension &mdash; Raw bytecode file (portable).
138</ul>
139<p>
140Notes:
141</p>
142<ul>
143<li>See also <a href="extensions.html#string_dump">string.dump()</a>
144for information on bytecode portability and compatibility.</li>
145<li>A file in raw bytecode format is auto-detected and can be loaded like
146any Lua source file. E.g. directly from the command line or with
147<tt>loadfile()</tt>, <tt>dofile()</tt> etc.</li>
148<li>To statically embed the bytecode of a module in your application,
149generate an object file and just link it with your application.</li>
150<li>On most ELF-based systems (e.g. Linux) you need to explicitly export the
151global symbols when linking your application, e.g. with: <tt>-Wl,-E</tt></li>
152<li><tt>require()</tt> tries to load embedded bytecode data from exported
153symbols (in <tt>*.exe</tt> or <tt>lua51.dll</tt> on Windows) and from
154shared libraries in <tt>package.cpath</tt>.</li>
155</ul>
156<p>
157Typical usage examples:
158</p>
159<pre class="code">
160luajit -b test.lua test.out # Save bytecode to test.out
161luajit -bg test.lua test.out # Keep debug info
162luajit -be "print('hello world')" test.out # Save cmdline script
163
164luajit -bl test.lua # List to stdout
165luajit -bl test.lua test.txt # List to test.txt
166luajit -ble "print('hello world')" # List cmdline script
167
168luajit -b test.lua test.obj # Generate object file
169# Link test.obj with your application and load it with require("test")
170</pre>
171
172<h3 id="opt_j"><tt>-j cmd[=arg[,arg...]]</tt></h3>
173<p>
174This option performs a LuaJIT control command or activates one of the
175loadable extension modules. The command is first looked up in the
176<tt>jit.*</tt> library. If no matching function is found, a module
177named <tt>jit.&lt;cmd&gt;</tt> is loaded and the <tt>start()</tt>
178function of the module is called with the specified arguments (if
179any). The space between <tt>-j</tt> and <tt>cmd</tt> is optional.
180</p>
181<p>
182Here are the available LuaJIT control commands:
183</p>
184<ul>
185<li id="j_on"><tt>-jon</tt> &mdash; Turns the JIT compiler on (default).</li>
186<li id="j_off"><tt>-joff</tt> &mdash; Turns the JIT compiler off (only use the interpreter).</li>
187<li id="j_flush"><tt>-jflush</tt> &mdash; Flushes the whole cache of compiled code.</li>
188<li id="j_v"><tt>-jv</tt> &mdash; Shows verbose information about the progress of the JIT compiler.</li>
189<li id="j_dump"><tt>-jdump</tt> &mdash; Dumps the code and structures used in various compiler stages.</li>
190</ul>
191<p>
192The <tt>-jv</tt> and <tt>-jdump</tt> commands are extension modules
193written in Lua. They are mainly used for debugging the JIT compiler
194itself. For a description of their options and output format, please
195read the comment block at the start of their source.
196They can be found in the <tt>lib</tt> directory of the source
197distribution or installed under the <tt>jit</tt> directory. By default
198this is <tt>/usr/local/share/luajit-2.0.0-beta9/jit</tt> on POSIX
199systems.
200</p>
201
202<h3 id="opt_O"><tt>-O[level]</tt><br>
203<tt>-O[+]flag</tt>&nbsp;&nbsp;&nbsp;<tt>-O-flag</tt><br>
204<tt>-Oparam=value</tt></h3>
205<p>
206This options allows fine-tuned control of the optimizations used by
207the JIT compiler. This is mainly intended for debugging LuaJIT itself.
208Please note that the JIT compiler is extremely fast (we are talking
209about the microsecond to millisecond range). Disabling optimizations
210doesn't have any visible impact on its overhead, but usually generates
211code that runs slower.
212</p>
213<p>
214The first form sets an optimization level &mdash; this enables a
215specific mix of optimization flags. <tt>-O0</tt> turns off all
216optimizations and higher numbers enable more optimizations. Omitting
217the level (i.e. just <tt>-O</tt>) sets the default optimization level,
218which is <tt>-O3</tt> in the current version.
219</p>
220<p>
221The second form adds or removes individual optimization flags.
222The third form sets a parameter for the VM or the JIT compiler
223to a specific value.
224</p>
225<p>
226You can either use this option multiple times (like <tt>-Ocse
227-O-dce -Ohotloop=10</tt>) or separate several settings with a comma
228(like <tt>-O+cse,-dce,hotloop=10</tt>). The settings are applied from
229left to right and later settings override earlier ones. You can freely
230mix the three forms, but note that setting an optimization level
231overrides all earlier flags.
232</p>
233<p>
234Here are the available flags and at what optimization levels they
235are enabled:
236</p>
237<table class="opt">
238<tr class="opthead">
239<td class="flag_name">Flag</td>
240<td class="flag_level">-O1</td>
241<td class="flag_level">-O2</td>
242<td class="flag_level">-O3</td>
243<td class="flag_desc">&nbsp;</td>
244</tr>
245<tr class="odd separate">
246<td class="flag_name">fold</td><td class="flag_level">&bull;</td><td class="flag_level">&bull;</td><td class="flag_level">&bull;</td><td class="flag_desc">Constant Folding, Simplifications and Reassociation</td></tr>
247<tr class="even">
248<td class="flag_name">cse</td><td class="flag_level">&bull;</td><td class="flag_level">&bull;</td><td class="flag_level">&bull;</td><td class="flag_desc">Common-Subexpression Elimination</td></tr>
249<tr class="odd">
250<td class="flag_name">dce</td><td class="flag_level">&bull;</td><td class="flag_level">&bull;</td><td class="flag_level">&bull;</td><td class="flag_desc">Dead-Code Elimination</td></tr>
251<tr class="even">
252<td class="flag_name">narrow</td><td class="flag_level">&nbsp;</td><td class="flag_level">&bull;</td><td class="flag_level">&bull;</td><td class="flag_desc">Narrowing of numbers to integers</td></tr>
253<tr class="odd">
254<td class="flag_name">loop</td><td class="flag_level">&nbsp;</td><td class="flag_level">&bull;</td><td class="flag_level">&bull;</td><td class="flag_desc">Loop Optimizations (code hoisting)</td></tr>
255<tr class="even">
256<td class="flag_name">fwd</td><td class="flag_level">&nbsp;</td><td class="flag_level">&nbsp;</td><td class="flag_level">&bull;</td><td class="flag_desc">Load Forwarding (L2L) and Store Forwarding (S2L)</td></tr>
257<tr class="odd">
258<td class="flag_name">dse</td><td class="flag_level">&nbsp;</td><td class="flag_level">&nbsp;</td><td class="flag_level">&bull;</td><td class="flag_desc">Dead-Store Elimination</td></tr>
259<tr class="even">
260<td class="flag_name">abc</td><td class="flag_level">&nbsp;</td><td class="flag_level">&nbsp;</td><td class="flag_level">&bull;</td><td class="flag_desc">Array Bounds Check Elimination</td></tr>
261<tr class="odd">
262<td class="flag_name">fuse</td><td class="flag_level">&nbsp;</td><td class="flag_level">&nbsp;</td><td class="flag_level">&bull;</td><td class="flag_desc">Fusion of operands into instructions</td></tr>
263</table>
264<p>
265Here are the parameters and their default settings:
266</p>
267<table class="opt">
268<tr class="opthead">
269<td class="param_name">Parameter</td>
270<td class="param_default">Default</td>
271<td class="param_desc">&nbsp;</td>
272</tr>
273<tr class="odd separate">
274<td class="param_name">maxtrace</td><td class="param_default">1000</td><td class="param_desc">Max. number of traces in the cache</td></tr>
275<tr class="even">
276<td class="param_name">maxrecord</td><td class="param_default">4000</td><td class="param_desc">Max. number of recorded IR instructions</td></tr>
277<tr class="odd">
278<td class="param_name">maxirconst</td><td class="param_default">500</td><td class="param_desc">Max. number of IR constants of a trace</td></tr>
279<tr class="even">
280<td class="param_name">maxside</td><td class="param_default">100</td><td class="param_desc">Max. number of side traces of a root trace</td></tr>
281<tr class="odd">
282<td class="param_name">maxsnap</td><td class="param_default">500</td><td class="param_desc">Max. number of snapshots for a trace</td></tr>
283<tr class="even separate">
284<td class="param_name">hotloop</td><td class="param_default">56</td><td class="param_desc">Number of iterations to detect a hot loop or hot call</td></tr>
285<tr class="odd">
286<td class="param_name">hotexit</td><td class="param_default">10</td><td class="param_desc">Number of taken exits to start a side trace</td></tr>
287<tr class="even">
288<td class="param_name">tryside</td><td class="param_default">4</td><td class="param_desc">Number of attempts to compile a side trace</td></tr>
289<tr class="odd separate">
290<td class="param_name">instunroll</td><td class="param_default">4</td><td class="param_desc">Max. unroll factor for instable loops</td></tr>
291<tr class="even">
292<td class="param_name">loopunroll</td><td class="param_default">15</td><td class="param_desc">Max. unroll factor for loop ops in side traces</td></tr>
293<tr class="odd">
294<td class="param_name">callunroll</td><td class="param_default">3</td><td class="param_desc">Max. unroll factor for pseudo-recursive calls</td></tr>
295<tr class="even">
296<td class="param_name">recunroll</td><td class="param_default">2</td><td class="param_desc">Min. unroll factor for true recursion</td></tr>
297<tr class="odd separate">
298<td class="param_name">sizemcode</td><td class="param_default">32</td><td class="param_desc">Size of each machine code area in KBytes (Windows: 64K)</td></tr>
299<tr class="even">
300<td class="param_name">maxmcode</td><td class="param_default">512</td><td class="param_desc">Max. total size of all machine code areas in KBytes</td></tr>
301</table>
302<br class="flush">
303</div>
304<div id="foot">
305<hr class="hide">
306Copyright &copy; 2005-2011 Mike Pall
307<span class="noprint">
308&middot;
309<a href="contact.html">Contact</a>
310</span>
311</div>
312</body>
313</html>
diff --git a/libraries/luajit-2.0/doc/status.html b/libraries/luajit-2.0/doc/status.html
new file mode 100644
index 0000000..d9cffe0
--- /dev/null
+++ b/libraries/luajit-2.0/doc/status.html
@@ -0,0 +1,240 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
2<html>
3<head>
4<title>Status &amp; Roadmap</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<style type="text/css">
12ul li { padding-bottom: 0.3em; }
13</style>
14</head>
15<body>
16<div id="site">
17<a href="http://luajit.org"><span>Lua<span id="logo">JIT</span></span></a>
18</div>
19<div id="head">
20<h1>Status &amp; Roadmap</h1>
21</div>
22<div id="nav">
23<ul><li>
24<a href="luajit.html">LuaJIT</a>
25<ul><li>
26<a href="install.html">Installation</a>
27</li><li>
28<a href="running.html">Running</a>
29</li></ul>
30</li><li>
31<a href="extensions.html">Extensions</a>
32<ul><li>
33<a href="ext_ffi.html">FFI Library</a>
34<ul><li>
35<a href="ext_ffi_tutorial.html">FFI Tutorial</a>
36</li><li>
37<a href="ext_ffi_api.html">ffi.* API</a>
38</li><li>
39<a href="ext_ffi_semantics.html">FFI Semantics</a>
40</li></ul>
41</li><li>
42<a href="ext_jit.html">jit.* Library</a>
43</li><li>
44<a href="ext_c_api.html">Lua/C API</a>
45</li></ul>
46</li><li>
47<a class="current" href="status.html">Status</a>
48<ul><li>
49<a href="changes.html">Changes</a>
50</li></ul>
51</li><li>
52<a href="faq.html">FAQ</a>
53</li><li>
54<a href="http://luajit.org/performance.html">Performance <span class="ext">&raquo;</span></a>
55</li><li>
56<a href="http://luajit.org/download.html">Download <span class="ext">&raquo;</span></a>
57</li></ul>
58</div>
59<div id="main">
60<p>
61The <span style="color: #0000c0;">LuaJIT 1.x</span> series represents
62the current <span style="color: #0000c0;">stable branch</span>.
63Only a single bug has been discovered in the last two years. So, if
64you need a rock-solid VM, you are encouraged to fetch the latest
65release of LuaJIT 1.x from the <a href="http://luajit.org/download.html"><span class="ext">&raquo;</span>&nbsp;Download</a>
66page.
67</p>
68<p>
69<span style="color: #c00000;">LuaJIT 2.0</span> is the currently active
70<span style="color: #c00000;">development branch</span>.
71It has <b>Beta Test</b> status and is still undergoing
72substantial changes.
73It has <a href="http://luajit.org/performance.html"><span class="ext">&raquo;</span>&nbsp;much better performance</a> than LuaJIT 1.x.
74It's maturing quickly, so you should definitely
75start to evaluate it for new projects right now.
76</p>
77
78<h2>Current Status</h2>
79<p>
80This is a list of the things you should know about the LuaJIT 2.0 beta test:
81</p>
82<ul>
83<li>
84Obviously there will be some <b>bugs</b> in a VM which has been
85rewritten from the ground up. Please report your findings together with
86the circumstances needed to reproduce the bug. If possible, reduce the
87problem down to a simple test case.<br>
88There is no formal bug tracker at the moment. The best place for
89discussion is the
90<a href="http://www.lua.org/lua-l.html"><span class="ext">&raquo;</span>&nbsp;Lua mailing list</a>. Of course
91you may also send your bug reports <a href="contact.html">directly to me</a>,
92especially when they contain lengthy debug output or if you require
93confidentiality.
94</li>
95<li>
96The x86 JIT compiler only generates code for CPUs with support for
97<b>SSE2</b> instructions. I.e. you need at least a P4, Core 2/i3/i5/i7,
98Atom or K8/K10 to get the full benefit.<br>
99If you run LuaJIT on older CPUs without SSE2 support, the JIT compiler
100is disabled and the VM falls back to the LuaJIT interpreter. This is faster
101than the Lua interpreter, but not nearly as fast as the JIT compiler of course.
102Run the command line executable without arguments to show the current status
103(<tt>JIT: ON</tt> or <tt>JIT: OFF</tt>).
104</li>
105<li>
106The VM is complete in the sense that it <b>should</b> run all Lua code
107just fine. It's considered a serious bug if the VM crashes or produces
108unexpected results &mdash; please report this. There are only very few
109known incompatibilities with standard Lua:
110<ul>
111<li>
112The Lua <b>debug API</b> is missing a couple of features (return
113hooks for non-Lua functions) and shows slightly different behavior
114(no per-coroutine hooks, no tail call counting).
115</li>
116<li>
117Some of the <b>configuration options</b> of Lua&nbsp;5.1 are not supported:
118<ul>
119<li>The <b>number type</b> cannot be changed (it's always a <tt>double</tt>).</li>
120<li>The stand-alone executable cannot be linked with <b>readline</b>
121to enable line editing. It's planned to add support for loading it
122on-demand.</li>
123</ul>
124</li>
125<li>
126Most other issues you're likely to find (e.g. with the existing test
127suites) are differences in the <b>implementation-defined</b> behavior.
128These either have a good reason (like early tail call resolving which
129may cause differences in error reporting), are arbitrary design choices
130or are due to quirks in the VM. The latter cases may get fixed if a
131demonstrable need is shown.
132</li>
133</ul>
134</li>
135<li>
136The <b>JIT compiler</b> falls back to the
137interpreter in some cases. All of this works transparently, so unless
138you use <tt>-jv</tt>, you'll probably never notice (the interpreter is
139<a href="http://luajit.org/performance.html"><span class="ext">&raquo;</span>&nbsp;quite fast</a>, too). Here are the known issues:
140<ul>
141<li>
142Most known issues cause a <b>NYI</b> (not yet implemented) trace abort
143message. E.g. for calls to some internal library
144functions. Reporting these is only mildly useful, except if you have good
145example code that shows the problem. Obviously, reports accompanied with
146a patch to fix the issue are more than welcome. But please check back
147with me, before writing major improvements, to avoid duplication of
148effort.
149</li>
150<li>
151Some checks are missing in the JIT-compiled code for obscure situations
152with <b>open upvalues aliasing</b> one of the SSA slots later on (or
153vice versa). Bonus points, if you can find a real world test case for
154this.
155</li>
156<li>
157Currently some <b>out-of-memory</b> errors from <b>on-trace code</b> are not
158handled correctly. The error may fall through an on-trace
159<tt>pcall</tt> (x86) or it may be passed on to the function set with
160<tt>lua_atpanic</tt> (x64).
161</li>
162</ul>
163</li>
164</ul>
165
166<h2>Roadmap</h2>
167<p>
168Please refer to the
169<a href="http://lua-users.org/lists/lua-l/2011-01/msg01238.html"><span class="ext">&raquo;</span>&nbsp;LuaJIT
170Roadmap 2011</a> for the latest release plan. Here's the general
171project plan for LuaJIT 2.0:
172</p>
173<ul>
174<li>
175The main goal right now is to stabilize LuaJIT 2.0 and get it out of
176beta test. <b>Correctness</b> has priority over completeness. This
177implies the first stable release will certainly NOT compile every
178library function call and will fall back to the interpreter from time
179to time. This is perfectly ok, since it still executes all Lua code,
180just not at the highest possible speed.
181</li>
182<li>
183The next step is to get it to compile more library functions and handle
184more cases where the compiler currently bails out. This doesn't mean it
185will compile every corner case. It's much more important that it
186performs well in a majority of use cases. Every compiler has to make
187these trade-offs &mdash; <b>completeness</b> just cannot be the
188overriding goal for a low-footprint, low-overhead JIT compiler.
189</li>
190<li>
191More <b>optimizations</b> will be added in parallel to the last step on
192an as-needed basis. Sinking of stores
193to aggregates and sinking of allocations are high on the list.
194More complex optimizations with less pay-off, such as value-range-propagation
195(VRP) will have to wait.
196</li>
197<li>
198LuaJIT 2.0 has been designed with <b>portability</b> in mind.
199Nonetheless, it compiles to native code and needs to be adapted to each
200architecture. The two major work items are porting the the fast interpreter,
201which is written in assembler, and porting the compiler backend.
202Most other portability issues like endianess or 32 vs. 64&nbsp;bit CPUs
203have already been taken care of.<br>
204Several ports are already available, thanks to the
205<a href="http://luajit.org/sponsors.html"><span class="ext">&raquo;</span>&nbsp;LuaJIT sponsorship program</a>.
206More ports will follow in the future &mdash; companies which are
207interested in sponsoring a port to a particular architecture, please
208use the given contact address.
209</li>
210<li>
211<b>Documentation</b> about the <b>internals</b> of LuaJIT is still sorely
212missing. Although the source code is included and is IMHO well
213commented, many basic design decisions are in need of an explanation.
214The rather un-traditional compiler architecture and the many highly
215optimized data structures are a barrier for outside participation in
216the development. Alas, as I've repeatedly stated, I'm better at
217writing code than papers and I'm not in need of any academic merits.
218Someday I will find the time for it. :-)
219</li>
220<li>
221Producing good code for unbiased branches is a key problem for trace
222compilers. This is the main cause for "trace explosion".
223<b>Hyperblock scheduling</b> promises to solve this nicely at the
224price of a major redesign of the compiler. This would also pave the
225way for emitting predicated instructions, which is a prerequisite
226for efficient <b>vectorization</b>.
227</li>
228</ul>
229<br class="flush">
230</div>
231<div id="foot">
232<hr class="hide">
233Copyright &copy; 2005-2011 Mike Pall
234<span class="noprint">
235&middot;
236<a href="contact.html">Contact</a>
237</span>
238</div>
239</body>
240</html>
generated by cgit v1.1 at 2024-07-05 07:46:24 +0000