diff options
author | David Walter Seikel | 2014-01-13 21:08:31 +1000 |
---|---|---|
committer | David Walter Seikel | 2014-01-13 21:08:31 +1000 |
commit | 637177eb1397ef1800027bccd50dbdc1af29a15b (patch) | |
tree | 3670a48303d05fceb8bf3ec4ee2901b72fe62d4d /libraries/luajit-2.0/doc | |
parent | Update Irrlicht to 1.8.1. Include actual change markers this time. lol (diff) | |
download | SledjHamr-637177eb1397ef1800027bccd50dbdc1af29a15b.zip SledjHamr-637177eb1397ef1800027bccd50dbdc1af29a15b.tar.gz SledjHamr-637177eb1397ef1800027bccd50dbdc1af29a15b.tar.bz2 SledjHamr-637177eb1397ef1800027bccd50dbdc1af29a15b.tar.xz |
Remove LuaJIT source, we can use packaged LuaJIT 2.0 release now.
Also some cleanups related to the other library removals.
Diffstat (limited to 'libraries/luajit-2.0/doc')
-rw-r--r-- | libraries/luajit-2.0/doc/bluequad-print.css | 166 | ||||
-rw-r--r-- | libraries/luajit-2.0/doc/bluequad.css | 306 | ||||
-rw-r--r-- | libraries/luajit-2.0/doc/changes.html | 640 | ||||
-rw-r--r-- | libraries/luajit-2.0/doc/contact.html | 98 | ||||
-rw-r--r-- | libraries/luajit-2.0/doc/ext_c_api.html | 183 | ||||
-rw-r--r-- | libraries/luajit-2.0/doc/ext_ffi.html | 332 | ||||
-rw-r--r-- | libraries/luajit-2.0/doc/ext_ffi_api.html | 553 | ||||
-rw-r--r-- | libraries/luajit-2.0/doc/ext_ffi_semantics.html | 1146 | ||||
-rw-r--r-- | libraries/luajit-2.0/doc/ext_ffi_tutorial.html | 598 | ||||
-rw-r--r-- | libraries/luajit-2.0/doc/ext_jit.html | 195 | ||||
-rw-r--r-- | libraries/luajit-2.0/doc/extensions.html | 336 | ||||
-rw-r--r-- | libraries/luajit-2.0/doc/faq.html | 180 | ||||
-rw-r--r-- | libraries/luajit-2.0/doc/img/contact.png | bin | 1340 -> 0 bytes | |||
-rw-r--r-- | libraries/luajit-2.0/doc/install.html | 543 | ||||
-rw-r--r-- | libraries/luajit-2.0/doc/luajit.html | 142 | ||||
-rw-r--r-- | libraries/luajit-2.0/doc/running.html | 313 | ||||
-rw-r--r-- | libraries/luajit-2.0/doc/status.html | 240 |
17 files changed, 0 insertions, 5971 deletions
diff --git a/libraries/luajit-2.0/doc/bluequad-print.css b/libraries/luajit-2.0/doc/bluequad-print.css deleted file mode 100644 index 69c07d6..0000000 --- a/libraries/luajit-2.0/doc/bluequad-print.css +++ /dev/null | |||
@@ -1,166 +0,0 @@ | |||
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 | body { | ||
7 | font-family: serif; | ||
8 | font-size: 11pt; | ||
9 | margin: 0 3em; | ||
10 | padding: 0; | ||
11 | border: none; | ||
12 | } | ||
13 | a:link, a:visited, a:hover, a:active { | ||
14 | text-decoration: none; | ||
15 | background: transparent; | ||
16 | color: #0000ff; | ||
17 | } | ||
18 | h1, h2, h3 { | ||
19 | font-family: sans-serif; | ||
20 | font-weight: bold; | ||
21 | text-align: left; | ||
22 | margin: 0.5em 0; | ||
23 | padding: 0; | ||
24 | } | ||
25 | h1 { | ||
26 | font-size: 200%; | ||
27 | } | ||
28 | h2 { | ||
29 | font-size: 150%; | ||
30 | } | ||
31 | h3 { | ||
32 | font-size: 125%; | ||
33 | } | ||
34 | p { | ||
35 | margin: 0 0 0.5em 0; | ||
36 | padding: 0; | ||
37 | } | ||
38 | ul, ol { | ||
39 | margin: 0.5em 0; | ||
40 | padding: 0 0 0 2em; | ||
41 | } | ||
42 | ul { | ||
43 | list-style: outside square; | ||
44 | } | ||
45 | ol { | ||
46 | list-style: outside decimal; | ||
47 | } | ||
48 | li { | ||
49 | margin: 0; | ||
50 | padding: 0; | ||
51 | } | ||
52 | dl { | ||
53 | margin: 1em 0; | ||
54 | padding: 1em; | ||
55 | border: 1px solid black; | ||
56 | } | ||
57 | dt { | ||
58 | font-weight: bold; | ||
59 | margin: 0; | ||
60 | padding: 0; | ||
61 | } | ||
62 | dt sup { | ||
63 | float: right; | ||
64 | margin-left: 1em; | ||
65 | } | ||
66 | dd { | ||
67 | margin: 0.5em 0 0 2em; | ||
68 | padding: 0; | ||
69 | } | ||
70 | table { | ||
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 | } | ||
79 | tr { | ||
80 | margin: 0; | ||
81 | padding: 0; | ||
82 | border: none; | ||
83 | } | ||
84 | td { | ||
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 | } | ||
91 | tr.separate td { | ||
92 | border-top: double; | ||
93 | } | ||
94 | tt, pre, code, kbd, samp { | ||
95 | font-family: monospace; | ||
96 | font-size: 75%; | ||
97 | } | ||
98 | kbd { | ||
99 | font-weight: bolder; | ||
100 | } | ||
101 | blockquote, pre { | ||
102 | margin: 1em 2em; | ||
103 | padding: 0; | ||
104 | } | ||
105 | img { | ||
106 | border: none; | ||
107 | vertical-align: baseline; | ||
108 | margin: 0; | ||
109 | padding: 0; | ||
110 | } | ||
111 | img.left { | ||
112 | float: left; | ||
113 | margin: 0.5em 1em 0.5em 0; | ||
114 | } | ||
115 | img.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 deleted file mode 100644 index 49849fb..0000000 --- a/libraries/luajit-2.0/doc/bluequad.css +++ /dev/null | |||
@@ -1,306 +0,0 @@ | |||
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 | */ | ||
20 | body { | ||
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 | } | ||
29 | a:link { | ||
30 | text-decoration: none; | ||
31 | background: transparent; | ||
32 | color: #2142bf; | ||
33 | } | ||
34 | a:visited { | ||
35 | text-decoration: none; | ||
36 | background: transparent; | ||
37 | color: #8122bf; | ||
38 | } | ||
39 | a:hover, a:active { | ||
40 | text-decoration: underline; | ||
41 | background: transparent; | ||
42 | color: #ff0000; | ||
43 | } | ||
44 | h1, h2, h3 { | ||
45 | font-weight: bold; | ||
46 | text-align: left; | ||
47 | margin: 0.5em 0; | ||
48 | padding: 0; | ||
49 | background: transparent; | ||
50 | } | ||
51 | h1 { | ||
52 | font-size: 200%; | ||
53 | line-height: 3em; /* really 6em relative to body, match #site span */ | ||
54 | margin: 0; | ||
55 | } | ||
56 | h2 { | ||
57 | font-size: 150%; | ||
58 | color: #606060; | ||
59 | } | ||
60 | h3 { | ||
61 | font-size: 125%; | ||
62 | color: #404040; | ||
63 | } | ||
64 | p { | ||
65 | max-width: 600px; | ||
66 | margin: 0 0 0.5em 0; | ||
67 | padding: 0; | ||
68 | } | ||
69 | b { | ||
70 | color: #404040; | ||
71 | } | ||
72 | ul, ol { | ||
73 | max-width: 600px; | ||
74 | margin: 0.5em 0; | ||
75 | padding: 0 0 0 2em; | ||
76 | } | ||
77 | ul { | ||
78 | list-style: outside square; | ||
79 | } | ||
80 | ol { | ||
81 | list-style: outside decimal; | ||
82 | } | ||
83 | li { | ||
84 | margin: 0; | ||
85 | padding: 0; | ||
86 | } | ||
87 | dl { | ||
88 | max-width: 600px; | ||
89 | margin: 1em 0; | ||
90 | padding: 1em; | ||
91 | border: 1px solid #bfcfff; | ||
92 | background: #f0f4ff; | ||
93 | } | ||
94 | dt { | ||
95 | font-weight: bold; | ||
96 | margin: 0; | ||
97 | padding: 0; | ||
98 | } | ||
99 | dt sup { | ||
100 | float: right; | ||
101 | margin-left: 1em; | ||
102 | color: #808080; | ||
103 | } | ||
104 | dt a:visited { | ||
105 | text-decoration: none; | ||
106 | color: #2142bf; | ||
107 | } | ||
108 | dt a:hover, dt a:active { | ||
109 | text-decoration: none; | ||
110 | color: #ff0000; | ||
111 | } | ||
112 | dd { | ||
113 | margin: 0.5em 0 0 2em; | ||
114 | padding: 0; | ||
115 | } | ||
116 | div.tablewrap { /* for IE *sigh* */ | ||
117 | max-width: 600px; | ||
118 | } | ||
119 | table { | ||
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 | } | ||
129 | tr { | ||
130 | margin: 0; | ||
131 | padding: 0; | ||
132 | border: none; | ||
133 | } | ||
134 | tr.odd { | ||
135 | background: #f0f4ff; | ||
136 | } | ||
137 | tr.separate td { | ||
138 | border-top: 1px solid #bfcfff; | ||
139 | } | ||
140 | td { | ||
141 | text-align: left; | ||
142 | margin: 0; | ||
143 | padding: 0.2em 0.5em; | ||
144 | border: none; | ||
145 | } | ||
146 | tt, code, kbd, samp { | ||
147 | font-family: Courier New, Courier, monospace; | ||
148 | line-height: 1.2; | ||
149 | font-size: 110%; | ||
150 | } | ||
151 | kbd { | ||
152 | font-weight: bolder; | ||
153 | } | ||
154 | blockquote, pre { | ||
155 | max-width: 600px; | ||
156 | margin: 1em 2em; | ||
157 | padding: 0; | ||
158 | } | ||
159 | pre { | ||
160 | line-height: 1.1; | ||
161 | } | ||
162 | pre.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 | } | ||
169 | img { | ||
170 | border: none; | ||
171 | vertical-align: baseline; | ||
172 | margin: 0; | ||
173 | padding: 0; | ||
174 | } | ||
175 | img.left { | ||
176 | float: left; | ||
177 | margin: 0.5em 1em 0.5em 0; | ||
178 | } | ||
179 | img.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 deleted file mode 100644 index 51027a9..0000000 --- a/libraries/luajit-2.0/doc/changes.html +++ /dev/null | |||
@@ -1,640 +0,0 @@ | |||
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"> | ||
12 | div.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">»</span></a> | ||
55 | </li><li> | ||
56 | <a href="http://luajit.org/download.html">Download <span class="ext">»</span></a> | ||
57 | </li></ul> | ||
58 | </div> | ||
59 | <div id="main"> | ||
60 | <p> | ||
61 | This is a list of changes between the released versions of LuaJIT.<br> | ||
62 | The current <span style="color: #c00000;">development version</span> is <strong>LuaJIT 2.0.0-beta9</strong>.<br> | ||
63 | The current <span style="color: #0000c0;">stable version</span> is <strong>LuaJIT 1.1.7</strong>. | ||
64 | </p> | ||
65 | <p> | ||
66 | Please check the | ||
67 | <a href="http://luajit.org/changes.html"><span class="ext">»</span> Online Change History</a> | ||
68 | to 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 — 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> | ||
78 | at 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> | ||
81 | files 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 | ||
84 | sequences.</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 | ||
122 | resolving, 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 | ||
140 | trace-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 — 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 | ||
151 | option.</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> | ||
171 | around 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<... *>: 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 — 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 — 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 — 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 — 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 — 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> | ||
365 | and <tt>math.random()</tt>.</li> | ||
366 | </ul></li> | ||
367 | </ul> | ||
368 | |||
369 | <h2 id="LuaJIT-2.0.0-beta2">LuaJIT 2.0.0-beta2 — 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 | ||
373 | using 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. | ||
385 | Prevent 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 /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 | ||
395 | negative arguments, too.<br> | ||
396 | This 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 — 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 | ||
403 | no 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 — 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">»</span> currently known bugs in Lua 5.1.4</a>.</li> | ||
412 | </ul> | ||
413 | |||
414 | <h2 id="LuaJIT-1.1.6">LuaJIT 1.1.6 — 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">»</span> currently known bugs in Lua 5.1.4</a>.</li> | ||
418 | <li>Removed wrong GC check in <tt>jit_createstate()</tt>. | ||
419 | Thanks 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 — 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">»</span> known bugs in Lua 5.1.3</a>.</li> | ||
428 | </ul> | ||
429 | |||
430 | <h2 id="LuaJIT-1.1.4">LuaJIT 1.1.4 — 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">»</span> 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 — 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">»</span> 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 trace=-</tt>).</li> | ||
450 | </ul> | ||
451 | |||
452 | <h2 id="LuaJIT-1.1.2">LuaJIT 1.1.2 — 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: | ||
457 | make values of consts used as lightuserdata keys unique | ||
458 | to avoid joining by the compiler/linker.</li> | ||
459 | </ul> | ||
460 | |||
461 | <h2 id="LuaJIT-1.1.1">LuaJIT 1.1.1 — 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">»</span> 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 | ||
467 | for some immediates.</li> | ||
468 | </ul> | ||
469 | <p> | ||
470 | This release is in sync with Coco 1.1.1 (see the | ||
471 | <a href="http://coco.luajit.org/changes.html"><span class="ext">»</span> Coco Change History</a>). | ||
472 | </p> | ||
473 | |||
474 | <h2 id="LuaJIT-1.1.0">LuaJIT 1.1.0 — 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). | ||
481 | Mandatory 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 | ||
484 | OP_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 | ||
490 | forwarding stalls.</li> | ||
491 | <li>Use (scalar) SSE2 ops (if the CPU supports it) to speed up slot moves | ||
492 | and 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>). | ||
495 | With 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 | ||
497 | use <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 | ||
505 | supports index chains, too.</li> | ||
506 | <li>Generate type hints for arithmetic and comparison operators, | ||
507 | OP_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 | ||
516 | instruction is recompiled and patched on-the-fly. | ||
517 | Regular programs will trigger deoptimization only occasionally.</li> | ||
518 | <li>This avoids generating code for uncommon fallback cases | ||
519 | most of the time. Generated code is up to 30% smaller compared to | ||
520 | LuaJIT 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, | ||
527 | OP_FORPREP: operand type and range mismatches.</li> | ||
528 | </ul></li> | ||
529 | <li>Complete redesign of the debug and traceback info | ||
530 | (bytecode ↔ mcode) to support deoptimization. | ||
531 | Much 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> | ||
554 | and <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 | ||
558 | on ndisasm anymore. Flexible API, very compact (500 lines) | ||
559 | and complete (x87, MMX, SSE, SSE2, SSE3, SSSE3, privileged instructions).</li> | ||
560 | <li><tt>luajit -v</tt> prints the LuaJIT version and copyright | ||
561 | on 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> | ||
569 | This release is in sync with Coco 1.1.0 (see the | ||
570 | <a href="http://coco.luajit.org/changes.html"><span class="ext">»</span> 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 — 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> | ||
584 | This is the first public release of LuaJIT. | ||
585 | </p> | ||
586 | |||
587 | <h2 id="LuaJIT-1.0.2">LuaJIT 1.0.2 — 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 | ||
592 | variant for POSIX systems.</li> | ||
593 | <li>Reorganized the C function signature handling in | ||
594 | <tt>jit.opt_lib</tt>.</li> | ||
595 | <li>Changed to index-based hints for inlining C functions. | ||
596 | Still 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> | ||
604 | Not released because Lua 5.1 alpha came out today. | ||
605 | </p> | ||
606 | |||
607 | <h2 id="LuaJIT-1.0.1">LuaJIT 1.0.1 — 2005-08-31</h2> | ||
608 | <ul> | ||
609 | <li>Missing GC step in <tt>OP_CONCAT</tt>.</li> | ||
610 | <li>Fix result handling for C –> 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> | ||
620 | Interim non-public release. | ||
621 | Special 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 — 2005-08-29</h2> | ||
625 | <p> | ||
626 | This 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"> | ||
633 | Copyright © 2005-2011 Mike Pall | ||
634 | <span class="noprint"> | ||
635 | · | ||
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 deleted file mode 100644 index a85c488..0000000 --- a/libraries/luajit-2.0/doc/contact.html +++ /dev/null | |||
@@ -1,98 +0,0 @@ | |||
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">»</span></a> | ||
52 | </li><li> | ||
53 | <a href="http://luajit.org/download.html">Download <span class="ext">»</span></a> | ||
54 | </li></ul> | ||
55 | </div> | ||
56 | <div id="main"> | ||
57 | <p> | ||
58 | Please send general questions to the | ||
59 | <a href="http://www.lua.org/lua-l.html"><span class="ext">»</span> Lua mailing list</a>. | ||
60 | You can also send any questions you have directly to me: | ||
61 | </p> | ||
62 | |||
63 | <script type="text/javascript"> | ||
64 | <!-- | ||
65 | var 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;} | ||
68 | document.write("<"+"p>"+r+"<"+"/p>\n");} | ||
69 | //--> | ||
70 | </script> | ||
71 | <script type="text/javascript"> | ||
72 | <!-- | ||
73 | xD("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> | ||
82 | All documentation is | ||
83 | Copyright © 2005-2011 Mike Pall. | ||
84 | </p> | ||
85 | |||
86 | |||
87 | <br class="flush"> | ||
88 | </div> | ||
89 | <div id="foot"> | ||
90 | <hr class="hide"> | ||
91 | Copyright © 2005-2011 Mike Pall | ||
92 | <span class="noprint"> | ||
93 | · | ||
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 deleted file mode 100644 index 35e2234..0000000 --- a/libraries/luajit-2.0/doc/ext_c_api.html +++ /dev/null | |||
@@ -1,183 +0,0 @@ | |||
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">»</span></a> | ||
52 | </li><li> | ||
53 | <a href="http://luajit.org/download.html">Download <span class="ext">»</span></a> | ||
54 | </li></ul> | ||
55 | </div> | ||
56 | <div id="main"> | ||
57 | <p> | ||
58 | LuaJIT adds some extensions to the standard Lua/C API. The LuaJIT include | ||
59 | directory must be in the compiler search path (<tt>-I<i>path</i></tt>) | ||
60 | to be able to include the required header for C code: | ||
61 | </p> | ||
62 | <pre class="code"> | ||
63 | #include "luajit.h" | ||
64 | </pre> | ||
65 | <p> | ||
66 | Or 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 | — Control VM</h2> | ||
74 | <p> | ||
75 | This is a C API extension to allow control of the VM from C code. The | ||
76 | full prototype of <tt>LuaJIT_setmode</tt> is: | ||
77 | </p> | ||
78 | <pre class="code"> | ||
79 | LUA_API int luaJIT_setmode(lua_State *L, int idx, int mode); | ||
80 | </pre> | ||
81 | <p> | ||
82 | The returned status is either success (<tt>1</tt>) or failure (<tt>0</tt>). | ||
83 | The second argument is either <tt>0</tt> or a stack index (similar to the | ||
84 | other Lua/C API functions). | ||
85 | </p> | ||
86 | <p> | ||
87 | The third argument specifies the mode, which is 'or'ed with a flag. | ||
88 | The 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> | ||
93 | The 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> | ||
98 | Turn 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> | ||
105 | This sets the mode for the function at the stack index <tt>idx</tt> or | ||
106 | the parent of the calling function (<tt>idx = 0</tt>). It either | ||
107 | enables JIT compilation for a function, disables it and flushes any | ||
108 | already compiled code or only flushes already compiled code. This | ||
109 | applies 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 | LUAJIT_MODE_TRACE|LUAJIT_MODE_FLUSH)</tt></h3> | ||
116 | <p> | ||
117 | Flushes the specified root trace and all of its side traces from the cache. | ||
118 | The code for the trace will be retained as long as there are any other | ||
119 | traces 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> | ||
124 | This mode defines a wrapper function for calls to C functions. If | ||
125 | called with <tt>LUAJIT_MODE_ON</tt>, the stack index at <tt>idx</tt> | ||
126 | must be a <tt>lightuserdata</tt> object holding a pointer to the wrapper | ||
127 | function. From now on all C functions are called through the wrapper | ||
128 | function. If called with <tt>LUAJIT_MODE_OFF</tt> this mode is turned | ||
129 | off and all C functions are directly called. | ||
130 | </p> | ||
131 | <p> | ||
132 | The wrapper function can be used for debugging purposes or to catch | ||
133 | and convert foreign exceptions. But please read the section on | ||
134 | <a href="extensions.html#exceptions">C++ exception interoperability</a> | ||
135 | first. Recommended usage can be seen in this C++ code excerpt: | ||
136 | </p> | ||
137 | <pre class="code"> | ||
138 | #include <exception> | ||
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. | ||
143 | static 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 | |||
157 | static 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> | ||
168 | Note that you can only define <b>a single global wrapper function</b>, | ||
169 | so be careful when using this mechanism from multiple C++ modules. | ||
170 | Also note that this mechanism is not without overhead. | ||
171 | </p> | ||
172 | <br class="flush"> | ||
173 | </div> | ||
174 | <div id="foot"> | ||
175 | <hr class="hide"> | ||
176 | Copyright © 2005-2011 Mike Pall | ||
177 | <span class="noprint"> | ||
178 | · | ||
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 deleted file mode 100644 index 9b59a3f..0000000 --- a/libraries/luajit-2.0/doc/ext_ffi.html +++ /dev/null | |||
@@ -1,332 +0,0 @@ | |||
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"> | ||
12 | span.codemark { position:absolute; left: 16em; color: #4040c0; } | ||
13 | span.mark { color: #4040c0; font-family: Courier New, Courier, monospace; | ||
14 | line-height: 1.1; } | ||
15 | pre.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">»</span></a> | ||
58 | </li><li> | ||
59 | <a href="http://luajit.org/download.html">Download <span class="ext">»</span></a> | ||
60 | </li></ul> | ||
61 | </div> | ||
62 | <div id="main"> | ||
63 | <p> | ||
64 | |||
65 | The FFI library allows <b>calling external C functions</b> and | ||
66 | <b>using C data structures</b> from pure Lua code. | ||
67 | |||
68 | </p> | ||
69 | <p> | ||
70 | |||
71 | The FFI library largely obviates the need to write tedious manual | ||
72 | Lua/C bindings in C. No need to learn a separate binding language | ||
73 | — <b>it parses plain C declarations!</b> These can be | ||
74 | cut-n-pasted from C header files or reference manuals. It's up to | ||
75 | the task of binding large libraries without the need for dealing with | ||
76 | fragile binding generators. | ||
77 | |||
78 | </p> | ||
79 | <p> | ||
80 | The FFI library is tightly integrated into LuaJIT (it's not available | ||
81 | as a separate module). The code generated by the JIT-compiler for | ||
82 | accesses to C data structures from Lua code is on par with the | ||
83 | code a C compiler would generate. Calls to C functions can | ||
84 | be inlined in JIT-compiled code, unlike calls to functions bound via | ||
85 | the classic Lua/C API. | ||
86 | </p> | ||
87 | <p> | ||
88 | This 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> | ||
94 | It's really easy to call an external C library function: | ||
95 | </p> | ||
96 | <pre class="code mark"> | ||
97 | <span class="codemark">① | ||
98 | ② | ||
99 | |||
100 | |||
101 | ③</span>local ffi = require("ffi") | ||
102 | ffi.cdef[[ | ||
103 | <span style="color:#00a000;">int printf(const char *fmt, ...);</span> | ||
104 | ]] | ||
105 | ffi.C.printf("Hello %s!", "world") | ||
106 | </pre> | ||
107 | <p> | ||
108 | So, let's pick that apart: | ||
109 | </p> | ||
110 | <p> | ||
111 | <span class="mark">①</span> Load the FFI library. | ||
112 | </p> | ||
113 | <p> | ||
114 | <span class="mark">②</span> Add a C declaration | ||
115 | for the function. The part inside the double-brackets (in green) is | ||
116 | just standard C syntax. | ||
117 | </p> | ||
118 | <p> | ||
119 | <span class="mark">③</span> Call the named | ||
120 | C function — Yes, it's that simple! | ||
121 | </p> | ||
122 | <p style="font-size: 8pt;"> | ||
123 | Actually, what goes on behind the scenes is far from simple: <span | ||
124 | style="color:#4040c0;">③</span> makes use of the standard | ||
125 | C library namespace <tt>ffi.C</tt>. Indexing this namespace with | ||
126 | a symbol name (<tt>"printf"</tt>) automatically binds it to the the | ||
127 | standard C library. The result is a special kind of object which, | ||
128 | when called, runs the <tt>printf</tt> function. The arguments passed | ||
129 | to this function are automatically converted from Lua objects to the | ||
130 | corresponding C types. | ||
131 | </p> | ||
132 | <p> | ||
133 | Ok, so maybe the use of <tt>printf()</tt> wasn't such a spectacular | ||
134 | example. 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> | ||
138 | So here's something to pop up a message box on Windows: | ||
139 | </p> | ||
140 | <pre class="code"> | ||
141 | local ffi = require("ffi") | ||
142 | ffi.cdef[[ | ||
143 | <span style="color:#00a000;">int MessageBoxA(void *w, const char *txt, const char *cap, int type);</span> | ||
144 | ]] | ||
145 | ffi.C.MessageBoxA(nil, "Hello world!", "Test", 0) | ||
146 | </pre> | ||
147 | <p> | ||
148 | Bing! Again, that was far too easy, no? | ||
149 | </p> | ||
150 | <p style="font-size: 8pt;"> | ||
151 | Compare this with the effort required to bind that function using the | ||
152 | classic Lua/C API: create an extra C file, add a C function | ||
153 | that retrieves and checks the argument types passed from Lua and calls | ||
154 | the actual C function, add a list of module functions and their | ||
155 | names, add a <tt>luaopen_*</tt> function and register all module | ||
156 | functions, compile and link it into a shared library (DLL), move it to | ||
157 | the proper path, add Lua code that loads the module aaaand ... finally | ||
158 | call the binding function. Phew! | ||
159 | </p> | ||
160 | |||
161 | <h2 id="cdata">Motivating Example: Using C Data Structures</h2> | ||
162 | <p> | ||
163 | The FFI library allows you to create and access C data | ||
164 | structures. Of course the main use for this is for interfacing with | ||
165 | C functions. But they can be used stand-alone, too. | ||
166 | </p> | ||
167 | <p> | ||
168 | Lua is built upon high-level data types. They are flexible, extensible | ||
169 | and dynamic. That's why we all love Lua so much. Alas, this can be | ||
170 | inefficient for certain tasks, where you'd really want a low-level | ||
171 | data type. E.g. a large array of a fixed structure needs to be | ||
172 | implemented with a big table holding lots of tiny tables. This imposes | ||
173 | both a substantial memory overhead as well as a performance overhead. | ||
174 | </p> | ||
175 | <p> | ||
176 | Here's a sketch of a library that operates on color images plus a | ||
177 | simple benchmark. First, the plain Lua version: | ||
178 | </p> | ||
179 | <pre class="code"> | ||
180 | local floor = math.floor | ||
181 | |||
182 | local 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 | ||
189 | end | ||
190 | |||
191 | local 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 | ||
196 | end | ||
197 | |||
198 | local N = 400*400 | ||
199 | local img = image_ramp_green(N) | ||
200 | for i=1,1000 do | ||
201 | image_to_grey(img, N) | ||
202 | end | ||
203 | </pre> | ||
204 | <p> | ||
205 | This creates a table with 160.000 pixels, each of which is a table | ||
206 | holding four number values in the range of 0-255. First an image with | ||
207 | a green ramp is created (1D for simplicity), then the image is | ||
208 | converted to greyscale 1000 times. Yes, that's silly, but I was in | ||
209 | need of a simple example ... | ||
210 | </p> | ||
211 | <p> | ||
212 | And here's the FFI version. The modified parts have been marked in | ||
213 | bold: | ||
214 | </p> | ||
215 | <pre class="code mark"> | ||
216 | <span class="codemark">① | ||
217 | |||
218 | |||
219 | |||
220 | |||
221 | |||
222 | ② | ||
223 | |||
224 | ③ | ||
225 | ④ | ||
226 | |||
227 | |||
228 | |||
229 | |||
230 | |||
231 | |||
232 | ③ | ||
233 | ⑤</span><b>local ffi = require("ffi") | ||
234 | ffi.cdef[[ | ||
235 | </b><span style="color:#00a000;">typedef struct { uint8_t red, green, blue, alpha; } rgba_pixel;</span><b> | ||
236 | ]]</b> | ||
237 | |||
238 | local 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 | ||
246 | end | ||
247 | |||
248 | local 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 | ||
253 | end | ||
254 | |||
255 | local N = 400*400 | ||
256 | local img = image_ramp_green(N) | ||
257 | for i=1,1000 do | ||
258 | image_to_grey(img, N) | ||
259 | end | ||
260 | </pre> | ||
261 | <p> | ||
262 | Ok, so that wasn't too difficult: | ||
263 | </p> | ||
264 | <p> | ||
265 | <span class="mark">①</span> First, load the FFI | ||
266 | library and declare the low-level data type. Here we choose a | ||
267 | <tt>struct</tt> which holds four byte fields, one for each component | ||
268 | of a 4x8 bit RGBA pixel. | ||
269 | </p> | ||
270 | <p> | ||
271 | <span class="mark">②</span> Creating the data | ||
272 | structure with <tt>ffi.new()</tt> is straightforward — the | ||
273 | <tt>'?'</tt> is a placeholder for the number of elements of a | ||
274 | variable-length array. | ||
275 | </p> | ||
276 | <p> | ||
277 | <span class="mark">③</span> C arrays are | ||
278 | zero-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 | ||
280 | simplify converting legacy code. | ||
281 | </p> | ||
282 | <p> | ||
283 | <span class="mark">④</span> Since <tt>ffi.new()</tt> | ||
284 | zero-fills the array by default, we only need to set the green and the | ||
285 | alpha fields. | ||
286 | </p> | ||
287 | <p> | ||
288 | <span class="mark">⑤</span> The calls to | ||
289 | <tt>math.floor()</tt> can be omitted here, because floating-point | ||
290 | numbers are already truncated towards zero when converting them to an | ||
291 | integer. This happens implicitly when the number is stored in the | ||
292 | fields of each pixel. | ||
293 | </p> | ||
294 | <p> | ||
295 | Now let's have a look at the impact of the changes: first, memory | ||
296 | consumption for the image is down from 22 Megabytes to | ||
297 | 640 Kilobytes (400*400*4 bytes). That's a factor of 35x less! So, | ||
298 | yes, tables do have a noticeable overhead. BTW: The original program | ||
299 | would consume 40 Megabytes in plain Lua (on x64). | ||
300 | </p> | ||
301 | <p> | ||
302 | Next, performance: the pure Lua version runs in 9.57 seconds (52.9 | ||
303 | seconds with the Lua interpreter) and the FFI version runs in 0.48 | ||
304 | seconds on my machine (YMMV). That's a factor of 20x faster (110x | ||
305 | faster than the Lua interpreter). | ||
306 | </p> | ||
307 | <p style="font-size: 8pt;"> | ||
308 | The avid reader may notice that converting the pure Lua version over | ||
309 | to 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 | ||
311 | be 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;"> | ||
315 | However the resulting code would be less idiomatic and rather | ||
316 | error-prone. And it still doesn't get even close to the performance of | ||
317 | the FFI version of the code. Also, high-level data structures cannot | ||
318 | be easily passed to other C functions, especially I/O functions, | ||
319 | without undue conversion penalties. | ||
320 | </p> | ||
321 | <br class="flush"> | ||
322 | </div> | ||
323 | <div id="foot"> | ||
324 | <hr class="hide"> | ||
325 | Copyright © 2005-2011 Mike Pall | ||
326 | <span class="noprint"> | ||
327 | · | ||
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 deleted file mode 100644 index 222c580..0000000 --- a/libraries/luajit-2.0/doc/ext_ffi_api.html +++ /dev/null | |||
@@ -1,553 +0,0 @@ | |||
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"> | ||
12 | table.abitable { width: 30em; line-height: 1.2; } | ||
13 | tr.abihead td { font-weight: bold; } | ||
14 | td.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">»</span></a> | ||
57 | </li><li> | ||
58 | <a href="http://luajit.org/download.html">Download <span class="ext">»</span></a> | ||
59 | </li></ul> | ||
60 | </div> | ||
61 | <div id="main"> | ||
62 | <p> | ||
63 | This page describes the API functions provided by the FFI library in | ||
64 | detail. 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> — An abstract C type declaration (a Lua | ||
72 | string).</li> | ||
73 | <li><b>ctype</b> — A C 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> — A C data object. It holds a value of the | ||
77 | corresponding <b>ctype</b>.</li> | ||
78 | <li><b>ct</b> — A C type specification which can be used for | ||
79 | most 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> — A callback object. This is a C data object | ||
82 | holding a special function pointer. Calling this function from | ||
83 | C code runs an associated Lua function.</li> | ||
84 | <li><b>VLA</b> — A variable-length array is declared with a | ||
85 | <tt>?</tt> instead of the number of elements, e.g. <tt>"int[?]"</tt>. | ||
86 | The 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> — A variable-length struct is a <tt>struct</tt> C | ||
89 | type where the last element is a <b>VLA</b>. The same rules for | ||
90 | declaration and creation apply.</li> | ||
91 | </ul> | ||
92 | |||
93 | <h2 id="decl">Declaring and Accessing External Symbols</h2> | ||
94 | <p> | ||
95 | External symbols must be declared first and can then be accessed by | ||
96 | indexing a <a href="ext_ffi_semantics.html#clib">C library | ||
97 | namespace</a>, which automatically binds the symbol to a specific | ||
98 | library. | ||
99 | </p> | ||
100 | |||
101 | <h3 id="ffi_cdef"><tt>ffi.cdef(def)</tt></h3> | ||
102 | <p> | ||
103 | Adds multiple C declarations for types or external symbols (named | ||
104 | variables or functions). <tt>def</tt> must be a Lua string. It's | ||
105 | recommended to use the syntactic sugar for string arguments as | ||
106 | follows: | ||
107 | </p> | ||
108 | <pre class="code"> | ||
109 | ffi.cdef[[ | ||
110 | <span style="color:#00a000;">typedef struct foo { int a, b; } foo_t; // Declare a struct and typedef. | ||
111 | int dofoo(foo_t *f, int n); /* Declare an external C function. */</span> | ||
112 | ]] | ||
113 | </pre> | ||
114 | <p> | ||
115 | The contents of the string (the part in green above) must be a | ||
116 | sequence of | ||
117 | <a href="ext_ffi_semantics.html#clang">C declarations</a>, | ||
118 | separated by semicolons. The trailing semicolon for a single | ||
119 | declaration may be omitted. | ||
120 | </p> | ||
121 | <p> | ||
122 | Please note that external symbols are only <em>declared</em>, but they | ||
123 | are <em>not bound</em> to any specific address, yet. Binding is | ||
124 | achieved with C library namespaces (see below). | ||
125 | </p> | ||
126 | <p style="color: #c00000;"> | ||
127 | C declarations are not passed through a C pre-processor, | ||
128 | yet. No pre-processor tokens are allowed, except for | ||
129 | <tt>#pragma pack</tt>. Replace <tt>#define</tt> in existing | ||
130 | C header files with <tt>enum</tt>, <tt>static const</tt> | ||
131 | or <tt>typedef</tt> and/or pass the files through an external | ||
132 | C pre-processor (once). Be careful not to include unneeded or | ||
133 | redundant declarations from unrelated header files. | ||
134 | </p> | ||
135 | |||
136 | <h3 id="ffi_C"><tt>ffi.C</tt></h3> | ||
137 | <p> | ||
138 | This is the default C library namespace — note the | ||
139 | uppercase <tt>'C'</tt>. It binds to the default set of symbols or | ||
140 | libraries on the target system. These are more or less the same as a | ||
141 | C compiler would offer by default, without specifying extra link | ||
142 | libraries. | ||
143 | </p> | ||
144 | <p> | ||
145 | On POSIX systems, this binds to symbols in the default or global | ||
146 | namespace. This includes all exported symbols from the executable and | ||
147 | any 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 | ||
150 | symbols from the Lua/C API provided by LuaJIT itself. | ||
151 | </p> | ||
152 | <p> | ||
153 | On Windows systems, this binds to symbols exported from the | ||
154 | <tt>*.exe</tt>, the <tt>lua51.dll</tt> (i.e. the Lua/C API | ||
155 | provided by LuaJIT itself), the C runtime library LuaJIT was linked | ||
156 | with (<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> | ||
162 | This loads the dynamic library given by <tt>name</tt> and returns | ||
163 | a new C library namespace which binds to its symbols. On POSIX | ||
164 | systems, if <tt>global</tt> is <tt>true</tt>, the library symbols are | ||
165 | loaded into the global namespace, too. | ||
166 | </p> | ||
167 | <p> | ||
168 | If <tt>name</tt> is a path, the library is loaded from this path. | ||
169 | Otherwise <tt>name</tt> is canonicalized in a system-dependent way and | ||
170 | searched in the default search path for dynamic libraries: | ||
171 | </p> | ||
172 | <p> | ||
173 | On POSIX systems, if the name contains no dot, the extension | ||
174 | <tt>.so</tt> is appended. Also, the <tt>lib</tt> prefix is prepended | ||
175 | if necessary. So <tt>ffi.load("z")</tt> looks for <tt>"libz.so"</tt> | ||
176 | in the default shared library search path. | ||
177 | </p> | ||
178 | <p> | ||
179 | On 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> | ||
186 | The following API functions create cdata objects (<tt>type()</tt> | ||
187 | returns <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> | ||
192 | cdata = <em>ctype</em>([nelem,] [init...])</tt></h3> | ||
193 | <p> | ||
194 | Creates a cdata object for the given <tt>ct</tt>. VLA/VLS types | ||
195 | require the <tt>nelem</tt> argument. The second syntax uses a ctype as | ||
196 | a constructor and is otherwise fully equivalent. | ||
197 | </p> | ||
198 | <p> | ||
199 | The cdata object is initialized according to the | ||
200 | <a href="ext_ffi_semantics.html#init">rules for initializers</a>, | ||
201 | using the optional <tt>init</tt> arguments. Excess initializers cause | ||
202 | an error. | ||
203 | </p> | ||
204 | <p> | ||
205 | Performance notice: if you want to create many objects of one kind, | ||
206 | parse 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;"> | ||
210 | Please note that an anonymous <tt>struct</tt> declaration implicitly | ||
211 | creates 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, | ||
213 | especially if you create more than one cdata object. Different anonymous | ||
214 | <tt>structs</tt> are not considered assignment-compatible by the | ||
215 | C standard, even though they may have the same fields! Also, they | ||
216 | are considered different types by the JIT-compiler, which may cause an | ||
217 | excessive number of traces. It's strongly suggested to either declare | ||
218 | a named <tt>struct</tt> or <tt>typedef</tt> with <tt>ffi.cdef()</tt> | ||
219 | or to create a single ctype object for an anonymous <tt>struct</tt> | ||
220 | with <tt>ffi.typeof()</tt>. | ||
221 | </p> | ||
222 | |||
223 | <h3 id="ffi_typeof"><tt>ctype = ffi.typeof(ct)</tt></h3> | ||
224 | <p> | ||
225 | Creates a ctype object for the given <tt>ct</tt>. | ||
226 | </p> | ||
227 | <p> | ||
228 | This function is especially useful to parse a cdecl only once and then | ||
229 | use 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> | ||
234 | Creates a scalar cdata object for the given <tt>ct</tt>. The cdata | ||
235 | object is initialized with <tt>init</tt> using the "cast" variant of | ||
236 | the <a href="ext_ffi_semantics.html#convert">C type conversion | ||
237 | rules</a>. | ||
238 | </p> | ||
239 | <p> | ||
240 | This functions is mainly useful to override the pointer compatibility | ||
241 | checks 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> | ||
246 | Creates a ctype object for the given <tt>ct</tt> and associates it with | ||
247 | a metatable. Only <tt>struct</tt>/<tt>union</tt> types, complex numbers | ||
248 | and vectors are allowed. Other types may be wrapped in a | ||
249 | <tt>struct</tt>, if needed. | ||
250 | </p> | ||
251 | <p> | ||
252 | The association with a metatable is permanent and cannot be changed | ||
253 | afterwards. Neither the contents of the <tt>metatable</tt> nor the | ||
254 | contents of an <tt>__index</tt> table (if any) may be modified | ||
255 | afterwards. The associated metatable automatically applies to all uses | ||
256 | of this type, no matter how the objects are created or where they | ||
257 | originate from. Note that pre-defined operations on types have | ||
258 | precedence (e.g. declared field names cannot be overriden). | ||
259 | </p> | ||
260 | <p> | ||
261 | All standard Lua metamethods are implemented. These are called directly, | ||
262 | without shortcuts and on any mix of types. For binary operations, the | ||
263 | left operand is checked first for a valid ctype metamethod. The | ||
264 | <tt>__gc</tt> metamethod only applies to <tt>struct</tt>/<tt>union</tt> | ||
265 | types and performs an implicit <a href="#ffi_gc"><tt>ffi.gc()</tt></a> | ||
266 | call during creation of an instance. | ||
267 | </p> | ||
268 | |||
269 | <h3 id="ffi_gc"><tt>cdata = ffi.gc(cdata, finalizer)</tt></h3> | ||
270 | <p> | ||
271 | Associates a finalizer with a pointer or aggregate cdata object. The | ||
272 | cdata object is returned unchanged. | ||
273 | </p> | ||
274 | <p> | ||
275 | This function allows safe integration of unmanaged resources into the | ||
276 | automatic memory management of the LuaJIT garbage collector. Typical | ||
277 | usage: | ||
278 | </p> | ||
279 | <pre class="code"> | ||
280 | local p = ffi.gc(ffi.C.malloc(n), ffi.C.free) | ||
281 | ... | ||
282 | p = nil -- Last reference to p is gone. | ||
283 | -- GC will eventually run finalizer: ffi.C.free(p) | ||
284 | </pre> | ||
285 | <p> | ||
286 | A cdata finalizer works like the <tt>__gc</tt> metamethod for userdata | ||
287 | objects: when the last reference to a cdata object is gone, the | ||
288 | associated finalizer is called with the cdata object as an argument. The | ||
289 | finalizer can be a Lua function or a cdata function or cdata function | ||
290 | pointer. An existing finalizer can be removed by setting a <tt>nil</tt> | ||
291 | finalizer, e.g. right before explicitly deleting a resource: | ||
292 | </p> | ||
293 | <pre class="code"> | ||
294 | ffi.C.free(ffi.gc(p, nil)) -- Manually free the memory. | ||
295 | </pre> | ||
296 | |||
297 | <h2 id="info">C Type Information</h2> | ||
298 | <p> | ||
299 | The following API functions return information about C types. | ||
300 | They 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> | ||
305 | Returns the size of <tt>ct</tt> in bytes. Returns <tt>nil</tt> if | ||
306 | the size is not known (e.g. for <tt>"void"</tt> or function types). | ||
307 | Requires <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> | ||
312 | Returns 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> | ||
317 | Returns the offset (in bytes) of <tt>field</tt> relative to the start | ||
318 | of <tt>ct</tt>, which must be a <tt>struct</tt>. Additionally returns | ||
319 | the 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> | ||
324 | Returns <tt>true</tt> if <tt>obj</tt> has the C type given by | ||
325 | <tt>ct</tt>. Returns <tt>false</tt> otherwise. | ||
326 | </p> | ||
327 | <p> | ||
328 | C type qualifiers (<tt>const</tt> etc.) are ignored. Pointers are | ||
329 | checked with the standard pointer compatibility rules, but without any | ||
330 | special treatment for <tt>void *</tt>. If <tt>ct</tt> specifies a | ||
331 | <tt>struct</tt>/<tt>union</tt>, then a pointer to this type is accepted, | ||
332 | too. Otherwise the types must match exactly. | ||
333 | </p> | ||
334 | <p> | ||
335 | Note: this function accepts all kinds of Lua objects for the | ||
336 | <tt>obj</tt> argument, but always returns <tt>false</tt> for non-cdata | ||
337 | objects. | ||
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> | ||
344 | Returns the error number set by the last C function call which | ||
345 | indicated an error condition. If the optional <tt>newerr</tt> argument | ||
346 | is present, the error number is set to the new value and the previous | ||
347 | value is returned. | ||
348 | </p> | ||
349 | <p> | ||
350 | This function offers a portable and OS-independent way to get and set the | ||
351 | error number. Note that only <em>some</em> C functions set the error | ||
352 | number. And it's only significant if the function actually indicated an | ||
353 | error 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 | ||
355 | value. | ||
356 | </p> | ||
357 | <p> | ||
358 | You're advised to call this function only when needed and as close as | ||
359 | possible after the return of the related C function. The | ||
360 | <tt>errno</tt> value is preserved across hooks, memory allocations, | ||
361 | invocations of the JIT compiler and other internal VM activity. The same | ||
362 | applies to the value returned by <tt>GetLastError()</tt> on Windows, but | ||
363 | you 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> | ||
368 | Creates an interned Lua string from the data pointed to by | ||
369 | <tt>ptr</tt>. | ||
370 | </p> | ||
371 | <p> | ||
372 | If the optional argument <tt>len</tt> is missing, <tt>ptr</tt> is | ||
373 | converted to a <tt>"char *"</tt> and the data is assumed to be | ||
374 | zero-terminated. The length of the string is computed with | ||
375 | <tt>strlen()</tt>. | ||
376 | </p> | ||
377 | <p> | ||
378 | Otherwise <tt>ptr</tt> is converted to a <tt>"void *"</tt> and | ||
379 | <tt>len</tt> gives the length of the data. The data may contain | ||
380 | embedded zeros and need not be byte-oriented (though this may cause | ||
381 | endianess issues). | ||
382 | </p> | ||
383 | <p> | ||
384 | This function is mainly useful to convert (temporary) | ||
385 | <tt>"const char *"</tt> pointers returned by | ||
386 | C functions to Lua strings and store them or pass them to other | ||
387 | functions expecting a Lua string. The Lua string is an (interned) copy | ||
388 | of the data and bears no relation to the original data area anymore. | ||
389 | Lua strings are 8 bit clean and may be used to hold arbitrary, | ||
390 | non-character data. | ||
391 | </p> | ||
392 | <p> | ||
393 | Performance notice: it's faster to pass the length of the string, if | ||
394 | it's known. E.g. when the length is returned by a C call like | ||
395 | <tt>sprintf()</tt>. | ||
396 | </p> | ||
397 | |||
398 | <h3 id="ffi_copy"><tt>ffi.copy(dst, src, len)<br> | ||
399 | ffi.copy(dst, str)</tt></h3> | ||
400 | <p> | ||
401 | Copies the data pointed to by <tt>src</tt> to <tt>dst</tt>. | ||
402 | <tt>dst</tt> is converted to a <tt>"void *"</tt> and <tt>src</tt> | ||
403 | is converted to a <tt>"const void *"</tt>. | ||
404 | </p> | ||
405 | <p> | ||
406 | In the first syntax, <tt>len</tt> gives the number of bytes to copy. | ||
407 | Caveat: if <tt>src</tt> is a Lua string, then <tt>len</tt> must not | ||
408 | exceed <tt>#src+1</tt>. | ||
409 | </p> | ||
410 | <p> | ||
411 | In the second syntax, the source of the copy must be a Lua string. All | ||
412 | bytes 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> | ||
416 | Performance notice: <tt>ffi.copy()</tt> may be used as a faster | ||
417 | (inlinable) replacement for the C 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> | ||
423 | Fills the data pointed to by <tt>dst</tt> with <tt>len</tt> constant | ||
424 | bytes, given by <tt>c</tt>. If <tt>c</tt> is omitted, the data is | ||
425 | zero-filled. | ||
426 | </p> | ||
427 | <p> | ||
428 | Performance notice: <tt>ffi.fill()</tt> may be used as a faster | ||
429 | (inlinable) replacement for the C library function | ||
430 | <tt>memset(dst, c, len)</tt>. Please note the different | ||
431 | order 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> | ||
438 | Returns <tt>true</tt> if <tt>param</tt> (a Lua string) applies for the | ||
439 | target ABI (Application Binary Interface). Returns <tt>false</tt> | ||
440 | otherwise. 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> | ||
469 | Contains 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> | ||
475 | Contains 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> | ||
481 | The C types for <a href="ext_ffi_semantics.html#callback">callbacks</a> | ||
482 | have some extra methods: | ||
483 | </p> | ||
484 | |||
485 | <h3 id="callback_free"><tt>cb:free()</tt></h3> | ||
486 | <p> | ||
487 | Free the resources associated with a callback. The associated Lua | ||
488 | function is unanchored and may be garbage collected. The callback | ||
489 | function 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> | ||
495 | Associate a new Lua function with a callback. The C type of the | ||
496 | callback and the callback function pointer are unchanged. | ||
497 | </p> | ||
498 | <p> | ||
499 | This method is useful to dynamically switch the receiver of callbacks | ||
500 | without creating a new callback each time and registering it again (e.g. | ||
501 | with a GUI library). | ||
502 | </p> | ||
503 | |||
504 | <h2 id="extended">Extended Standard Library Functions</h2> | ||
505 | <p> | ||
506 | The following standard library functions have been extended to work | ||
507 | with cdata objects: | ||
508 | </p> | ||
509 | |||
510 | <h3 id="tonumber"><tt>n = tonumber(cdata)</tt></h3> | ||
511 | <p> | ||
512 | Converts a number cdata object to a <tt>double</tt> and returns it as | ||
513 | a Lua number. This is particularly useful for boxed 64 bit | ||
514 | integer values. Caveat: this conversion may incur a precision loss. | ||
515 | </p> | ||
516 | |||
517 | <h3 id="tostring"><tt>s = tostring(cdata)</tt></h3> | ||
518 | <p> | ||
519 | Returns a string representation of the value of 64 bit integers | ||
520 | (<tt><b>"</b>nnn<b>LL"</b></tt> or <tt><b>"</b>nnn<b>ULL"</b></tt>) or | ||
521 | complex numbers (<tt><b>"</b>re±im<b>i"</b></tt>). Otherwise | ||
522 | returns a string representation of the C type of a ctype object | ||
523 | (<tt><b>"ctype<</b>type<b>>"</b></tt>) or a cdata object | ||
524 | (<tt><b>"cdata<</b>type<b>>: </b>address"</tt>). | ||
525 | </p> | ||
526 | |||
527 | <h2 id="literals">Extensions to the Lua Parser</h2> | ||
528 | <p> | ||
529 | The parser for Lua source code treats numeric literals with the | ||
530 | suffixes <tt>LL</tt> or <tt>ULL</tt> as signed or unsigned 64 bit | ||
531 | integers. Case doesn't matter, but uppercase is recommended for | ||
532 | readability. It handles both decimal (<tt>42LL</tt>) and hexadecimal | ||
533 | (<tt>0x2aLL</tt>) literals. | ||
534 | </p> | ||
535 | <p> | ||
536 | The imaginary part of complex numbers can be specified by suffixing | ||
537 | number literals with <tt>i</tt> or <tt>I</tt>, e.g. <tt>12.5i</tt>. | ||
538 | Caveat: you'll need to use <tt>1i</tt> to get an imaginary part with | ||
539 | the value one, since <tt>i</tt> itself still refers to a variable | ||
540 | named <tt>i</tt>. | ||
541 | </p> | ||
542 | <br class="flush"> | ||
543 | </div> | ||
544 | <div id="foot"> | ||
545 | <hr class="hide"> | ||
546 | Copyright © 2005-2011 Mike Pall | ||
547 | <span class="noprint"> | ||
548 | · | ||
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 deleted file mode 100644 index 661b0b4..0000000 --- a/libraries/luajit-2.0/doc/ext_ffi_semantics.html +++ /dev/null | |||
@@ -1,1146 +0,0 @@ | |||
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"> | ||
12 | table.convtable { line-height: 1.2; } | ||
13 | tr.convhead td { font-weight: bold; } | ||
14 | td.convin { width: 11em; } | ||
15 | td.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">»</span></a> | ||
58 | </li><li> | ||
59 | <a href="http://luajit.org/download.html">Download <span class="ext">»</span></a> | ||
60 | </li></ul> | ||
61 | </div> | ||
62 | <div id="main"> | ||
63 | <p> | ||
64 | This page describes the detailed semantics underlying the FFI library | ||
65 | and its interaction with both Lua and C code. | ||
66 | </p> | ||
67 | <p> | ||
68 | Given that the FFI library is designed to interface with C code | ||
69 | and that declarations can be written in plain C syntax, <b>it | ||
70 | closely follows the C language semantics</b>, wherever possible. | ||
71 | Some minor concessions are needed for smoother interoperation with Lua | ||
72 | language semantics. | ||
73 | </p> | ||
74 | <p> | ||
75 | Please don't be overwhelmed by the contents of this page — this | ||
76 | is a reference and you may need to consult it, if in doubt. It doesn't | ||
77 | hurt to skim this page, but most of the semantics "just work" as you'd | ||
78 | expect them to work. It should be straightforward to write | ||
79 | applications using the LuaJIT FFI for developers with a C or C++ | ||
80 | background. | ||
81 | </p> | ||
82 | <p class="indent" style="color: #c00000;"> | ||
83 | Please note: this doesn't comprise the final specification for the FFI | ||
84 | semantics, yet. Some semantics may need to be changed, based on your | ||
85 | feedback. Please <a href="contact.html">report</a> any problems you may | ||
86 | encounter or any improvements you'd like to see — thank you! | ||
87 | </p> | ||
88 | |||
89 | <h2 id="clang">C Language Support</h2> | ||
90 | <p> | ||
91 | The FFI library has a built-in C parser with a minimal memory | ||
92 | footprint. It's used by the <a href="ext_ffi_api.html">ffi.* library | ||
93 | functions</a> to declare C types or external symbols. | ||
94 | </p> | ||
95 | <p> | ||
96 | It's only purpose is to parse C declarations, as found e.g. in | ||
97 | C header files. Although it does evaluate constant expressions, | ||
98 | it's <em>not</em> a C compiler. The body of <tt>inline</tt> | ||
99 | C function definitions is simply ignored. | ||
100 | </p> | ||
101 | <p> | ||
102 | Also, this is <em>not</em> a validating C parser. It expects and | ||
103 | accepts correctly formed C declarations, but it may choose to | ||
104 | ignore bad declarations or show rather generic error messages. If in | ||
105 | doubt, please check the input against your favorite C compiler. | ||
106 | </p> | ||
107 | <p> | ||
108 | The C parser complies to the <b>C99 language standard</b> plus | ||
109 | the 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> | ||
116 | or <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 double</tt>) and <tt>complex 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 | ||
128 | inside 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 | ||
136 | global namespace, too.</li> | ||
137 | |||
138 | <li>Scoped <tt>static 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 | ||
144 | VLA).</li> | ||
145 | |||
146 | <li>C++ reference types (<tt>int &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 | ||
160 | function 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> | ||
167 | and <tt>#pragma pack</tt>.</li> | ||
168 | |||
169 | <li>All other GCC/MSVC-specific attributes are ignored.</li> | ||
170 | |||
171 | </ul> | ||
172 | <p> | ||
173 | The following C types are pre-defined by the C parser (like | ||
174 | a <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><stddef.h></tt>: <tt>ptrdiff_t</tt>, | ||
182 | <tt>size_t</tt>, <tt>wchar_t</tt>.</li> | ||
183 | |||
184 | <li>From <tt><stdint.h></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> | ||
191 | You're encouraged to use these types in preference to the | ||
192 | compiler-specific extensions or the target-dependent standard types. | ||
193 | E.g. <tt>char</tt> differs in signedness and <tt>long</tt> differs in | ||
194 | size, depending on the target architecture and platform ABI. | ||
195 | </p> | ||
196 | <p> | ||
197 | The following C features are <b>not</b> supported: | ||
198 | </p> | ||
199 | <ul> | ||
200 | |||
201 | <li>A declaration must always have a type specifier; it doesn't | ||
202 | default to an <tt>int</tt> type.</li> | ||
203 | |||
204 | <li>Old-style empty function declarations (K&R) are not allowed. | ||
205 | All C functions must have a proper prototype declaration. A | ||
206 | function declared without parameters (<tt>int foo();</tt>) is | ||
207 | treated as a function taking zero arguments, like in C++.</li> | ||
208 | |||
209 | <li>The <tt>long double</tt> C type is parsed correctly, but | ||
210 | there's no support for the related conversions, accesses or arithmetic | ||
211 | operations.</li> | ||
212 | |||
213 | <li>Wide character strings and character literals are not | ||
214 | supported.</li> | ||
215 | |||
216 | <li><a href="#status">See below</a> for features that are currently | ||
217 | not implemented.</li> | ||
218 | |||
219 | </ul> | ||
220 | |||
221 | <h2 id="convert">C Type Conversion Rules</h2> | ||
222 | |||
223 | <h3 id="convert_tolua">Conversions from C types to Lua objects</h3> | ||
224 | <p> | ||
225 | These conversion rules apply for <em>read accesses</em> to | ||
226 | C types: indexing pointers, arrays or | ||
227 | <tt>struct</tt>/<tt>union</tt> types; reading external variables or | ||
228 | constant values; retrieving return values from C 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">→<sup>sign-ext</sup> <tt>int32_t</tt> → <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">→<sup>zero-ext</sup> <tt>int32_t</tt> → <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">→ <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">→ <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 → <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> | ||
260 | Bitfields or <tt>enum</tt> types are treated like their underlying | ||
261 | type. | ||
262 | </p> | ||
263 | <p> | ||
264 | Reference types are dereferenced <em>before</em> a conversion can take | ||
265 | place — the conversion is applied to the C type pointed to | ||
266 | by the reference. | ||
267 | </p> | ||
268 | |||
269 | <h3 id="convert_fromlua">Conversions from Lua objects to C types</h3> | ||
270 | <p> | ||
271 | These conversion rules apply for <em>write accesses</em> to | ||
272 | C types: indexing pointers, arrays or | ||
273 | <tt>struct</tt>/<tt>union</tt> types; initializing cdata objects; | ||
274 | casts to C types; writing to external variables; passing | ||
275 | arguments to C 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">→</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> → 0, <tt>true</tt> → 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> →</td><td class="convout"><tt>(void *)</tt></td></tr> | ||
289 | <tr class="even"> | ||
290 | <td class="convin">userdata</td><td class="convop">userdata payload →</td><td class="convout"><tt>(void *)</tt></td></tr> | ||
291 | <tr class="odd"> | ||
292 | <td class="convin">lightuserdata</td><td class="convop">lightuserdata address →</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 →</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> →</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 →</td><td class="convout">C type</td></tr> | ||
307 | </table> | ||
308 | <p> | ||
309 | If the result type of this conversion doesn't match the | ||
310 | C type of the destination, the | ||
311 | <a href="#convert_between">conversion rules between C types</a> | ||
312 | are applied. | ||
313 | </p> | ||
314 | <p> | ||
315 | Reference types are immutable after initialization ("no re-seating of | ||
316 | references"). For initialization purposes or when passing values to | ||
317 | reference parameters, they are treated like pointers. Note that unlike | ||
318 | in C++, there's no way to implement automatic reference generation of | ||
319 | variables under the Lua language semantics. If you want to call a | ||
320 | function with a reference parameter, you need to explicitly pass a | ||
321 | one-element array. | ||
322 | </p> | ||
323 | |||
324 | <h3 id="convert_between">Conversions between C types</h3> | ||
325 | <p> | ||
326 | These conversion rules are more or less the same as the standard | ||
327 | C conversion rules. Some rules only apply to casts, or require | ||
328 | pointer 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">→<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">→<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">→<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">→<sup>trunc</sup> <tt>int32_t</tt> →<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">→<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">→<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 → 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> → 0, <tt>true</tt> → 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> | ||
382 | Bitfields or <tt>enum</tt> types are treated like their underlying | ||
383 | type. | ||
384 | </p> | ||
385 | <p> | ||
386 | Conversions not listed above will raise an error. E.g. it's not | ||
387 | possible to convert a pointer to a complex number or vice versa. | ||
388 | </p> | ||
389 | |||
390 | <h3 id="convert_vararg">Conversions for vararg C function arguments</h3> | ||
391 | <p> | ||
392 | The following default conversion rules apply when passing Lua objects | ||
393 | to the variable argument part of vararg C 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">→</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> → 0, <tt>true</tt> → 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> →</td><td class="convout"><tt>(void *)</tt></td></tr> | ||
407 | <tr class="even"> | ||
408 | <td class="convin">userdata</td><td class="convop">userdata payload →</td><td class="convout"><tt>(void *)</tt></td></tr> | ||
409 | <tr class="odd"> | ||
410 | <td class="convin">lightuserdata</td><td class="convop">lightuserdata address →</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 →</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">→</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> | ||
425 | To pass a Lua object, other than a cdata object, as a specific type, | ||
426 | you need to override the conversion rules: create a temporary cdata | ||
427 | object with a constructor or a cast and initialize it with the value | ||
428 | to pass: | ||
429 | </p> | ||
430 | <p> | ||
431 | Assuming <tt>x</tt> is a Lua number, here's how to pass it as an | ||
432 | integer to a vararg function: | ||
433 | </p> | ||
434 | <pre class="code"> | ||
435 | ffi.cdef[[ | ||
436 | int printf(const char *fmt, ...); | ||
437 | ]] | ||
438 | ffi.C.printf("integer value: %d\n", ffi.new("int", x)) | ||
439 | </pre> | ||
440 | <p> | ||
441 | If you don't do this, the default Lua number → <tt>double</tt> | ||
442 | conversion rule applies. A vararg C function expecting an integer | ||
443 | will see a garbled or uninitialized value. | ||
444 | </p> | ||
445 | |||
446 | <h2 id="init">Initializers</h2> | ||
447 | <p> | ||
448 | Creating a cdata object with | ||
449 | <a href="ext_ffi_api.html#ffi_new"><tt>ffi.new()</tt></a> or the | ||
450 | equivalent constructor syntax always initializes its contents, too. | ||
451 | Different rules apply, depending on the number of optional | ||
452 | initializers and the C 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. | ||
458 | The Lua object is <a href="#convert_fromlua">converted to the scalar | ||
459 | C type</a>.</li> | ||
460 | |||
461 | <li>Valarrays (complex numbers and vectors) are treated like scalars | ||
462 | when a single initializer is given. Otherwise they are treated like | ||
463 | regular 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 | ||
467 | initializers.</li> | ||
468 | |||
469 | <li>The elements of an array are initialized, starting at index zero. | ||
470 | If a single initializer is given for an array, it's repeated for all | ||
471 | remaining elements. This doesn't happen if two or more initializers | ||
472 | are given: all remaining uninitialized elements are filled with zero | ||
473 | bytes.</li> | ||
474 | |||
475 | <li>Byte arrays may also be initialized with a Lua string. This copies | ||
476 | the whole string plus a terminating zero-byte. The copy stops early only | ||
477 | if the array has a known, fixed size.</li> | ||
478 | |||
479 | <li>The fields of a <tt>struct</tt> are initialized in the order of | ||
480 | their declaration. Uninitialized fields are filled with zero | ||
481 | bytes.</li> | ||
482 | |||
483 | <li>Only the first field of a <tt>union</tt> can be initialized with a | ||
484 | flat initializer.</li> | ||
485 | |||
486 | <li>Elements or fields which are aggregates themselves are initialized | ||
487 | with a <em>single</em> initializer, but this may be a table | ||
488 | initializer 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> | ||
496 | The following rules apply if a Lua table is used to initialize an | ||
497 | Array 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 | ||
502 | table is assumed to be zero-based. Otherwise it's assumed to be | ||
503 | one-based.</li> | ||
504 | |||
505 | <li>Array elements, starting at index zero, are initialized one-by-one | ||
506 | with 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 | ||
511 | all the remaining elements. Otherwise all remaining uninitialized | ||
512 | elements are filled with zero bytes.</li> | ||
513 | |||
514 | <li>The above logic only applies to arrays with a known fixed size. | ||
515 | A VLA is only initialized with the element(s) given in the table. | ||
516 | Depending 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 | ||
521 | name (as a string key) in the table. Each non-<tt>nil</tt> value is | ||
522 | used to initialize the corresponding field.</li> | ||
523 | |||
524 | <li>Otherwise a <tt>struct</tt>/<tt>union</tt> is initialized in the | ||
525 | order of the declaration of its fields. Each field is initialized with | ||
526 | the consecutive table elements, starting at either index <tt>[0]</tt> | ||
527 | or <tt>[1]</tt>. This process stops at the first <tt>nil</tt> table | ||
528 | element.</li> | ||
529 | |||
530 | <li>Uninitialized fields of a <tt>struct</tt> are filled with zero | ||
531 | bytes, except for the trailing VLA of a VLS.</li> | ||
532 | |||
533 | <li>Initialization of a <tt>union</tt> stops after one field has been | ||
534 | initialized. If no field has been initialized, the <tt>union</tt> is | ||
535 | filled with zero bytes.</li> | ||
536 | |||
537 | <li>Elements or fields which are aggregates themselves are initialized | ||
538 | with a <em>single</em> initializer, but this may be a nested table | ||
539 | initializer (or a compatible aggregate).</li> | ||
540 | |||
541 | <li>Excess initializers for an array cause an error. Excess | ||
542 | initializers for a <tt>struct</tt>/<tt>union</tt> are ignored. | ||
543 | Unrelated table entries are ignored, too.</li> | ||
544 | |||
545 | </ul> | ||
546 | <p> | ||
547 | Example: | ||
548 | </p> | ||
549 | <pre class="code"> | ||
550 | local ffi = require("ffi") | ||
551 | |||
552 | ffi.cdef[[ | ||
553 | struct foo { int a, b; }; | ||
554 | union bar { int i; double d; }; | ||
555 | struct nested { int x; struct foo y; }; | ||
556 | ]] | ||
557 | |||
558 | ffi.new("int[3]", {}) --> 0, 0, 0 | ||
559 | ffi.new("int[3]", {1}) --> 1, 1, 1 | ||
560 | ffi.new("int[3]", {1,2}) --> 1, 2, 0 | ||
561 | ffi.new("int[3]", {1,2,3}) --> 1, 2, 3 | ||
562 | ffi.new("int[3]", {[0]=1}) --> 1, 1, 1 | ||
563 | ffi.new("int[3]", {[0]=1,2}) --> 1, 2, 0 | ||
564 | ffi.new("int[3]", {[0]=1,2,3}) --> 1, 2, 3 | ||
565 | ffi.new("int[3]", {[0]=1,2,3,4}) --> error: too many initializers | ||
566 | |||
567 | ffi.new("struct foo", {}) --> a = 0, b = 0 | ||
568 | ffi.new("struct foo", {1}) --> a = 1, b = 0 | ||
569 | ffi.new("struct foo", {1,2}) --> a = 1, b = 2 | ||
570 | ffi.new("struct foo", {[0]=1,2}) --> a = 1, b = 2 | ||
571 | ffi.new("struct foo", {b=2}) --> a = 0, b = 2 | ||
572 | ffi.new("struct foo", {a=1,b=2,c=3}) --> a = 1, b = 2 'c' is ignored | ||
573 | |||
574 | ffi.new("union bar", {}) --> i = 0, d = 0.0 | ||
575 | ffi.new("union bar", {1}) --> i = 1, d = ? | ||
576 | ffi.new("union bar", {[0]=1,2}) --> i = 1, d = ? '2' is ignored | ||
577 | ffi.new("union bar", {d=2}) --> i = ?, d = 2.0 | ||
578 | |||
579 | ffi.new("struct nested", {1,{2,3}}) --> x = 1, y.a = 2, y.b = 3 | ||
580 | ffi.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> | ||
585 | All of the standard Lua operators can be applied to cdata objects or a | ||
586 | mix of a cdata object and another Lua object. The following list shows | ||
587 | the valid combinations. All other combinations currently raise an | ||
588 | error. | ||
589 | </p> | ||
590 | <p> | ||
591 | Reference types are dereferenced <em>before</em> performing each of | ||
592 | the operations below — the operation is applied to the | ||
593 | C type pointed to by the reference. | ||
594 | </p> | ||
595 | <p> | ||
596 | The pre-defined operations are always tried first before deferring to a | ||
597 | metamethod 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 | ||
604 | indexed by a cdata number or a Lua number. The element address is | ||
605 | computed as the base address plus the number value multiplied by the | ||
606 | element 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 | ||
608 | access <a href="#convert_fromlua">converts a Lua object to the element | ||
609 | type</a> and stores the converted value to the element. An error is | ||
610 | raised if the element size is undefined or a write access to a | ||
611 | constant element is attempted.</li> | ||
612 | |||
613 | <li><b>Dereferencing a <tt>struct</tt>/<tt>union</tt> field</b>: a | ||
614 | cdata <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, | ||
616 | giving the field name. The field address is computed as the base | ||
617 | address plus the relative offset of the field. A read access loads the | ||
618 | field value and <a href="#convert_tolua">converts it to a Lua | ||
619 | object</a>. A write access <a href="#convert_fromlua">converts a Lua | ||
620 | object to the field type</a> and stores the converted value to the | ||
621 | field. 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 | ||
625 | either by a cdata number or a Lua number with the values 0 or 1, or by | ||
626 | the strings <tt>"re"</tt> or <tt>"im"</tt>. A read access loads the | ||
627 | real 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 | ||
630 | sub-parts of a complex number are immutable — assigning to an | ||
631 | index of a complex number raises an error. Accessing out-of-bound | ||
632 | indexes returns unspecified results, but is guaranteed not to trigger | ||
633 | memory access violations.</li> | ||
634 | |||
635 | <li><b>Indexing a vector</b>: a vector is treated like an array for | ||
636 | indexing purposes, except the vector elements are immutable — | ||
637 | assigning to an index of a vector raises an error.</li> | ||
638 | |||
639 | </ul> | ||
640 | <p> | ||
641 | Note: since there's (deliberately) no address-of operator, a cdata | ||
642 | object holding a value type is effectively immutable after | ||
643 | initialization. The JIT compiler benefits from this fact when applying | ||
644 | certain optimizations. | ||
645 | </p> | ||
646 | <p> | ||
647 | As a consequence of this, the <em>elements</em> of complex numbers and | ||
648 | vectors are immutable. But the elements of an aggregate holding these | ||
649 | types <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 | ||
651 | to <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 function call</b>: a cdata function or cdata function | ||
661 | pointer can be called. The passed arguments are | ||
662 | <a href="#convert_fromlua">converted to the C types</a> of the | ||
663 | parameters given by the function declaration. Arguments passed to the | ||
664 | variable argument part of vararg C function use | ||
665 | <a href="#convert_vararg">special conversion rules</a>. This | ||
666 | C function is called and the return value (if any) is | ||
667 | <a href="#convert_tolua">converted to a Lua object</a>.<br> | ||
668 | On Windows/x86 systems, <tt>__stdcall</tt> functions are automatically | ||
669 | detected and a function declared as <tt>__cdecl</tt> (the default) is | ||
670 | silently 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 | ||
678 | number or a Lua number can be added or subtracted. The number must be | ||
679 | on the right hand side for a subtraction. The result is a pointer of | ||
680 | the same type with an address plus or minus the number value | ||
681 | multiplied by the element size in bytes. An error is raised if the | ||
682 | element size is undefined.</li> | ||
683 | |||
684 | <li><b>Pointer difference</b>: two compatible cdata pointers/arrays | ||
685 | can be subtracted. The result is the difference between their | ||
686 | addresses, divided by the element size in bytes. An error is raised if | ||
687 | the element size is undefined or zero.</li> | ||
688 | |||
689 | <li><b>64 bit integer arithmetic</b>: the standard arithmetic | ||
690 | operators (<tt>+ - * / % ^</tt> and unary | ||
691 | minus) can be applied to two cdata numbers, or a cdata number and a | ||
692 | Lua number. If one of them is an <tt>uint64_t</tt>, the other side is | ||
693 | converted to an <tt>uint64_t</tt> and an unsigned arithmetic operation | ||
694 | is performed. Otherwise both sides are converted to an | ||
695 | <tt>int64_t</tt> and a signed arithmetic operation is performed. The | ||
696 | result is a boxed 64 bit cdata object.<br> | ||
697 | |||
698 | These rules ensure that 64 bit integers are "sticky". Any | ||
699 | expression involving at least one 64 bit integer operand results | ||
700 | in another one. The undefined cases for the division, modulo and power | ||
701 | operators return <tt>2LL ^ 63</tt> or | ||
702 | <tt>2ULL ^ 63</tt>.<br> | ||
703 | |||
704 | You'll have to explicitly convert a 64 bit integer to a Lua | ||
705 | number (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 | ||
714 | can be compared. The result is the same as an unsigned comparison of | ||
715 | their addresses. <tt>nil</tt> is treated like a <tt>NULL</tt> pointer, | ||
716 | which is compatible with any other pointer type.</li> | ||
717 | |||
718 | <li><b>64 bit integer comparison</b>: two cdata numbers, or a | ||
719 | cdata number and a Lua number can be compared with each other. If one | ||
720 | of 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 | ||
722 | both sides are converted to an <tt>int64_t</tt> and a signed | ||
723 | comparison is performed.</li> | ||
724 | |||
725 | </ul> | ||
726 | |||
727 | <h3 id="cdata_key">cdata objects as table keys</h3> | ||
728 | <p> | ||
729 | Lua tables may be indexed by cdata objects, but this doesn't provide | ||
730 | any useful semantics — <b>cdata objects are unsuitable as table | ||
731 | keys!</b> | ||
732 | </p> | ||
733 | <p> | ||
734 | A cdata object is treated like any other garbage-collected object and | ||
735 | is hashed and compared by its address for table indexing. Since | ||
736 | there's no interning for cdata value types, the same value may be | ||
737 | boxed 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 | ||
739 | the same hash slot and they certainly <b>do not</b> point to the same | ||
740 | hash slot as <tt>t[2]</tt>. | ||
741 | </p> | ||
742 | <p> | ||
743 | It would seriously drive up implementation complexity and slow down | ||
744 | the common case, if one were to add extra handling for by-value | ||
745 | hashing and comparisons to Lua tables. Given the ubiquity of their use | ||
746 | inside the VM, this is not acceptable. | ||
747 | </p> | ||
748 | <p> | ||
749 | There are three viable alternatives, if you really need to use cdata | ||
750 | objects as keys: | ||
751 | </p> | ||
752 | <ul> | ||
753 | |||
754 | <li>If you can get by with the precision of Lua numbers | ||
755 | (52 bits), then use <tt>tonumber()</tt> on a cdata number or | ||
756 | combine multiple fields of a cdata aggregate to a Lua number. Then use | ||
757 | the resulting Lua number as a key when indexing tables.<br> | ||
758 | One obvious benefit: <tt>t[tonumber(2LL)]</tt> <b>does</b> point to | ||
759 | the same slot as <tt>t[2]</tt>.</li> | ||
760 | |||
761 | <li>Otherwise use either <tt>tostring()</tt> on 64 bit integers | ||
762 | or complex numbers or combine multiple fields of a cdata aggregate to | ||
763 | a Lua string (e.g. with | ||
764 | <a href="ext_ffi_api.html#ffi_string"><tt>ffi.string()</tt></a>). Then | ||
765 | use the resulting Lua string as a key when indexing tables.</li> | ||
766 | |||
767 | <li>Create your own specialized hash table implementation using the | ||
768 | C types provided by the FFI library, just like you would in | ||
769 | C code. Ultimately this may give much better performance than the | ||
770 | other alternatives or what a generic by-value hash table could | ||
771 | possibly provide.</li> | ||
772 | |||
773 | </ul> | ||
774 | |||
775 | <h2 id="gc">Garbage Collection of cdata Objects</h2> | ||
776 | <p> | ||
777 | All explicitly (<tt>ffi.new()</tt>, <tt>ffi.cast()</tt> etc.) or | ||
778 | implicitly (accessors) created cdata objects are garbage collected. | ||
779 | You need to ensure to retain valid references to cdata objects | ||
780 | somewhere on a Lua stack, an upvalue or in a Lua table while they are | ||
781 | still in use. Once the last reference to a cdata object is gone, the | ||
782 | garbage collector will automatically free the memory used by it (at | ||
783 | the end of the next GC cycle). | ||
784 | </p> | ||
785 | <p> | ||
786 | Please note that pointers themselves are cdata objects, however they | ||
787 | are <b>not</b> followed by the garbage collector. So e.g. if you | ||
788 | assign a cdata array to a pointer, you must keep the cdata object | ||
789 | holding the array alive as long as the pointer is still in use: | ||
790 | </p> | ||
791 | <pre class="code"> | ||
792 | ffi.cdef[[ | ||
793 | typedef struct { int *a; } foo_t; | ||
794 | ]] | ||
795 | |||
796 | local s = ffi.new("foo_t", ffi.new("int[10]")) -- <span style="color:#c00000;">WRONG!</span> | ||
797 | |||
798 | local a = ffi.new("int[10]") -- <span style="color:#00a000;">OK</span> | ||
799 | local s = ffi.new("foo_t", a) | ||
800 | -- Now do something with 's', but keep 'a' alive until you're done. | ||
801 | </pre> | ||
802 | <p> | ||
803 | Similar rules apply for Lua strings which are implicitly converted to | ||
804 | <tt>"const char *"</tt>: the string object itself must be | ||
805 | referenced somewhere or it'll be garbage collected eventually. The | ||
806 | pointer will then point to stale data, which may have already been | ||
807 | overwritten. Note that <em>string literals</em> are automatically kept | ||
808 | alive as long as the function containing it (actually its prototype) | ||
809 | is not garbage collected. | ||
810 | </p> | ||
811 | <p> | ||
812 | Objects which are passed as an argument to an external C function | ||
813 | are kept alive until the call returns. So it's generally safe to | ||
814 | create temporary cdata objects in argument lists. This is a common | ||
815 | idiom for <a href="#convert_vararg">passing specific C types to | ||
816 | vararg functions</a>. | ||
817 | </p> | ||
818 | <p> | ||
819 | Memory areas returned by C functions (e.g. from <tt>malloc()</tt>) | ||
820 | must be manually managed, of course (or use | ||
821 | <a href="ext_ffi_api.html#ffi_gc"><tt>ffi.gc()</tt></a>). Pointers to | ||
822 | cdata objects are indistinguishable from pointers returned by C | ||
823 | functions (which is one of the reasons why the GC cannot follow them). | ||
824 | </p> | ||
825 | |||
826 | <h2 id="callback">Callbacks</h2> | ||
827 | <p> | ||
828 | The LuaJIT FFI automatically generates special callback functions | ||
829 | whenever a Lua function is converted to a C function pointer. This | ||
830 | associates the generated callback function pointer with the C type | ||
831 | of the function pointer and the Lua function object (closure). | ||
832 | </p> | ||
833 | <p> | ||
834 | This can happen implicitly due to the usual conversions, e.g. when | ||
835 | passing 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 | ||
837 | C function pointer. | ||
838 | </p> | ||
839 | <p> | ||
840 | Currently only certain C function types can be used as callback | ||
841 | functions. Neither C vararg functions nor functions with | ||
842 | pass-by-value aggregate argument or result types are supported. There | ||
843 | are no restrictions for the kind of Lua functions that can be called | ||
844 | from the callback — no checks for the proper number of arguments | ||
845 | are made. The return value of the Lua function will be converted to the | ||
846 | result type and an error will be thrown for invalid conversions. | ||
847 | </p> | ||
848 | <p> | ||
849 | It's allowed to throw errors across a callback invocation, but it's not | ||
850 | advisable in general. Do this only if you know the C function, that | ||
851 | called the callback, copes with the forced stack unwinding and doesn't | ||
852 | leak resources. | ||
853 | </p> | ||
854 | |||
855 | <h3 id="callback_resources">Callback resource handling</h3> | ||
856 | <p> | ||
857 | Callbacks take up resources — you can only have a limited number | ||
858 | of them at the same time (500 - 1000, depending on the | ||
859 | architecture). The associated Lua functions are anchored to prevent | ||
860 | garbage collection, too. | ||
861 | </p> | ||
862 | <p> | ||
863 | <b>Callbacks due to implicit conversions are permanent!</b> There is no | ||
864 | way to guess their lifetime, since the C side might store the | ||
865 | function pointer for later use (typical for GUI toolkits). The associated | ||
866 | resources cannot be reclaimed until termination: | ||
867 | </p> | ||
868 | <pre class="code"> | ||
869 | ffi.cdef[[ | ||
870 | typedef int (__stdcall *WNDENUMPROC)(void *hwnd, intptr_t l); | ||
871 | int EnumWindows(WNDENUMPROC func, intptr_t l); | ||
872 | ]] | ||
873 | |||
874 | -- Implicit conversion to a callback via function pointer argument. | ||
875 | local count = 0 | ||
876 | ffi.C.EnumWindows(function(hwnd, l) | ||
877 | count = count + 1 | ||
878 | return true | ||
879 | end, 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> | ||
884 | Note: this example shows that you <em>must</em> properly declare | ||
885 | <tt>__stdcall</tt> callbacks on Windows/x86 systems. The calling | ||
886 | convention cannot be automatically detected, unlike for | ||
887 | <tt>__stdcall</tt> calls <em>to</em> Windows functions. | ||
888 | </p> | ||
889 | <p> | ||
890 | For some use cases it's necessary to free up the resources or to | ||
891 | dynamically redirect callbacks. Use an explicit cast to a | ||
892 | C function pointer and keep the resulting cdata object. Then use | ||
893 | the <a href="ext_ffi_api.html#callback_free"><tt>cb:free()</tt></a> | ||
894 | or <a href="ext_ffi_api.html#callback_set"><tt>cb:set()</tt></a> methods | ||
895 | on the cdata object: | ||
896 | </p> | ||
897 | <pre class="code"> | ||
898 | -- Explicitly convert to a callback via cast. | ||
899 | local count = 0 | ||
900 | local cb = ffi.cast("WNDENUMPROC", function(hwnd, l) | ||
901 | count = count + 1 | ||
902 | return true | ||
903 | end) | ||
904 | |||
905 | -- Pass it to a C function. | ||
906 | ffi.C.EnumWindows(cb, 0) | ||
907 | -- EnumWindows doesn't need the callback after it returns, so free it. | ||
908 | |||
909 | cb: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 to Lua transition itself | ||
917 | has an unavoidable cost, similar to a <tt>lua_call()</tt> or | ||
918 | <tt>lua_pcall()</tt>. Argument and result marshalling add to that cost. | ||
919 | And finally, neither the C compiler nor LuaJIT can inline or | ||
920 | optimize across the language barrier and hoist repeated computations out | ||
921 | of a callback function. | ||
922 | </p> | ||
923 | <p> | ||
924 | Do not use callbacks for performance-sensitive work: e.g. consider a | ||
925 | numerical integration routine which takes a user-defined function to | ||
926 | integrate over. It's a bad idea to call a user-defined Lua function from | ||
927 | C code millions of times. The callback overhead will be absolutely | ||
928 | detrimental for performance. | ||
929 | </p> | ||
930 | <p> | ||
931 | It's considerably faster to write the numerical integration routine | ||
932 | itself in Lua — the JIT compiler will be able to inline the | ||
933 | user-defined function and optimize it together with its calling context, | ||
934 | with very competitive performance. | ||
935 | </p> | ||
936 | <p> | ||
937 | As a general guideline: <b>use callbacks only when you must</b>, because | ||
938 | of existing C APIs. E.g. callback performance is irrelevant for a | ||
939 | GUI application, which waits for user input most of the time, anyway. | ||
940 | </p> | ||
941 | <p> | ||
942 | For new designs <b>avoid push-style APIs</b> (C function repeatedly | ||
943 | calling a callback for each result). Instead <b>use pull-style APIs</b> | ||
944 | (call a C function repeatedly to get a new result). Calls from Lua | ||
945 | to C via the FFI are much faster than the other way round. Most well-designed | ||
946 | libraries already use pull-style APIs (read/write, get/put). | ||
947 | </p> | ||
948 | |||
949 | <h2 id="clib">C Library Namespaces</h2> | ||
950 | <p> | ||
951 | A C library namespace is a special kind of object which allows | ||
952 | access to the symbols contained in shared libraries or the default | ||
953 | symbol namespace. The default | ||
954 | <a href="ext_ffi_api.html#ffi_C"><tt>ffi.C</tt></a> namespace is | ||
955 | automatically created when the FFI library is loaded. C library | ||
956 | namespaces for specific shared libraries may be created with the | ||
957 | <a href="ext_ffi_api.html#ffi_load"><tt>ffi.load()</tt></a> API | ||
958 | function. | ||
959 | </p> | ||
960 | <p> | ||
961 | Indexing a C library namespace object with a symbol name (a Lua | ||
962 | string) automatically binds it to the library. First the symbol type | ||
963 | is resolved — it must have been declared with | ||
964 | <a href="ext_ffi_api.html#ffi_cdef"><tt>ffi.cdef</tt></a>. Then the | ||
965 | symbol address is resolved by searching for the symbol name in the | ||
966 | associated shared libraries or the default symbol namespace. Finally, | ||
967 | the resulting binding between the symbol name, the symbol type and its | ||
968 | address is cached. Missing symbol declarations or nonexistent symbol | ||
969 | names cause an error. | ||
970 | </p> | ||
971 | <p> | ||
972 | This is what happens on a <b>read access</b> for the different kinds of | ||
973 | symbols: | ||
974 | </p> | ||
975 | <ul> | ||
976 | |||
977 | <li>External functions: a cdata object with the type of the function | ||
978 | and its address is returned.</li> | ||
979 | |||
980 | <li>External variables: the symbol address is dereferenced and the | ||
981 | loaded value is <a href="#convert_tolua">converted to a Lua object</a> | ||
982 | and returned.</li> | ||
983 | |||
984 | <li>Constant values (<tt>static const</tt> or <tt>enum</tt> | ||
985 | constants): the constant is <a href="#convert_tolua">converted to a | ||
986 | Lua object</a> and returned.</li> | ||
987 | |||
988 | </ul> | ||
989 | <p> | ||
990 | This 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 type</a> of the | ||
996 | variable and then stored at the symbol address.</li> | ||
997 | |||
998 | <li>Writing to constant variables or to any other symbol type causes | ||
999 | an error, like any other attempted write to a constant location.</li> | ||
1000 | |||
1001 | </ul> | ||
1002 | <p> | ||
1003 | C library namespaces themselves are garbage collected objects. If | ||
1004 | the last reference to the namespace object is gone, the garbage | ||
1005 | collector will eventually release the shared library reference and | ||
1006 | remove all memory associated with the namespace. Since this may | ||
1007 | trigger the removal of the shared library from the memory of the | ||
1008 | running process, it's generally <em>not safe</em> to use function | ||
1009 | cdata objects obtained from a library if the namespace object may be | ||
1010 | unreferenced. | ||
1011 | </p> | ||
1012 | <p> | ||
1013 | Performance notice: the JIT compiler specializes to the identity of | ||
1014 | namespace objects and to the strings used to index it. This | ||
1015 | effectively turns function cdata objects into constants. It's not | ||
1016 | useful and actually counter-productive to explicitly cache these | ||
1017 | function 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 = | ||
1019 | ffi.C</tt>. | ||
1020 | </p> | ||
1021 | |||
1022 | <h2 id="policy">No Hand-holding!</h2> | ||
1023 | <p> | ||
1024 | The FFI library has been designed as <b>a low-level library</b>. The | ||
1025 | goal is to interface with C code and C data types with a | ||
1026 | minimum of overhead. This means <b>you can do anything you can do | ||
1027 | from C</b>: access all memory, overwrite anything in memory, call | ||
1028 | machine code at any memory address and so on. | ||
1029 | </p> | ||
1030 | <p> | ||
1031 | The FFI library provides <b>no memory safety</b>, unlike regular Lua | ||
1032 | code. It will happily allow you to dereference a <tt>NULL</tt> | ||
1033 | pointer, to access arrays out of bounds or to misdeclare | ||
1034 | C functions. If you make a mistake, your application might crash, | ||
1035 | just like equivalent C code would. | ||
1036 | </p> | ||
1037 | <p> | ||
1038 | This behavior is inevitable, since the goal is to provide full | ||
1039 | interoperability with C code. Adding extra safety measures, like | ||
1040 | bounds checks, would be futile. There's no way to detect | ||
1041 | misdeclarations of C functions, since shared libraries only | ||
1042 | provide symbol names, but no type information. Likewise there's no way | ||
1043 | to infer the valid range of indexes for a returned pointer. | ||
1044 | </p> | ||
1045 | <p> | ||
1046 | Again: the FFI library is a low-level library. This implies it needs | ||
1047 | to be used with care, but it's flexibility and performance often | ||
1048 | outweigh this concern. If you're a C or C++ developer, it'll be easy | ||
1049 | to apply your existing knowledge. OTOH writing code for the FFI | ||
1050 | library is not for the faint of heart and probably shouldn't be the | ||
1051 | first exercise for someone with little experience in Lua, C or C++. | ||
1052 | </p> | ||
1053 | <p> | ||
1054 | As a corollary of the above, the FFI library is <b>not safe for use by | ||
1055 | untrusted Lua code</b>. If you're sandboxing untrusted Lua code, you | ||
1056 | definitely don't want to give this code access to the FFI library or | ||
1057 | to <em>any</em> cdata object (except 64 bit integers or complex | ||
1058 | numbers). Any properly engineered Lua sandbox needs to provide safety | ||
1059 | wrappers for many of the standard Lua library functions — | ||
1060 | similar wrappers need to be written for high-level operations on FFI | ||
1061 | data types, too. | ||
1062 | </p> | ||
1063 | |||
1064 | <h2 id="status">Current Status</h2> | ||
1065 | <p> | ||
1066 | The initial release of the FFI library has some limitations and is | ||
1067 | missing some features. Most of these will be fixed in future releases. | ||
1068 | </p> | ||
1069 | <p> | ||
1070 | <a href="#clang">C language support</a> is | ||
1071 | currently incomplete: | ||
1072 | </p> | ||
1073 | <ul> | ||
1074 | <li>C declarations are not passed through a C pre-processor, | ||
1075 | yet.</li> | ||
1076 | <li>The C parser is able to evaluate most constant expressions | ||
1077 | commonly found in C header files. However it doesn't handle the | ||
1078 | full range of C expression semantics and may fail for some | ||
1079 | obscure constructs.</li> | ||
1080 | <li><tt>static const</tt> declarations only work for integer types | ||
1081 | up to 32 bits. Neither declaring string constants nor | ||
1082 | floating-point constants is supported.</li> | ||
1083 | <li>Packed <tt>struct</tt> bitfields that cross container boundaries | ||
1084 | are 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, | ||
1087 | storing and initializing them are supported, yet.</li> | ||
1088 | <li>The <tt>volatile</tt> type qualifier is currently ignored by | ||
1089 | compiled code.</li> | ||
1090 | <li><a href="ext_ffi_api.html#ffi_cdef"><tt>ffi.cdef</tt></a> silently | ||
1091 | ignores all re-declarations.</li> | ||
1092 | </ul> | ||
1093 | <p> | ||
1094 | The JIT compiler already handles a large subset of all FFI operations. | ||
1095 | It automatically falls back to the interpreter for unimplemented | ||
1096 | operations (you can check for this with the | ||
1097 | <a href="running.html#opt_j"><tt>-jv</tt></a> command line option). | ||
1098 | The following operations are currently not compiled and may exhibit | ||
1099 | suboptimal 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 types with a size > 64 bytes or an | ||
1109 | alignment > 8 bytes.</li> | ||
1110 | <li>Conversions from lightuserdata to <tt>void *</tt>.</li> | ||
1111 | <li>Pointer differences for element sizes that are not a power of | ||
1112 | two.</li> | ||
1113 | <li>Calls to C functions with aggregates passed or returned by | ||
1114 | value.</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> | ||
1120 | functions: <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> | ||
1125 | Other missing features: | ||
1126 | </p> | ||
1127 | <ul> | ||
1128 | <li>Bit operations for 64 bit types.</li> | ||
1129 | <li>Arithmetic for <tt>complex</tt> numbers.</li> | ||
1130 | <li>Passing structs by value to vararg C functions.</li> | ||
1131 | <li><a href="extensions.html#exceptions">C++ exception interoperability</a> | ||
1132 | does not extend to C functions called via the FFI, if the call is | ||
1133 | compiled.</li> | ||
1134 | </ul> | ||
1135 | <br class="flush"> | ||
1136 | </div> | ||
1137 | <div id="foot"> | ||
1138 | <hr class="hide"> | ||
1139 | Copyright © 2005-2011 Mike Pall | ||
1140 | <span class="noprint"> | ||
1141 | · | ||
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 deleted file mode 100644 index fb46a84..0000000 --- a/libraries/luajit-2.0/doc/ext_ffi_tutorial.html +++ /dev/null | |||
@@ -1,598 +0,0 @@ | |||
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"> | ||
12 | span.codemark { position:absolute; left: 16em; color: #4040c0; } | ||
13 | span.mark { color: #4040c0; font-family: Courier New, Courier, monospace; | ||
14 | line-height: 1.1; } | ||
15 | pre.mark { padding-left: 2em; } | ||
16 | table.idiomtable { line-height: 1.2; } | ||
17 | table.idiomtable tt { font-size: 100%; } | ||
18 | table.idiomtable td { vertical-align: top; } | ||
19 | tr.idiomhead td { font-weight: bold; } | ||
20 | td.idiomc { width: 12em; } | ||
21 | td.idiomlua { width: 14em; } | ||
22 | td.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">»</span></a> | ||
65 | </li><li> | ||
66 | <a href="http://luajit.org/download.html">Download <span class="ext">»</span></a> | ||
67 | </li></ul> | ||
68 | </div> | ||
69 | <div id="main"> | ||
70 | <p> | ||
71 | This page is intended to give you an overview of the features of the FFI | ||
72 | library by presenting a few use cases and guidelines. | ||
73 | </p> | ||
74 | <p> | ||
75 | This page makes no attempt to explain all of the FFI library, though. | ||
76 | You'll want to have a look at the <a href="ext_ffi_api.html">ffi.* API | ||
77 | function reference</a> and the <a href="ext_ffi_semantics.html">FFI | ||
78 | semantics</a> to learn more. | ||
79 | </p> | ||
80 | |||
81 | <h2 id="load">Loading the FFI Library</h2> | ||
82 | <p> | ||
83 | The FFI library is built into LuaJIT by default, but it's not loaded | ||
84 | and initialized by default. The suggested way to use the FFI library | ||
85 | is to add the following to the start of every Lua file that needs one | ||
86 | of its functions: | ||
87 | </p> | ||
88 | <pre class="code"> | ||
89 | local ffi = require("ffi") | ||
90 | </pre> | ||
91 | <p> | ||
92 | Please note this doesn't define an <tt>ffi</tt> variable in the table | ||
93 | of globals — 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> | ||
99 | The following code explains how to access standard system functions. | ||
100 | We slowly print two lines of dots by sleeping for 10 milliseconds | ||
101 | after each dot: | ||
102 | </p> | ||
103 | <pre class="code mark"> | ||
104 | <span class="codemark"> | ||
105 | ① | ||
106 | |||
107 | |||
108 | |||
109 | |||
110 | |||
111 | ② | ||
112 | ③ | ||
113 | ④ | ||
114 | |||
115 | |||
116 | |||
117 | ⑤ | ||
118 | |||
119 | |||
120 | |||
121 | |||
122 | |||
123 | ⑥</span>local ffi = require("ffi") | ||
124 | ffi.cdef[[ | ||
125 | <span style="color:#00a000;">void Sleep(int ms); | ||
126 | int poll(struct pollfd *fds, unsigned long nfds, int timeout);</span> | ||
127 | ]] | ||
128 | |||
129 | local sleep | ||
130 | if ffi.os == "Windows" then | ||
131 | function sleep(s) | ||
132 | ffi.C.Sleep(s*1000) | ||
133 | end | ||
134 | else | ||
135 | function sleep(s) | ||
136 | ffi.C.poll(nil, 0, s*1000) | ||
137 | end | ||
138 | end | ||
139 | |||
140 | for i=1,160 do | ||
141 | io.write("."); io.flush() | ||
142 | sleep(0.01) | ||
143 | end | ||
144 | io.write("\n") | ||
145 | </pre> | ||
146 | <p> | ||
147 | Here's the step-by-step explanation: | ||
148 | </p> | ||
149 | <p> | ||
150 | <span class="mark">①</span> This defines the | ||
151 | C library functions we're going to use. The part inside the | ||
152 | double-brackets (in green) is just standard C syntax. You can | ||
153 | usually get this info from the C header files or the | ||
154 | documentation provided by each C library or C compiler. | ||
155 | </p> | ||
156 | <p> | ||
157 | <span class="mark">②</span> The difficulty we're | ||
158 | facing here, is that there are different standards to choose from. | ||
159 | Windows has a simple <tt>Sleep()</tt> function. On other systems there | ||
160 | are a variety of functions available to achieve sub-second sleeps, but | ||
161 | with no clear consensus. Thankfully <tt>poll()</tt> can be used for | ||
162 | this task, too, and it's present on most non-Windows systems. The | ||
163 | check for <tt>ffi.os</tt> makes sure we use the Windows-specific | ||
164 | function only on Windows systems. | ||
165 | </p> | ||
166 | <p> | ||
167 | <span class="mark">③</span> Here we're wrapping the | ||
168 | call to the C function in a Lua function. This isn't strictly | ||
169 | necessary, but it's helpful to deal with system-specific issues only | ||
170 | in one part of the code. The way we're wrapping it ensures the check | ||
171 | for the OS is only done during initialization and not for every call. | ||
172 | </p> | ||
173 | <p> | ||
174 | <span class="mark">④</span> A more subtle point is | ||
175 | that we defined our <tt>sleep()</tt> function (for the sake of this | ||
176 | example) as taking the number of seconds, but accepting fractional | ||
177 | seconds. Multiplying this by 1000 gets us milliseconds, but that still | ||
178 | leaves it a Lua number, which is a floating-point value. Alas, the | ||
179 | <tt>Sleep()</tt> function only accepts an integer value. Luckily for | ||
180 | us, the FFI library automatically performs the conversion when calling | ||
181 | the function (truncating the FP value towards zero, like in C). | ||
182 | </p> | ||
183 | <p style="font-size: 8pt;"> | ||
184 | Some 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 | ||
186 | can this possibly work? The FFI library provides the <tt>ffi.C</tt> | ||
187 | default C library namespace, which allows calling functions from | ||
188 | the default set of libraries, like a C compiler would. Also, the | ||
189 | FFI library automatically detects <tt>stdcall</tt> functions, so you | ||
190 | don't need to declare them as such. | ||
191 | </p> | ||
192 | <p> | ||
193 | <span class="mark">⑤</span> The <tt>poll()</tt> | ||
194 | function takes a couple more arguments we're not going to use. You can | ||
195 | simply use <tt>nil</tt> to pass a <tt>NULL</tt> pointer and <tt>0</tt> | ||
196 | for the <tt>nfds</tt> parameter. Please note that the | ||
197 | number <tt>0</tt> <em>does not convert to a pointer value</em>, | ||
198 | unlike in C++. You really have to pass pointers to pointer arguments | ||
199 | and numbers to number arguments. | ||
200 | </p> | ||
201 | <p style="font-size: 8pt;"> | ||
202 | The page on <a href="ext_ffi_semantics.html">FFI semantics</a> has all | ||
203 | of the gory details about | ||
204 | <a href="ext_ffi_semantics.html#convert">conversions between Lua | ||
205 | objects and C types</a>. For the most part you don't have to deal | ||
206 | with this, as it's performed automatically and it's carefully designed | ||
207 | to bridge the semantic differences between Lua and C. | ||
208 | </p> | ||
209 | <p> | ||
210 | <span class="mark">⑥</span> Now that we have defined | ||
211 | our own <tt>sleep()</tt> function, we can just call it from plain Lua | ||
212 | code. That wasn't so bad, huh? Turning these boring animated dots into | ||
213 | a 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> | ||
219 | The following code shows how to access the <a | ||
220 | href="http://zlib.net/">zlib</a> compression library from Lua code. | ||
221 | We'll define two convenience wrapper functions that take a string and | ||
222 | compress or uncompress it to another string: | ||
223 | </p> | ||
224 | <pre class="code mark"> | ||
225 | <span class="codemark"> | ||
226 | ① | ||
227 | |||
228 | |||
229 | |||
230 | |||
231 | |||
232 | |||
233 | ② | ||
234 | |||
235 | |||
236 | ③ | ||
237 | |||
238 | ④ | ||
239 | |||
240 | |||
241 | ⑤ | ||
242 | |||
243 | |||
244 | ⑥ | ||
245 | |||
246 | |||
247 | |||
248 | |||
249 | |||
250 | |||
251 | |||
252 | ⑦</span>local ffi = require("ffi") | ||
253 | ffi.cdef[[ | ||
254 | <span style="color:#00a000;">unsigned long compressBound(unsigned long sourceLen); | ||
255 | int compress2(uint8_t *dest, unsigned long *destLen, | ||
256 | const uint8_t *source, unsigned long sourceLen, int level); | ||
257 | int uncompress(uint8_t *dest, unsigned long *destLen, | ||
258 | const uint8_t *source, unsigned long sourceLen);</span> | ||
259 | ]] | ||
260 | local zlib = ffi.load(ffi.os == "Windows" and "zlib1" or "z") | ||
261 | |||
262 | local 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]) | ||
269 | end | ||
270 | |||
271 | local 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]) | ||
277 | end | ||
278 | |||
279 | -- Simple test code. | ||
280 | local txt = string.rep("abcd", 1000) | ||
281 | print("Uncompressed size: ", #txt) | ||
282 | local c = compress(txt) | ||
283 | print("Compressed size: ", #c) | ||
284 | local txt2 = uncompress(c, #txt) | ||
285 | assert(txt2 == txt) | ||
286 | </pre> | ||
287 | <p> | ||
288 | Here's the step-by-step explanation: | ||
289 | </p> | ||
290 | <p> | ||
291 | <span class="mark">①</span> This defines some of the | ||
292 | C functions provided by zlib. For the sake of this example, some | ||
293 | type indirections have been reduced and it uses the pre-defined | ||
294 | fixed-size integer types, while still adhering to the zlib API/ABI. | ||
295 | </p> | ||
296 | <p> | ||
297 | <span class="mark">②</span> This loads the zlib shared | ||
298 | library. On POSIX systems it's named <tt>libz.so</tt> and usually | ||
299 | comes pre-installed. Since <tt>ffi.load()</tt> automatically adds any | ||
300 | missing standard prefixes/suffixes, we can simply load the | ||
301 | <tt>"z"</tt> library. On Windows it's named <tt>zlib1.dll</tt> and | ||
302 | you'll have to download it first from the | ||
303 | <a href="http://zlib.net/"><span class="ext">»</span> 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">③</span> First, the maximum size of | ||
309 | the compression buffer is obtained by calling the | ||
310 | <tt>zlib.compressBound</tt> function with the length of the | ||
311 | uncompressed string. The next line allocates a byte buffer of this | ||
312 | size. The <tt>[?]</tt> in the type specification indicates a | ||
313 | variable-length array (VLA). The actual number of elements of this | ||
314 | array is given as the 2nd argument to <tt>ffi.new()</tt>. | ||
315 | </p> | ||
316 | <p> | ||
317 | <span class="mark">④</span> This may look strange at | ||
318 | first, but have a look at the declaration of the <tt>compress2</tt> | ||
319 | function from zlib: the destination length is defined as a pointer! | ||
320 | This is because you pass in the maximum buffer size and get back the | ||
321 | actual length that was used. | ||
322 | </p> | ||
323 | <p> | ||
324 | In C you'd pass in the address of a local variable | ||
325 | (<tt>&buflen</tt>). But since there's no address-of operator in | ||
326 | Lua, we'll just pass in a one-element array. Conveniently it can be | ||
327 | initialized with the maximum buffer size in one step. Calling the | ||
328 | actual <tt>zlib.compress2</tt> function is then straightforward. | ||
329 | </p> | ||
330 | <p> | ||
331 | <span class="mark">⑤</span> We want to return the | ||
332 | compressed data as a Lua string, so we'll use <tt>ffi.string()</tt>. | ||
333 | It needs a pointer to the start of the data and the actual length. The | ||
334 | length has been returned in the <tt>buflen</tt> array, so we'll just | ||
335 | get it from there. | ||
336 | </p> | ||
337 | <p style="font-size: 8pt;"> | ||
338 | Note that since the function returns now, the <tt>buf</tt> and | ||
339 | <tt>buflen</tt> variables will eventually be garbage collected. This | ||
340 | is fine, because <tt>ffi.string()</tt> has copied the contents to a | ||
341 | newly created (interned) Lua string. If you plan to call this function | ||
342 | lots of times, consider reusing the buffers and/or handing back the | ||
343 | results in buffers instead of strings. This will reduce the overhead | ||
344 | for garbage collection and string interning. | ||
345 | </p> | ||
346 | <p> | ||
347 | <span class="mark">⑥</span> The <tt>uncompress</tt> | ||
348 | functions does the exact opposite of the <tt>compress</tt> function. | ||
349 | The compressed data doesn't include the size of the original string, | ||
350 | so this needs to be passed in. Otherwise no surprises here. | ||
351 | </p> | ||
352 | <p> | ||
353 | <span class="mark">⑦</span> The code, that makes use | ||
354 | of the functions we just defined, is just plain Lua code. It doesn't | ||
355 | need to know anything about the LuaJIT FFI — the convenience | ||
356 | wrapper functions completely hide it. | ||
357 | </p> | ||
358 | <p> | ||
359 | One major advantage of the LuaJIT FFI is that you are now able to | ||
360 | write those wrappers <em>in Lua</em>. And at a fraction of the time it | ||
361 | would cost you to create an extra C module using the Lua/C API. | ||
362 | Many of the simpler C functions can probably be used directly | ||
363 | from your Lua code, without any wrappers. | ||
364 | </p> | ||
365 | <p style="font-size: 8pt;"> | ||
366 | Side note: the zlib API uses the <tt>long</tt> type for passing | ||
367 | lengths and sizes around. But all those zlib functions actually only | ||
368 | deal with 32 bit values. This is an unfortunate choice for a | ||
369 | public API, but may be explained by zlib's history — we'll just | ||
370 | have to deal with it. | ||
371 | </p> | ||
372 | <p style="font-size: 8pt;"> | ||
373 | First, you should know that a <tt>long</tt> is a 64 bit type e.g. | ||
374 | on POSIX/x64 systems, but a 32 bit type on Windows/x64 and on | ||
375 | 32 bit systems. Thus a <tt>long</tt> result can be either a plain | ||
376 | Lua number or a boxed 64 bit integer cdata object, depending on | ||
377 | the target system. | ||
378 | </p> | ||
379 | <p style="font-size: 8pt;"> | ||
380 | Ok, so the <tt>ffi.*</tt> functions generally accept cdata objects | ||
381 | wherever you'd want to use a number. That's why we get a away with | ||
382 | passing <tt>n</tt> to <tt>ffi.string()</tt> above. But other Lua | ||
383 | library functions or modules don't know how to deal with this. So for | ||
384 | maximum portability one needs to use <tt>tonumber()</tt> on returned | ||
385 | <tt>long</tt> results before passing them on. Otherwise the | ||
386 | application might work on some systems, but would fail in a POSIX/x64 | ||
387 | environment. | ||
388 | </p> | ||
389 | |||
390 | <h2 id="metatype">Defining Metamethods for a C Type</h2> | ||
391 | <p> | ||
392 | The following code explains how to define metamethods for a C type. | ||
393 | We define a simple point type and add some operations to it: | ||
394 | </p> | ||
395 | <pre class="code mark"> | ||
396 | <span class="codemark"> | ||
397 | ① | ||
398 | |||
399 | |||
400 | |||
401 | ② | ||
402 | |||
403 | ③ | ||
404 | |||
405 | ④ | ||
406 | |||
407 | |||
408 | |||
409 | ⑤ | ||
410 | |||
411 | ⑥</span>local ffi = require("ffi") | ||
412 | ffi.cdef[[ | ||
413 | <span style="color:#00a000;">typedef struct { double x, y; } point_t;</span> | ||
414 | ]] | ||
415 | |||
416 | local point | ||
417 | local 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 | } | ||
424 | point = ffi.metatype("point_t", mt) | ||
425 | |||
426 | local a = point(3, 4) | ||
427 | print(a.x, a.y) --> 3 4 | ||
428 | print(#a) --> 5 | ||
429 | print(a:area()) --> 25 | ||
430 | local b = a + point(0.5, 8) | ||
431 | print(#b) --> 12.5 | ||
432 | </pre> | ||
433 | <p> | ||
434 | Here's the step-by-step explanation: | ||
435 | </p> | ||
436 | <p> | ||
437 | <span class="mark">①</span> This defines the C type for a | ||
438 | two-dimensional point object. | ||
439 | </p> | ||
440 | <p> | ||
441 | <span class="mark">②</span> We have to declare the variable | ||
442 | holding the point constructor first, because it's used inside of a | ||
443 | metamethod. | ||
444 | </p> | ||
445 | <p> | ||
446 | <span class="mark">③</span> Let's define an <tt>__add</tt> | ||
447 | metamethod which adds the coordinates of two points and creates a new | ||
448 | point object. For simplicity, this function assumes that both arguments | ||
449 | are points. But it could be any mix of objects, if at least one operand | ||
450 | is of the required type (e.g. adding a point plus a number or vice | ||
451 | versa). Our <tt>__len</tt> metamethod returns the distance of a point to | ||
452 | the origin. | ||
453 | </p> | ||
454 | <p> | ||
455 | <span class="mark">④</span> If we run out of operators, we can | ||
456 | define named methods, too. Here the <tt>__index</tt> table defines an | ||
457 | <tt>area</tt> function. For custom indexing needs, one might want to | ||
458 | define <tt>__index</tt> and <tt>__newindex</tt> <em>functions</em> instead. | ||
459 | </p> | ||
460 | <p> | ||
461 | <span class="mark">⑤</span> This associates the metamethods with | ||
462 | our C type. This only needs to be done once. For convenience, a | ||
463 | constructor is returned by | ||
464 | <a href="ext_ffi_api.html#ffi_metatype"><tt>ffi.metatype()</tt></a>. | ||
465 | We're not required to use it, though. The original C type can still | ||
466 | be used e.g. to create an array of points. The metamethods automatically | ||
467 | apply to any and all uses of this type. | ||
468 | </p> | ||
469 | <p> | ||
470 | Please 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">⑥</span> Here are some simple usage examples | ||
476 | for the point type and their expected results. The pre-defined | ||
477 | operations (such as <tt>a.x</tt>) can be freely mixed with the newly | ||
478 | defined metamethods. Note that <tt>area</tt> is a method and must be | ||
479 | called with the Lua syntax for methods: <tt>a:area()</tt>, not | ||
480 | <tt>a.area()</tt>. | ||
481 | </p> | ||
482 | <p> | ||
483 | The C type metamethod mechanism is most useful when used in | ||
484 | conjunction with C libraries that are written in an object-oriented | ||
485 | style. Creators return a pointer to a new instance and methods take an | ||
486 | instance pointer as the first argument. Sometimes you can just point | ||
487 | <tt>__index</tt> to the library namespace and <tt>__gc</tt> to the | ||
488 | destructor and you're done. But often enough you'll want to add | ||
489 | convenience wrappers, e.g. to return actual Lua strings or when | ||
490 | returning multiple values. | ||
491 | </p> | ||
492 | <p> | ||
493 | Some C libraries only declare instance pointers as an opaque | ||
494 | <tt>void *</tt> type. In this case you can use a fake type for all | ||
495 | declarations, e.g. a pointer to a named (incomplete) struct will do: | ||
496 | <tt>typedef struct foo_type *foo_handle</tt>. The C side doesn't | ||
497 | know what you declare with the LuaJIT FFI, but as long as the underlying | ||
498 | types are compatible, everything still works. | ||
499 | </p> | ||
500 | |||
501 | <h2 id="idioms">Translating C Idioms</h2> | ||
502 | <p> | ||
503 | Here's a list of common C idioms and their translation to the | ||
504 | LuaJIT FFI: | ||
505 | </p> | ||
506 | <table class="idiomtable"> | ||
507 | <tr class="idiomhead"> | ||
508 | <td class="idiomdesc">Idiom</td> | ||
509 | <td class="idiomc">C 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 = &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> ffi.cast("intptr_t",<br> 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(&len);<br>y = len;</tt></td><td class="idiomlua"><tt><b>local len =<br> 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> </tt></td><td class="idiomlua"><tt>printf("%g", 1);<br>printf("%d",<br> <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> | ||
538 | It's a common Lua idiom to cache library functions in local variables | ||
539 | or upvalues, e.g.: | ||
540 | </p> | ||
541 | <pre class="code"> | ||
542 | local byte, char = string.byte, string.char | ||
543 | local function foo(x) | ||
544 | return char(byte(x)+1) | ||
545 | end | ||
546 | </pre> | ||
547 | <p> | ||
548 | This replaces several hash-table lookups with a (faster) direct use of | ||
549 | a local or an upvalue. This is less important with LuaJIT, since the | ||
550 | JIT compiler optimizes hash-table lookups a lot and is even able to | ||
551 | hoist 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 | ||
553 | functions. So there's still a place for this, even with LuaJIT. | ||
554 | </p> | ||
555 | <p> | ||
556 | The situation is a bit different with C function calls via the | ||
557 | FFI library. The JIT compiler has special logic to eliminate <em>all | ||
558 | of the lookup overhead</em> for functions resolved from a | ||
559 | <a href="ext_ffi_semantics.html#clib">C library namespace</a>! | ||
560 | Thus it's not helpful and actually counter-productive to cache | ||
561 | individual C functions like this: | ||
562 | </p> | ||
563 | <pre class="code"> | ||
564 | local <b>funca</b>, <b>funcb</b> = ffi.C.funcb, ffi.C.funcb -- <span style="color:#c00000;">Not helpful!</span> | ||
565 | local function foo(x, n) | ||
566 | for i=1,n do <b>funcb</b>(<b>funca</b>(x, i), 1) end | ||
567 | end | ||
568 | </pre> | ||
569 | <p> | ||
570 | This turns them into indirect calls and generates bigger and slower | ||
571 | machine code. Instead you'll want to cache the namespace itself and | ||
572 | rely on the JIT compiler to eliminate the lookups: | ||
573 | </p> | ||
574 | <pre class="code"> | ||
575 | local <b>C</b> = ffi.C -- <span style="color:#00a000;">Instead use this!</span> | ||
576 | local function foo(x, n) | ||
577 | for i=1,n do <b>C.funcb</b>(<b>C.funca</b>(x, i), 1) end | ||
578 | end | ||
579 | </pre> | ||
580 | <p> | ||
581 | This generates both shorter and faster code. So <b>don't cache | ||
582 | C functions</b>, but <b>do</b> cache namespaces! Most often the | ||
583 | namespace is already in a local variable at an outer scope, e.g. from | ||
584 | <tt>local lib = ffi.load(...)</tt>. Note that copying | ||
585 | it 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"> | ||
591 | Copyright © 2005-2011 Mike Pall | ||
592 | <span class="noprint"> | ||
593 | · | ||
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 deleted file mode 100644 index e8f5518..0000000 --- a/libraries/luajit-2.0/doc/ext_jit.html +++ /dev/null | |||
@@ -1,195 +0,0 @@ | |||
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">»</span></a> | ||
52 | </li><li> | ||
53 | <a href="http://luajit.org/download.html">Download <span class="ext">»</span></a> | ||
54 | </li></ul> | ||
55 | </div> | ||
56 | <div id="main"> | ||
57 | <p> | ||
58 | The functions in this built-in module control the behavior of the JIT | ||
59 | compiler engine. Note that JIT-compilation is fully automatic — | ||
60 | you probably won't need to use any of the following functions unless | ||
61 | you have special needs. | ||
62 | </p> | ||
63 | |||
64 | <h3 id="jit_onoff"><tt>jit.on()<br> | ||
65 | jit.off()</tt></h3> | ||
66 | <p> | ||
67 | Turns the whole JIT compiler on (default) or off. | ||
68 | </p> | ||
69 | <p> | ||
70 | These 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> | ||
76 | Flushes the whole cache of compiled code. | ||
77 | </p> | ||
78 | |||
79 | <h3 id="jit_onoff_func"><tt>jit.on(func|true [,true|false])<br> | ||
80 | jit.off(func|true [,true|false])<br> | ||
81 | jit.flush(func|true [,true|false])</tt></h3> | ||
82 | <p> | ||
83 | <tt>jit.on</tt> enables JIT compilation for a Lua function (this is | ||
84 | the default). | ||
85 | </p> | ||
86 | <p> | ||
87 | <tt>jit.off</tt> disables JIT compilation for a Lua function and | ||
88 | flushes 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 | ||
92 | enable/disable status. | ||
93 | </p> | ||
94 | <p> | ||
95 | The current function, i.e. the Lua function calling this library | ||
96 | function, can also be specified by passing <tt>true</tt> as the first | ||
97 | argument. | ||
98 | </p> | ||
99 | <p> | ||
100 | If the second argument is <tt>true</tt>, JIT compilation is also | ||
101 | enabled, disabled or flushed recursively for all sub-functions of a | ||
102 | function. With <tt>false</tt> only the sub-functions are affected. | ||
103 | </p> | ||
104 | <p> | ||
105 | The <tt>jit.on</tt> and <tt>jit.off</tt> functions only set a flag | ||
106 | which is checked when the function is about to be compiled. They do | ||
107 | not trigger immediate compilation. | ||
108 | </p> | ||
109 | <p> | ||
110 | Typical usage is <tt>jit.off(true, true)</tt> in the main chunk | ||
111 | of a module to turn off JIT compilation for the whole module for | ||
112 | debugging purposes. | ||
113 | </p> | ||
114 | |||
115 | <h3 id="jit_flush_tr"><tt>jit.flush(tr)</tt></h3> | ||
116 | <p> | ||
117 | Flushes the root trace, specified by its number, and all of its side | ||
118 | traces from the cache. The code for the trace will be retained as long | ||
119 | as 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> | ||
124 | Returns the current status of the JIT compiler. The first result is | ||
125 | either <tt>true</tt> or <tt>false</tt> if the JIT compiler is turned | ||
126 | on or off. The remaining results are strings for CPU-specific features | ||
127 | and enabled optimizations. | ||
128 | </p> | ||
129 | |||
130 | <h3 id="jit_version"><tt>jit.version</tt></h3> | ||
131 | <p> | ||
132 | Contains the LuaJIT version string. | ||
133 | </p> | ||
134 | |||
135 | <h3 id="jit_version_num"><tt>jit.version_num</tt></h3> | ||
136 | <p> | ||
137 | Contains the version number of the LuaJIT core. Version xx.yy.zz | ||
138 | is represented by the decimal number xxyyzz. | ||
139 | </p> | ||
140 | |||
141 | <h3 id="jit_os"><tt>jit.os</tt></h3> | ||
142 | <p> | ||
143 | Contains 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> | ||
149 | Contains the target architecture name: | ||
150 | "x86", "x64" or "ppcspe". | ||
151 | </p> | ||
152 | |||
153 | <h2 id="jit_opt"><tt>jit.opt.*</tt> — JIT compiler optimization control</h2> | ||
154 | <p> | ||
155 | This sub-module provides the backend for the <tt>-O</tt> command line | ||
156 | option. | ||
157 | </p> | ||
158 | <p> | ||
159 | You can also use it programmatically, e.g.: | ||
160 | </p> | ||
161 | <pre class="code"> | ||
162 | jit.opt.start(2) -- same as -O2 | ||
163 | jit.opt.start("-dce") | ||
164 | jit.opt.start("hotloop=10", "hotexit=2") | ||
165 | </pre> | ||
166 | <p> | ||
167 | Unlike in LuaJIT 1.x, the module is built-in and | ||
168 | <b>optimization is turned on by default!</b> | ||
169 | It's no longer necessary to run <tt>require("jit.opt").start()</tt>, | ||
170 | which was one of the ways to enable optimization. | ||
171 | </p> | ||
172 | |||
173 | <h2 id="jit_util"><tt>jit.util.*</tt> — JIT compiler introspection</h2> | ||
174 | <p> | ||
175 | This sub-module holds functions to introspect the bytecode, generated | ||
176 | traces, the IR and the generated machine code. The functionality | ||
177 | provided by this module is still in flux and therefore undocumented. | ||
178 | </p> | ||
179 | <p> | ||
180 | The debug modules <tt>-jbc</tt>, <tt>-jv</tt> and <tt>-jdump</tt> make | ||
181 | extensive use of these functions. Please check out their source code, | ||
182 | if you want to know more. | ||
183 | </p> | ||
184 | <br class="flush"> | ||
185 | </div> | ||
186 | <div id="foot"> | ||
187 | <hr class="hide"> | ||
188 | Copyright © 2005-2011 Mike Pall | ||
189 | <span class="noprint"> | ||
190 | · | ||
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 deleted file mode 100644 index b0e1164..0000000 --- a/libraries/luajit-2.0/doc/extensions.html +++ /dev/null | |||
@@ -1,336 +0,0 @@ | |||
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"> | ||
12 | table.exc { | ||
13 | line-height: 1.2; | ||
14 | } | ||
15 | tr.exchead td { | ||
16 | font-weight: bold; | ||
17 | } | ||
18 | td.excplatform { | ||
19 | width: 48%; | ||
20 | } | ||
21 | td.exccompiler { | ||
22 | width: 29%; | ||
23 | } | ||
24 | td.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">»</span></a> | ||
69 | </li><li> | ||
70 | <a href="http://luajit.org/download.html">Download <span class="ext">»</span></a> | ||
71 | </li></ul> | ||
72 | </div> | ||
73 | <div id="main"> | ||
74 | <p> | ||
75 | LuaJIT 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">»</span> standard Lua | ||
77 | library functions</a> and the full set of | ||
78 | <a href="http://www.lua.org/manual/5.1/manual.html#3"><span class="ext">»</span> Lua/C API | ||
79 | functions</a>. | ||
80 | </p> | ||
81 | <p> | ||
82 | LuaJIT is also fully ABI-compatible to Lua 5.1 at the linker/dynamic | ||
83 | loader level. This means you can compile a C module against the | ||
84 | standard Lua headers and load the same shared library from either Lua | ||
85 | or LuaJIT. | ||
86 | </p> | ||
87 | <p> | ||
88 | LuaJIT extends the standard Lua VM with new functionality and adds | ||
89 | several extension modules. Please note that this page is only about | ||
90 | <em>functional</em> enhancements and not about performance enhancements, | ||
91 | such as the optimized VM, the faster interpreter or the JIT compiler. | ||
92 | </p> | ||
93 | |||
94 | <h2 id="modules">Extensions Modules</h2> | ||
95 | <p> | ||
96 | LuaJIT comes with several built-in extension modules: | ||
97 | </p> | ||
98 | |||
99 | <h3 id="bit"><tt>bit.*</tt> — Bitwise operations</h3> | ||
100 | <p> | ||
101 | LuaJIT supports all bitwise operations as defined by | ||
102 | <a href="http://bitop.luajit.org"><span class="ext">»</span> Lua BitOp</a>: | ||
103 | </p> | ||
104 | <pre class="code"> | ||
105 | bit.tobit bit.tohex bit.bnot bit.band bit.bor bit.bxor | ||
106 | bit.lshift bit.rshift bit.arshift bit.rol bit.ror bit.bswap | ||
107 | </pre> | ||
108 | <p> | ||
109 | This module is a LuaJIT built-in — you don't need to download or | ||
110 | install Lua BitOp. The Lua BitOp site has full documentation for all | ||
111 | <a href="http://bitop.luajit.org/api.html"><span class="ext">»</span> Lua BitOp API functions</a>. | ||
112 | </p> | ||
113 | <p> | ||
114 | Please make sure to <tt>require</tt> the module before using any of | ||
115 | its functions: | ||
116 | </p> | ||
117 | <pre class="code"> | ||
118 | local bit = require("bit") | ||
119 | </pre> | ||
120 | <p> | ||
121 | An already installed Lua BitOp module is ignored by LuaJIT. | ||
122 | This way you can use bit operations from both Lua and LuaJIT on a | ||
123 | shared installation. | ||
124 | </p> | ||
125 | |||
126 | <h3 id="ffi"><tt>ffi.*</tt> — FFI library</h3> | ||
127 | <p> | ||
128 | The <a href="ext_ffi.html">FFI library</a> allows calling external | ||
129 | C functions and the use of C data structures from pure Lua | ||
130 | code. | ||
131 | </p> | ||
132 | |||
133 | <h3 id="jit"><tt>jit.*</tt> — JIT compiler control</h3> | ||
134 | <p> | ||
135 | The 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> | ||
141 | LuaJIT 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> | ||
149 | Unlike the standard implementation in Lua 5.1, <tt>xpcall()</tt> | ||
150 | passes any arguments after the error function to the function | ||
151 | which 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> | ||
156 | Non-ASCII characters are handled transparently by the Lua source code parser. | ||
157 | This allows the use of UTF-8 characters in identifiers and strings. | ||
158 | A 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 ±Inf</h3> | ||
162 | <p> | ||
163 | All number-to-string conversions consistently convert non-finite numbers | ||
164 | to the same strings on all platforms. NaN results in <tt>"nan"</tt>, | ||
165 | positive infinity results in <tt>"inf"</tt> and negative infinity results | ||
166 | in <tt>"-inf"</tt>. | ||
167 | </p> | ||
168 | |||
169 | <h3 id="string_dump"><tt>string.dump(f [,strip])</tt> generates portable bytecode</h3> | ||
170 | <p> | ||
171 | An extra argument has been added to <tt>string.dump()</tt>. If set to | ||
172 | <tt>true</tt>, 'stripped' bytecode without debug information is | ||
173 | generated. This speeds up later bytecode loading and reduces memory | ||
174 | usage. See also the | ||
175 | <a href="running.html#opt_b"><tt>-b</tt> command line option</a>. | ||
176 | </p> | ||
177 | <p> | ||
178 | The generated bytecode is portable and can be loaded on any architecture | ||
179 | that LuaJIT supports, independent of word size or endianess. However the | ||
180 | bytecode compatibility versions must match. Bytecode stays compatible | ||
181 | for dot releases (x.y.0 → x.y.1), but may change with major or | ||
182 | minor releases (2.0 → 2.1) or between any beta release. Foreign | ||
183 | bytecode (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> | ||
188 | LuaJIT uses a Tausworthe PRNG with period 2^223 to implement | ||
189 | <tt>math.random()</tt> and <tt>math.randomseed()</tt>. The quality of | ||
190 | the PRNG results is much superior compared to the standard Lua | ||
191 | implementation which uses the platform-specific ANSI rand(). | ||
192 | </p> | ||
193 | <p> | ||
194 | The PRNG generates the same sequences from the same seeds on all | ||
195 | platforms and makes use of all bits in the seed argument. | ||
196 | <tt>math.random()</tt> without arguments generates 52 pseudo-random bits | ||
197 | for every call. The result is uniformly distributed between 0 and 1. | ||
198 | It's correctly scaled up and rounded for <tt>math.random(n [,m])</tt> to | ||
199 | preserve uniformity. | ||
200 | </p> | ||
201 | |||
202 | <h3 id="io"><tt>io.*</tt> functions handle 64 bit file offsets</h3> | ||
203 | <p> | ||
204 | The file I/O functions in the standard <tt>io.*</tt> library handle | ||
205 | 64 bit file offsets. In particular this means it's possible | ||
206 | to open files larger than 2 Gigabytes and to reposition or obtain | ||
207 | the current file position for offsets beyond 2 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 | ||
214 | about invoked metamethods. The <tt>namewhat</tt> field is set to | ||
215 | <tt>"metamethod"</tt> and the <tt>name</tt> field has the name of | ||
216 | the corresponding metamethod (e.g. <tt>"__index"</tt>). | ||
217 | </p> | ||
218 | |||
219 | <h2 id="resumable">Fully Resumable VM</h2> | ||
220 | <p> | ||
221 | The LuaJIT 2.x VM is fully resumable. This means you can yield from a | ||
222 | coroutine even across contexts, where this would not possible with | ||
223 | the standard Lua 5.1 VM: e.g. you can yield across <tt>pcall()</tt> | ||
224 | and <tt>xpcall()</tt>, across iterators and across metamethods. | ||
225 | </p> | ||
226 | <p> | ||
227 | Note however that LuaJIT 2.x doesn't use | ||
228 | <a href="http://coco.luajit.org/"><span class="ext">»</span> Coco</a> anymore. This means the | ||
229 | overhead for creating coroutines is much smaller and no extra | ||
230 | C stacks need to be allocated. OTOH you can no longer yield | ||
231 | across arbitrary C functions. Keep this in mind when | ||
232 | upgrading from LuaJIT 1.x. | ||
233 | </p> | ||
234 | |||
235 | <h2 id="exceptions">C++ Exception Interoperability</h2> | ||
236 | <p> | ||
237 | LuaJIT has built-in support for interoperating with C++ exceptions. | ||
238 | The available range of features depends on the target platform and | ||
239 | the 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++ exceptions can be caught on the Lua side with <tt>pcall()</tt>, | ||
278 | <tt>lua_pcall()</tt> etc.</li> | ||
279 | <li>C++ exceptions will be converted to the generic Lua error | ||
280 | <tt>"C++ exception"</tt>, unless you use the | ||
281 | <a href="ext_c_api.html#mode_wrapcfunc">C call wrapper</a> feature.</li> | ||
282 | <li>It's safe to throw C++ exceptions across non-protected Lua frames | ||
283 | on the C stack. The contents of the C++ exception object | ||
284 | pass through unmodified.</li> | ||
285 | <li>Lua errors can be caught on the C++ side with <tt>catch(...)</tt>. | ||
286 | The corresponding Lua error message can be retrieved from the Lua stack.</li> | ||
287 | <li>Throwing Lua errors across C++ frames is safe. C++ destructors | ||
288 | will be called.</li> | ||
289 | </ul> | ||
290 | <p> | ||
291 | <b style="color: #c06000;">Limited interoperability</b> means: | ||
292 | </p> | ||
293 | <ul> | ||
294 | <li>C++ exceptions can be caught on the Lua side with <tt>pcall()</tt>, | ||
295 | <tt>lua_pcall()</tt> etc.</li> | ||
296 | <li>C++ exceptions will be converted to the generic Lua error | ||
297 | <tt>"C++ exception"</tt>, unless you use the | ||
298 | <a href="ext_c_api.html#mode_wrapcfunc">C call wrapper</a> feature.</li> | ||
299 | <li>C++ exceptions will be caught by non-protected Lua frames and | ||
300 | are rethrown as a generic Lua error. The C++ exception object will | ||
301 | be 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 | ||
304 | C++ 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++ exceptions across Lua frames.</li> | ||
312 | <li>C++ 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 | ||
315 | C++ destructors.</li> | ||
316 | <li>Additionally, on Windows/x86 with SEH-based C++ exceptions: | ||
317 | it's <b>not</b> safe to throw a Lua error across any frames containing | ||
318 | a C++ function with any try/catch construct or using variables with | ||
319 | (implicit) destructors. This also applies to any functions which may be | ||
320 | inlined in such a function. It doesn't matter whether <tt>lua_error()</tt> | ||
321 | is called inside or outside of a try/catch or whether any object actually | ||
322 | needs to be destroyed: the SEH chain is corrupted and this will eventually | ||
323 | lead to the termination of the process.</li> | ||
324 | </ul> | ||
325 | <br class="flush"> | ||
326 | </div> | ||
327 | <div id="foot"> | ||
328 | <hr class="hide"> | ||
329 | Copyright © 2005-2011 Mike Pall | ||
330 | <span class="noprint"> | ||
331 | · | ||
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 deleted file mode 100644 index b28a72c..0000000 --- a/libraries/luajit-2.0/doc/faq.html +++ /dev/null | |||
@@ -1,180 +0,0 @@ | |||
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"> | ||
12 | dd { 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">»</span></a> | ||
55 | </li><li> | ||
56 | <a href="http://luajit.org/download.html">Download <span class="ext">»</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">»</span> main Lua.org site</a> has complete | ||
65 | <a href="http://www.lua.org/docs.html"><span class="ext">»</span> documentation</a> of the language | ||
66 | and links to books and papers about Lua.</li> | ||
67 | <li>The community-managed <a href="http://lua-users.org/wiki/"><span class="ext">»</span> Lua Wiki</a> | ||
68 | has information about diverse topics.</li> | ||
69 | <li>The primary source of information for the latest developments surrounding | ||
70 | Lua is the <a href="http://www.lua.org/lua-l.html"><span class="ext">»</span> Lua mailing list</a>. | ||
71 | You can check out the <a href="http://lua-users.org/lists/lua-l/"><span class="ext">»</span> mailing | ||
72 | list archive</a> or | ||
73 | <a href="http://bazar2.conectiva.com.br/mailman/listinfo/lua"><span class="ext">»</span> subscribe</a> | ||
74 | to the list (you need to be subscribed before posting).<br> | ||
75 | This is also the place where announcements and discussions about LuaJIT | ||
76 | take 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> | ||
83 | I'm planning to write more documentation about the internals of LuaJIT. | ||
84 | In the meantime, please use the following Google Scholar searches | ||
85 | to find relevant papers:<br> | ||
86 | Search for: <a href="http://scholar.google.com/scholar?q=Trace+Compiler"><span class="ext">»</span> Trace Compiler</a><br> | ||
87 | Search for: <a href="http://scholar.google.com/scholar?q=JIT+Compiler"><span class="ext">»</span> JIT Compiler</a><br> | ||
88 | Search for: <a href="http://scholar.google.com/scholar?q=Dynamic+Language+Optimizations"><span class="ext">»</span> Dynamic Language Optimizations</a><br> | ||
89 | Search for: <a href="http://scholar.google.com/scholar?q=SSA+Form"><span class="ext">»</span> SSA Form</a><br> | ||
90 | Search for: <a href="http://scholar.google.com/scholar?q=Linear+Scan+Register+Allocation"><span class="ext">»</span> Linear Scan Register Allocation</a><br> | ||
91 | Here is a list of the <a href="http://article.gmane.org/gmane.comp.lang.lua.general/58908"><span class="ext">»</span> innovative features in LuaJIT</a>.<br> | ||
92 | And, 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> | ||
98 | Q: My vararg functions fail after switching to LuaJIT!</dt> | ||
99 | <dd>LuaJIT is compatible to the Lua 5.1 language standard. It doesn't | ||
100 | support the implicit <tt>arg</tt> parameter for old-style vararg | ||
101 | functions 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">»</span> Lua 5.1 | ||
103 | vararg 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 | |||
113 | DirectX/Direct3D (up to version 9) sets the x87 FPU to single-precision | ||
114 | mode by default. This violates the Windows ABI and interferes with the | ||
115 | operation of many programs — LuaJIT is affected, too. Please make | ||
116 | sure you always use the <tt>D3DCREATE_FPU_PRESERVE</tt> flag when | ||
117 | initializing Direct3D.<br> | ||
118 | |||
119 | Direct3D version 10 or higher do not show this behavior anymore. | ||
120 | Consider testing your application with older versions, too.<br> | ||
121 | |||
122 | Similarly, the Borland/Delphi runtime modifies the FPU control word and | ||
123 | enables FP exceptions. Of course this violates the Windows ABI, too. | ||
124 | Please 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 | ||
131 | currently ignored by compiled code (this will eventually be fixed). If | ||
132 | your program is running in a tight loop and never falls back to the | ||
133 | interpreter, the debug hook never runs and can't throw the | ||
134 | "interrupted!" error.<br> In the meantime you have to press Ctrl-C | ||
135 | twice to get stop your program. That's similar to when it's stuck | ||
136 | running 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 | ||
142 | in common with Lua anymore. Also, if the patch introduces changes to | ||
143 | the Lua semantics, these would need to be reflected everywhere in the | ||
144 | VM, from the interpreter up to all stages of the compiler.<br> Please | ||
145 | use only standard Lua language constructs. For many common needs you | ||
146 | can use source transformations or use wrapper or proxy functions. | ||
147 | The 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 — it needs to generate native | ||
153 | machine code. This means the code generator must be ported to each | ||
154 | architecture. And the fast interpreter is written in assembler and | ||
155 | must be ported, too. This is quite an undertaking.<br> | ||
156 | The <a href="install.html">install documentation</a> shows the supported | ||
157 | architectures. Other architectures will follow based on sufficient user | ||
158 | demand 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> | ||
164 | C'mon, it's open source — I'm doing it on my own time and you're | ||
165 | getting it for free. You can either contribute a patch or sponsor | ||
166 | the 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"> | ||
173 | Copyright © 2005-2011 Mike Pall | ||
174 | <span class="noprint"> | ||
175 | · | ||
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 deleted file mode 100644 index 9c73dc5..0000000 --- a/libraries/luajit-2.0/doc/img/contact.png +++ /dev/null | |||
Binary files differ | |||
diff --git a/libraries/luajit-2.0/doc/install.html b/libraries/luajit-2.0/doc/install.html deleted file mode 100644 index 07c55fa..0000000 --- a/libraries/luajit-2.0/doc/install.html +++ /dev/null | |||
@@ -1,543 +0,0 @@ | |||
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"> | ||
12 | table.compat { | ||
13 | line-height: 1.2; | ||
14 | width: 600px; | ||
15 | } | ||
16 | table.compat td { | ||
17 | border: 1px solid #bfcfff; | ||
18 | font-size: 90%; | ||
19 | height: 2.5em; | ||
20 | } | ||
21 | table.compat tr.compathead td { | ||
22 | font-weight: bold; | ||
23 | border-bottom: 2px solid #bfcfff; | ||
24 | } | ||
25 | tr.compathead td.compatos { | ||
26 | vertical-align: top; | ||
27 | } | ||
28 | table.compat td.compatcpu { | ||
29 | width: 16%; | ||
30 | border-right: 2px solid #bfcfff; | ||
31 | } | ||
32 | td.compatos { | ||
33 | width: 21%; | ||
34 | vertical-align: middle; | ||
35 | } | ||
36 | td.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">»</span></a> | ||
81 | </li><li> | ||
82 | <a href="http://luajit.org/download.html">Download <span class="ext">»</span></a> | ||
83 | </li></ul> | ||
84 | </div> | ||
85 | <div id="main"> | ||
86 | <p> | ||
87 | LuaJIT is only distributed as a source package. This page explains | ||
88 | how to build and install LuaJIT with different operating systems | ||
89 | and C compilers. | ||
90 | </p> | ||
91 | <p> | ||
92 | For the impatient (on POSIX systems): | ||
93 | </p> | ||
94 | <pre class="code"> | ||
95 | make && sudo make install | ||
96 | </pre> | ||
97 | <p> | ||
98 | LuaJIT currently builds out-of-the box on most systems. | ||
99 | Here's the compatibility matrix for the supported combinations of | ||
100 | operating 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"> </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"> </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"> </td> | ||
136 | <td class="compatos compatno"> </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"> </td> | ||
143 | <td class="compatos compatno"> </td> | ||
144 | </tr> | ||
145 | </table> | ||
146 | |||
147 | <h2>Configuring LuaJIT</h2> | ||
148 | <p> | ||
149 | The standard configuration should work fine for most installations. | ||
150 | Usually there is no need to tweak the settings. The following files | ||
151 | hold 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 | ||
156 | only).</li> | ||
157 | <li><tt>src/Makefile</tt> has settings for <b>compiling</b> LuaJIT | ||
158 | under POSIX, MinGW or Cygwin.</li> | ||
159 | <li><tt>src/msvcbuild.bat</tt> has settings for compiling LuaJIT with | ||
160 | MSVC or WinSDK.</li> | ||
161 | </ul> | ||
162 | <p> | ||
163 | Please read the instructions given in these files, before changing | ||
164 | any settings. | ||
165 | </p> | ||
166 | |||
167 | <h2 id="posix">POSIX Systems (Linux, OSX, *BSD etc.)</h2> | ||
168 | <h3>Prerequisites</h3> | ||
169 | <p> | ||
170 | Depending on your distribution, you may need to install a package for | ||
171 | GCC, the development headers and/or a complete SDK. E.g. on a current | ||
172 | Debian/Ubuntu, install <tt>libc6-dev</tt> with the package manager. | ||
173 | </p> | ||
174 | <p> | ||
175 | Download the current source package of LuaJIT (pick the .tar.gz), | ||
176 | if you haven't already done so. Move it to a directory of your choice, | ||
177 | open a terminal window and change to this directory. Now unpack the archive | ||
178 | and change to the newly created directory: | ||
179 | </p> | ||
180 | <pre class="code"> | ||
181 | tar zxf LuaJIT-2.0.0-beta9.tar.gz | ||
182 | cd LuaJIT-2.0.0-beta9</pre> | ||
183 | <h3>Building LuaJIT</h3> | ||
184 | <p> | ||
185 | The supplied Makefiles try to auto-detect the settings needed for your | ||
186 | operating system and your compiler. They need to be run with GNU Make, | ||
187 | which is probably the default on your system, anyway. Simply run: | ||
188 | </p> | ||
189 | <pre class="code"> | ||
190 | make | ||
191 | </pre> | ||
192 | <p> | ||
193 | This always builds a native x86, x64 or PPC binary, depending on the host OS | ||
194 | you're running this command on. Check the section on | ||
195 | <a href="#cross">cross-compilation</a> for more options. | ||
196 | </p> | ||
197 | <p> | ||
198 | By default, modules are only searched under the prefix <tt>/usr/local</tt>. | ||
199 | You 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"> | ||
203 | make PREFIX=/home/myself/lj2 | ||
204 | </pre> | ||
205 | <p> | ||
206 | Note for OSX: <tt>MACOSX_DEPLOYMENT_TARGET</tt> is set to <tt>10.4</tt> | ||
207 | in <tt>src/Makefile</tt>. Change it, if you want to build on an older version. | ||
208 | </p> | ||
209 | <h3>Installing LuaJIT</h3> | ||
210 | <p> | ||
211 | The 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 | ||
214 | to write to this path. So, assuming sudo is installed on your system, | ||
215 | run the following command and enter your sudo password: | ||
216 | </p> | ||
217 | <pre class="code"> | ||
218 | sudo make install | ||
219 | </pre> | ||
220 | <p> | ||
221 | Otherwise specify the directory prefix as an absolute path, e.g.: | ||
222 | </p> | ||
223 | <pre class="code"> | ||
224 | make install PREFIX=/home/myself/lj2 | ||
225 | </pre> | ||
226 | <p> | ||
227 | Obviously the prefixes given during build and installation need to be the same. | ||
228 | </p> | ||
229 | <p style="color: #c00000;"> | ||
230 | Note: to avoid overwriting a previous version, the beta test releases | ||
231 | only 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 | ||
233 | for convenience, with a command like this: | ||
234 | </p> | ||
235 | <pre class="code" style="color: #c00000;"> | ||
236 | sudo ln -sf luajit-2.0.0-beta9 /usr/local/bin/luajit | ||
237 | </pre> | ||
238 | |||
239 | <h2 id="windows">Windows Systems</h2> | ||
240 | <h3>Prerequisites</h3> | ||
241 | <p> | ||
242 | Either install one of the open source SDKs | ||
243 | (<a href="http://mingw.org/"><span class="ext">»</span> MinGW</a> or | ||
244 | <a href="http://www.cygwin.com/"><span class="ext">»</span> Cygwin</a>), which come with a modified | ||
245 | GCC plus the required development headers. | ||
246 | </p> | ||
247 | <p> | ||
248 | Or install Microsoft's Visual C++ (MSVC). The freely downloadable | ||
249 | <a href="http://www.microsoft.com/Express/VC/"><span class="ext">»</span> Express Edition</a> | ||
250 | works just fine, but only contains an x86 compiler. | ||
251 | </p> | ||
252 | <p> | ||
253 | The freely downloadable | ||
254 | <a href="http://msdn.microsoft.com/en-us/windowsserver/bb980924.aspx"><span class="ext">»</span> Windows SDK</a> | ||
255 | only comes with command line tools, but this is all you need to build LuaJIT. | ||
256 | It contains x86 and x64 compilers. | ||
257 | </p> | ||
258 | <p> | ||
259 | Next, 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> | ||
264 | Open a "Visual Studio .NET Command Prompt", <tt>cd</tt> to the | ||
265 | directory where you've unpacked the sources and run these commands: | ||
266 | </p> | ||
267 | <pre class="code"> | ||
268 | cd src | ||
269 | msvcbuild | ||
270 | </pre> | ||
271 | <p> | ||
272 | Then follow the installation instructions below. | ||
273 | </p> | ||
274 | <h3>Building with the Windows SDK</h3> | ||
275 | <p> | ||
276 | Open a "Windows SDK Command Shell" and select the x86 compiler: | ||
277 | </p> | ||
278 | <pre class="code"> | ||
279 | setenv /release /x86 | ||
280 | </pre> | ||
281 | <p> | ||
282 | Or select the x64 compiler: | ||
283 | </p> | ||
284 | <pre class="code"> | ||
285 | setenv /release /x64 | ||
286 | </pre> | ||
287 | <p> | ||
288 | Then <tt>cd</tt> to the directory where you've unpacked the sources | ||
289 | and run these commands: | ||
290 | </p> | ||
291 | <pre class="code"> | ||
292 | cd src | ||
293 | msvcbuild | ||
294 | </pre> | ||
295 | <p> | ||
296 | Then follow the installation instructions below. | ||
297 | </p> | ||
298 | <h3>Building with MinGW or Cygwin</h3> | ||
299 | <p> | ||
300 | Open a command prompt window and make sure the MinGW or Cygwin programs | ||
301 | are in your path. Then <tt>cd</tt> to the directory where | ||
302 | you've unpacked the sources and run this command for MinGW: | ||
303 | </p> | ||
304 | <pre class="code"> | ||
305 | mingw32-make | ||
306 | </pre> | ||
307 | <p> | ||
308 | Or this command for Cygwin: | ||
309 | </p> | ||
310 | <pre class="code"> | ||
311 | make | ||
312 | </pre> | ||
313 | <p> | ||
314 | Then follow the installation instructions below. | ||
315 | </p> | ||
316 | <h3>Installing LuaJIT</h3> | ||
317 | <p> | ||
318 | Copy <tt>luajit.exe</tt> and <tt>lua51.dll</tt> (built in the <tt>src</tt> | ||
319 | directory) to a newly created directory (any location is ok). | ||
320 | Add <tt>lua</tt> and <tt>lua\jit</tt> directories below it and copy | ||
321 | all Lua files from the <tt>lib</tt> directory of the distribution | ||
322 | to the latter directory. | ||
323 | </p> | ||
324 | <p> | ||
325 | There are no hardcoded | ||
326 | absolute path names — all modules are loaded relative to the | ||
327 | directory 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> | ||
333 | The build system has limited support for cross-compilation. For details | ||
334 | check the comments in <tt>src/Makefile</tt>. Here are some popular examples: | ||
335 | </p> | ||
336 | <p> | ||
337 | You can cross-compile to a <b>32 bit binary on a multilib x64 OS</b> by | ||
338 | installing the multilib development packages (e.g. <tt>libc6-dev-i386</tt> | ||
339 | on Debian/Ubuntu) and running: | ||
340 | </p> | ||
341 | <pre class="code"> | ||
342 | make CC="gcc -m32" | ||
343 | </pre> | ||
344 | <p> | ||
345 | You can cross-compile for a <b>Windows target on Debian/Ubuntu</b> by | ||
346 | installing the <tt>mingw32</tt> package and running: | ||
347 | </p> | ||
348 | <pre class="code"> | ||
349 | make HOST_CC="gcc -m32" CROSS=i586-mingw32msvc- TARGET_SYS=Windows | ||
350 | </pre> | ||
351 | <p> | ||
352 | You can cross-compile for an <b>ARM target</b> on an x86 or x64 host | ||
353 | system using a standard GNU cross-compile toolchain (Binutils, GCC, | ||
354 | EGLIBC). The <tt>CROSS</tt> prefix may vary depending on the | ||
355 | <tt>--target</tt> of the toolchain: | ||
356 | </p> | ||
357 | <pre class="code"> | ||
358 | make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabi- | ||
359 | </pre> | ||
360 | <p> | ||
361 | You 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">»</span> Android NDK</a>. | ||
362 | The environment variables need to match the install locations and the | ||
363 | desired target platform. E.g. Android 2.2 corresponds to ABI level 8: | ||
364 | </p> | ||
365 | <pre class="code"> | ||
366 | NDK=/opt/android/ndk | ||
367 | NDKABI=8 | ||
368 | NDKVER=$NDK/toolchains/arm-linux-androideabi-4.4.3 | ||
369 | NDKP=$NDKVER/prebuilt/linux-x86/bin/arm-linux-androideabi- | ||
370 | NDKF="--sysroot $NDK/platforms/android-$NDKABI/arch-arm" | ||
371 | make HOST_CC="gcc -m32" CROSS=$NDKP TARGET_FLAGS="$NDKF" | ||
372 | </pre> | ||
373 | <p> | ||
374 | You 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">»</span> iOS SDK</a>. | ||
375 | The environment variables need to match the iOS SDK version: | ||
376 | </p> | ||
377 | <p style="font-size: 8pt;"> | ||
378 | Note: <b>the JIT compiler is disabled for iOS</b>, because regular iOS Apps | ||
379 | are not allowed to generate code at runtime. You'll only get the performance | ||
380 | of the LuaJIT interpreter on iOS. This is still faster than plain Lua, but | ||
381 | much slower than the JIT compiler. Please complain to Apple, not me. | ||
382 | Or use Android. :-p | ||
383 | </p> | ||
384 | <pre class="code"> | ||
385 | ISDK=/Developer/Platforms/iPhoneOS.platform/Developer | ||
386 | ISDKVER=iPhoneOS4.3.sdk | ||
387 | ISDKP=$ISDK/usr/bin/ | ||
388 | ISDKF="-arch armv6 -isysroot $ISDK/SDKs/$ISDKVER" | ||
389 | make HOST_CC="gcc -m32 -arch i386" CROSS=$ISDKP TARGET_FLAGS="$ISDKF" \ | ||
390 | TARGET_SYS=iOS | ||
391 | </pre> | ||
392 | <p> | ||
393 | You 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 | ||
395 | GNU cross-compile toolchain (Binutils, GCC, EGLIBC). | ||
396 | The <tt>CROSS</tt> prefix may vary depending on the <tt>--target</tt> | ||
397 | of the toolchain: | ||
398 | </p> | ||
399 | <pre class="code"> | ||
400 | # PPC | ||
401 | make HOST_CC="gcc -m32" CROSS=powerpc-linux-gnu- | ||
402 | </pre> | ||
403 | <pre class="code"> | ||
404 | # PPC/e500v2 | ||
405 | make HOST_CC="gcc -m32" CROSS=powerpc-e500v2-linux-gnuspe- | ||
406 | </pre> | ||
407 | <p> | ||
408 | Whenever 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 | ||
410 | you're compiling on a Windows or OSX host for embedded Linux or Android, | ||
411 | you need to add <tt>TARGET_SYS=Linux</tt> to the examples above. For a | ||
412 | minimal 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> | ||
418 | LuaJIT is API-compatible with Lua 5.1. If you've already embedded Lua | ||
419 | into your application, you probably don't need to do anything to switch | ||
420 | to LuaJIT, except link with a different library: | ||
421 | </p> | ||
422 | <ul> | ||
423 | <li>It's strongly suggested to build LuaJIT separately using the supplied | ||
424 | build system. Please do <em>not</em> attempt to integrate the individual | ||
425 | source files into your build tree. You'll most likely get the internal build | ||
426 | dependencies wrong or mess up the compiler flags. Treat LuaJIT like any | ||
427 | other external library and link your application with either the dynamic | ||
428 | or static library, depending on your needs.</li> | ||
429 | <li>If you want to load C modules compiled for plain Lua | ||
430 | with <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 | ||
433 | or link the static library into your application. In the latter case | ||
434 | you'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 | ||
438 | link to the <tt>lua51.dll</tt> created by the LuaJIT build (do not rename | ||
439 | the DLL). You may link LuaJIT statically on Windows only if you don't | ||
440 | intend to load Lua/C modules at runtime. | ||
441 | </li></ul> | ||
442 | </li> | ||
443 | <li> | ||
444 | If you're building a 64 bit application on OSX which links directly or | ||
445 | indirectly against LuaJIT, you need to link your main executable | ||
446 | with these flags: | ||
447 | <pre class="code"> | ||
448 | -pagezero_size 10000 -image_base 100000000 | ||
449 | </pre> | ||
450 | Also, it's recommended to <tt>rebase</tt> all (self-compiled) shared libraries | ||
451 | which are loaded at runtime on OSX/x64 (e.g. C extension modules for Lua). | ||
452 | See: <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">»</span> simple example</a> | ||
459 | for 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 | ||
462 | allocator 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 | ||
464 | of 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. | ||
467 | Make sure the <tt>jit</tt> library is loaded or the JIT compiler | ||
468 | will not be activated.</li> | ||
469 | <li>The <tt>bit.*</tt> module for bitwise operations | ||
470 | is already built-in. There's no need to statically link | ||
471 | <a href="http://bitop.luajit.org/"><span class="ext">»</span> Lua BitOp</a> to your application.</li> | ||
472 | </ul> | ||
473 | |||
474 | <h2 id="distro">Hints for Distribution Maintainers</h2> | ||
475 | <p> | ||
476 | The LuaJIT build system has extra provisions for the needs of most | ||
477 | POSIX-based distributions. If you're a package maintainer for | ||
478 | a distribution, <em>please</em> make use of these features and | ||
479 | avoid patching, subverting, autotoolizing or messing up the build system | ||
480 | in unspeakable ways. | ||
481 | </p> | ||
482 | <p> | ||
483 | There should be absolutely no need to patch <tt>luaconf.h</tt> or any | ||
484 | of the Makefiles. And please do not hand-pick files for your packages — | ||
485 | simply use whatever <tt>make install</tt> creates. There's a reason | ||
486 | for all of the files <em>and</em> directories it creates. | ||
487 | </p> | ||
488 | <p> | ||
489 | The build system uses GNU make and auto-detects most settings based on | ||
490 | the host you're building it on. This should work fine for native builds, | ||
491 | even 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 | ||
493 | for a regular distribution build: | ||
494 | </p> | ||
495 | <ul> | ||
496 | <li><tt>PREFIX</tt> overrides the installation path and should usually | ||
497 | be set to <tt>/usr</tt>. Setting this also changes the module paths and | ||
498 | the <tt>-rpath</tt> of the shared library.</li> | ||
499 | <li><tt>DESTDIR</tt> is an absolute path which allows you to install | ||
500 | to 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> | ||
502 | for additional variables to tweak. The following variables <em>may</em> be | ||
503 | overridden, but it's <em>not</em> recommended, except for special needs | ||
504 | like cross-builds: | ||
505 | <tt>BUILDMODE, CC, HOST_CC, STATIC_CC, DYNAMIC_CC, CFLAGS, HOST_CFLAGS, | ||
506 | TARGET_CFLAGS, LDFLAGS, HOST_LDFLAGS, TARGET_LDFLAGS, TARGET_SHLDFLAGS, | ||
507 | TARGET_FLAGS, LIBS, HOST_LIBS, TARGET_LIBS, CROSS, HOST_SYS, TARGET_SYS | ||
508 | </tt></li> | ||
509 | </ul> | ||
510 | <p> | ||
511 | The 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 | ||
513 | and allows GCC to generate faster and shorter code. Alas, this requires | ||
514 | lots of memory during the build. This may be a problem for some users, | ||
515 | that's why it's not enabled by default. But it shouldn't be a problem for | ||
516 | most build farms. It's recommended that binary distributions use this | ||
517 | target for their LuaJIT builds. | ||
518 | </p> | ||
519 | <p> | ||
520 | The tl;dr version of the above: | ||
521 | </p> | ||
522 | <pre class="code"> | ||
523 | make amalg PREFIX=/usr && \ | ||
524 | make install PREFIX=/usr DESTDIR=/tmp/buildroot | ||
525 | </pre> | ||
526 | <p> | ||
527 | Finally, if you encounter any difficulties, please | ||
528 | <a href="contact.html">contact me</a> first, instead of releasing a broken | ||
529 | package onto unsuspecting users. Because they'll usually gonna complain | ||
530 | to 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"> | ||
536 | Copyright © 2005-2011 Mike Pall | ||
537 | <span class="noprint"> | ||
538 | · | ||
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 deleted file mode 100644 index 9725f5c..0000000 --- a/libraries/luajit-2.0/doc/luajit.html +++ /dev/null | |||
@@ -1,142 +0,0 @@ | |||
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">»</span></a> | ||
53 | </li><li> | ||
54 | <a href="http://luajit.org/download.html">Download <span class="ext">»</span></a> | ||
55 | </li></ul> | ||
56 | </div> | ||
57 | <div id="main"> | ||
58 | <p> | ||
59 | LuaJIT is a <b>Just-In-Time Compiler</b> for the Lua<sup>*</sup> | ||
60 | programming language. | ||
61 | </p> | ||
62 | <p> | ||
63 | LuaJIT is Copyright © 2005-2011 Mike Pall. | ||
64 | LuaJIT is open source software, released under the | ||
65 | <a href="http://www.opensource.org/licenses/mit-license.php"><span class="ext">»</span> MIT license</a>. | ||
66 | </p> | ||
67 | <p class="indent" style="color: #606060;"> | ||
68 | * Lua is a powerful, dynamic and light-weight programming language | ||
69 | designed for extending applications. Lua is also frequently used as a | ||
70 | general-purpose, stand-alone language. More information about | ||
71 | Lua can be found at: <a href="http://www.lua.org/"><span class="ext">»</span> http://www.lua.org/</a> | ||
72 | </p> | ||
73 | <h2>Compatibility</h2> | ||
74 | <p> | ||
75 | LuaJIT implements the full set of language features defined by Lua 5.1. | ||
76 | The virtual machine (VM) is <b>API- and ABI-compatible</b> to the | ||
77 | standard Lua interpreter and can be deployed as a drop-in replacement. | ||
78 | </p> | ||
79 | <p> | ||
80 | LuaJIT offers more performance, at the expense of portability. It | ||
81 | currently runs on all popular operating systems based on | ||
82 | <b>x86</b> or <b>x64</b> CPUs (Linux, Windows, OSX etc.) or embedded | ||
83 | systems based on <b>ARM</b> (Android, iOS) or <b>PPC</b> CPUs. | ||
84 | Other platforms will be supported in the future, based on user demand | ||
85 | and sponsoring. | ||
86 | </p> | ||
87 | |||
88 | <h2>Overview</h2> | ||
89 | <p> | ||
90 | LuaJIT has been successfully used as a <b>scripting middleware</b> in | ||
91 | games, 3D modellers, numerical simulations, trading platforms and many | ||
92 | other specialty applications. It combines high flexibility with high | ||
93 | performance 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> | ||
97 | LuaJIT has been in continuous development since 2005. It's widely | ||
98 | considered to be <b>one of the fastest dynamic language | ||
99 | implementations</b>. It has outperformed other dynamic languages on many | ||
100 | cross-language benchmarks since its first release — often by a | ||
101 | substantial margin. In 2009 other dynamic language VMs started to catch up | ||
102 | with the performance of LuaJIT 1.x. Well, I couldn't let that slide. ;-) | ||
103 | </p> | ||
104 | <p> | ||
105 | 2009 also marks the first release of the long-awaited <b>LuaJIT 2.0</b>. | ||
106 | The whole VM has been rewritten from the ground up and relentlessly | ||
107 | optimized for performance. It combines a high-speed interpreter, | ||
108 | written in assembler, with a state-of-the-art JIT compiler. | ||
109 | </p> | ||
110 | <p> | ||
111 | An innovative <b>trace compiler</b> is integrated with advanced, | ||
112 | SSA-based optimizations and a highly tuned code generation backend. This | ||
113 | allows a substantial reduction of the overhead associated with dynamic | ||
114 | language features. | ||
115 | </p> | ||
116 | <p> | ||
117 | It's destined to break into the <a href="http://luajit.org/performance.html"><span class="ext">»</span> performance</a> | ||
118 | range traditionally reserved for offline, static language compilers. | ||
119 | </p> | ||
120 | |||
121 | <h2>More ...</h2> | ||
122 | <p> | ||
123 | Click on the LuaJIT sub-topics in the navigation bar to learn more | ||
124 | about LuaJIT. | ||
125 | </p> | ||
126 | <p><p> | ||
127 | Click on the Logo in the upper left corner to visit | ||
128 | the LuaJIT project page on the web. All other links to online | ||
129 | resources are marked with a '<span class="ext">»</span>'. | ||
130 | </p> | ||
131 | <br class="flush"> | ||
132 | </div> | ||
133 | <div id="foot"> | ||
134 | <hr class="hide"> | ||
135 | Copyright © 2005-2011 Mike Pall | ||
136 | <span class="noprint"> | ||
137 | · | ||
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 deleted file mode 100644 index e2afdee..0000000 --- a/libraries/luajit-2.0/doc/running.html +++ /dev/null | |||
@@ -1,313 +0,0 @@ | |||
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"> | ||
12 | table.opt { | ||
13 | line-height: 1.2; | ||
14 | } | ||
15 | tr.opthead td { | ||
16 | font-weight: bold; | ||
17 | } | ||
18 | td.flag_name { | ||
19 | width: 4em; | ||
20 | } | ||
21 | td.flag_level { | ||
22 | width: 2em; | ||
23 | text-align: center; | ||
24 | } | ||
25 | td.param_name { | ||
26 | width: 6em; | ||
27 | } | ||
28 | td.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">»</span></a> | ||
74 | </li><li> | ||
75 | <a href="http://luajit.org/download.html">Download <span class="ext">»</span></a> | ||
76 | </li></ul> | ||
77 | </div> | ||
78 | <div id="main"> | ||
79 | <p> | ||
80 | LuaJIT has only a single stand-alone executable, called <tt>luajit</tt> on | ||
81 | POSIX systems or <tt>luajit.exe</tt> on Windows. It can be used to run simple | ||
82 | Lua statements or whole Lua applications from the command line. It has an | ||
83 | interactive mode, too. | ||
84 | </p> | ||
85 | <p class="indent" style="color: #c00000;"> | ||
86 | Note: the beta test releases only install under the versioned name on | ||
87 | POSIX systems (to avoid overwriting a previous version). You either need | ||
88 | to type <tt>luajit-2.0.0-beta9</tt> to start it or create a symlink | ||
89 | with a command like this: | ||
90 | </p> | ||
91 | <pre class="code" style="color: #c00000;"> | ||
92 | sudo ln -sf luajit-2.0.0-beta9 /usr/local/bin/luajit | ||
93 | </pre> | ||
94 | <p> | ||
95 | Unlike previous versions <b>optimization is turned on by default</b> in | ||
96 | LuaJIT 2.0!<br>It's no longer necessary to use <tt>luajit -O</tt>. | ||
97 | </p> | ||
98 | |||
99 | <h2 id="options">Command Line Options</h2> | ||
100 | <p> | ||
101 | The <tt>luajit</tt> stand-alone executable is just a slightly modified | ||
102 | version of the regular <tt>lua</tt> stand-alone executable. | ||
103 | It supports the same basic options, too. <tt>luajit -h</tt> | ||
104 | prints 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">»</span> Lua manual</a> | ||
106 | for details. | ||
107 | </p> | ||
108 | <p> | ||
109 | LuaJIT has some additional options: | ||
110 | </p> | ||
111 | |||
112 | <h3 id="opt_b"><tt>-b[options] input output</tt></h3> | ||
113 | <p> | ||
114 | This option saves or lists bytecode. The following additional options | ||
115 | are accepted: | ||
116 | </p> | ||
117 | <ul> | ||
118 | <li><tt>-l</tt> — Only list bytecode.</li> | ||
119 | <li><tt>-s</tt> — Strip debug info (this is the default).</li> | ||
120 | <li><tt>-g</tt> — Keep debug info.</li> | ||
121 | <li><tt>-n name</tt> — Set module name (default: auto-detect from input name)</li> | ||
122 | <li><tt>-t type</tt> — Set output file type (default: auto-detect from output name).</li> | ||
123 | <li><tt>-a arch</tt> — Override architecture for object files (default: native).</li> | ||
124 | <li><tt>-o os</tt> — Override OS for object files (default: native).</li> | ||
125 | <li><tt>-e chunk</tt> — Use chunk string as input.</li> | ||
126 | <li><tt>-</tt> (a single minus sign) — Use stdin as input and/or stdout as output.</li> | ||
127 | </ul> | ||
128 | <p> | ||
129 | The output file type is auto-detected from the extension of the output | ||
130 | file name: | ||
131 | </p> | ||
132 | <ul> | ||
133 | <li><tt>c</tt> — C source file, exported bytecode data.</li> | ||
134 | <li><tt>h</tt> — C header file, static bytecode data.</li> | ||
135 | <li><tt>obj</tt> or <tt>o</tt> — Object file, exported bytecode data | ||
136 | (OS- and architecture-specific).</li> | ||
137 | <li><tt>raw</tt> or any other extension — Raw bytecode file (portable). | ||
138 | </ul> | ||
139 | <p> | ||
140 | Notes: | ||
141 | </p> | ||
142 | <ul> | ||
143 | <li>See also <a href="extensions.html#string_dump">string.dump()</a> | ||
144 | for information on bytecode portability and compatibility.</li> | ||
145 | <li>A file in raw bytecode format is auto-detected and can be loaded like | ||
146 | any 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, | ||
149 | generate 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 | ||
151 | global 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 | ||
153 | symbols (in <tt>*.exe</tt> or <tt>lua51.dll</tt> on Windows) and from | ||
154 | shared libraries in <tt>package.cpath</tt>.</li> | ||
155 | </ul> | ||
156 | <p> | ||
157 | Typical usage examples: | ||
158 | </p> | ||
159 | <pre class="code"> | ||
160 | luajit -b test.lua test.out # Save bytecode to test.out | ||
161 | luajit -bg test.lua test.out # Keep debug info | ||
162 | luajit -be "print('hello world')" test.out # Save cmdline script | ||
163 | |||
164 | luajit -bl test.lua # List to stdout | ||
165 | luajit -bl test.lua test.txt # List to test.txt | ||
166 | luajit -ble "print('hello world')" # List cmdline script | ||
167 | |||
168 | luajit -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> | ||
174 | This option performs a LuaJIT control command or activates one of the | ||
175 | loadable extension modules. The command is first looked up in the | ||
176 | <tt>jit.*</tt> library. If no matching function is found, a module | ||
177 | named <tt>jit.<cmd></tt> is loaded and the <tt>start()</tt> | ||
178 | function of the module is called with the specified arguments (if | ||
179 | any). The space between <tt>-j</tt> and <tt>cmd</tt> is optional. | ||
180 | </p> | ||
181 | <p> | ||
182 | Here are the available LuaJIT control commands: | ||
183 | </p> | ||
184 | <ul> | ||
185 | <li id="j_on"><tt>-jon</tt> — Turns the JIT compiler on (default).</li> | ||
186 | <li id="j_off"><tt>-joff</tt> — Turns the JIT compiler off (only use the interpreter).</li> | ||
187 | <li id="j_flush"><tt>-jflush</tt> — Flushes the whole cache of compiled code.</li> | ||
188 | <li id="j_v"><tt>-jv</tt> — Shows verbose information about the progress of the JIT compiler.</li> | ||
189 | <li id="j_dump"><tt>-jdump</tt> — Dumps the code and structures used in various compiler stages.</li> | ||
190 | </ul> | ||
191 | <p> | ||
192 | The <tt>-jv</tt> and <tt>-jdump</tt> commands are extension modules | ||
193 | written in Lua. They are mainly used for debugging the JIT compiler | ||
194 | itself. For a description of their options and output format, please | ||
195 | read the comment block at the start of their source. | ||
196 | They can be found in the <tt>lib</tt> directory of the source | ||
197 | distribution or installed under the <tt>jit</tt> directory. By default | ||
198 | this is <tt>/usr/local/share/luajit-2.0.0-beta9/jit</tt> on POSIX | ||
199 | systems. | ||
200 | </p> | ||
201 | |||
202 | <h3 id="opt_O"><tt>-O[level]</tt><br> | ||
203 | <tt>-O[+]flag</tt> <tt>-O-flag</tt><br> | ||
204 | <tt>-Oparam=value</tt></h3> | ||
205 | <p> | ||
206 | This options allows fine-tuned control of the optimizations used by | ||
207 | the JIT compiler. This is mainly intended for debugging LuaJIT itself. | ||
208 | Please note that the JIT compiler is extremely fast (we are talking | ||
209 | about the microsecond to millisecond range). Disabling optimizations | ||
210 | doesn't have any visible impact on its overhead, but usually generates | ||
211 | code that runs slower. | ||
212 | </p> | ||
213 | <p> | ||
214 | The first form sets an optimization level — this enables a | ||
215 | specific mix of optimization flags. <tt>-O0</tt> turns off all | ||
216 | optimizations and higher numbers enable more optimizations. Omitting | ||
217 | the level (i.e. just <tt>-O</tt>) sets the default optimization level, | ||
218 | which is <tt>-O3</tt> in the current version. | ||
219 | </p> | ||
220 | <p> | ||
221 | The second form adds or removes individual optimization flags. | ||
222 | The third form sets a parameter for the VM or the JIT compiler | ||
223 | to a specific value. | ||
224 | </p> | ||
225 | <p> | ||
226 | You 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 | ||
229 | left to right and later settings override earlier ones. You can freely | ||
230 | mix the three forms, but note that setting an optimization level | ||
231 | overrides all earlier flags. | ||
232 | </p> | ||
233 | <p> | ||
234 | Here are the available flags and at what optimization levels they | ||
235 | are 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"> </td> | ||
244 | </tr> | ||
245 | <tr class="odd separate"> | ||
246 | <td class="flag_name">fold</td><td class="flag_level">•</td><td class="flag_level">•</td><td class="flag_level">•</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">•</td><td class="flag_level">•</td><td class="flag_level">•</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">•</td><td class="flag_level">•</td><td class="flag_level">•</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"> </td><td class="flag_level">•</td><td class="flag_level">•</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"> </td><td class="flag_level">•</td><td class="flag_level">•</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"> </td><td class="flag_level"> </td><td class="flag_level">•</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"> </td><td class="flag_level"> </td><td class="flag_level">•</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"> </td><td class="flag_level"> </td><td class="flag_level">•</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"> </td><td class="flag_level"> </td><td class="flag_level">•</td><td class="flag_desc">Fusion of operands into instructions</td></tr> | ||
263 | </table> | ||
264 | <p> | ||
265 | Here 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"> </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"> | ||
306 | Copyright © 2005-2011 Mike Pall | ||
307 | <span class="noprint"> | ||
308 | · | ||
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 deleted file mode 100644 index d9cffe0..0000000 --- a/libraries/luajit-2.0/doc/status.html +++ /dev/null | |||
@@ -1,240 +0,0 @@ | |||
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 & 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"> | ||
12 | ul 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 & 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">»</span></a> | ||
55 | </li><li> | ||
56 | <a href="http://luajit.org/download.html">Download <span class="ext">»</span></a> | ||
57 | </li></ul> | ||
58 | </div> | ||
59 | <div id="main"> | ||
60 | <p> | ||
61 | The <span style="color: #0000c0;">LuaJIT 1.x</span> series represents | ||
62 | the current <span style="color: #0000c0;">stable branch</span>. | ||
63 | Only a single bug has been discovered in the last two years. So, if | ||
64 | you need a rock-solid VM, you are encouraged to fetch the latest | ||
65 | release of LuaJIT 1.x from the <a href="http://luajit.org/download.html"><span class="ext">»</span> Download</a> | ||
66 | page. | ||
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>. | ||
71 | It has <b>Beta Test</b> status and is still undergoing | ||
72 | substantial changes. | ||
73 | It has <a href="http://luajit.org/performance.html"><span class="ext">»</span> much better performance</a> than LuaJIT 1.x. | ||
74 | It's maturing quickly, so you should definitely | ||
75 | start to evaluate it for new projects right now. | ||
76 | </p> | ||
77 | |||
78 | <h2>Current Status</h2> | ||
79 | <p> | ||
80 | This is a list of the things you should know about the LuaJIT 2.0 beta test: | ||
81 | </p> | ||
82 | <ul> | ||
83 | <li> | ||
84 | Obviously there will be some <b>bugs</b> in a VM which has been | ||
85 | rewritten from the ground up. Please report your findings together with | ||
86 | the circumstances needed to reproduce the bug. If possible, reduce the | ||
87 | problem down to a simple test case.<br> | ||
88 | There is no formal bug tracker at the moment. The best place for | ||
89 | discussion is the | ||
90 | <a href="http://www.lua.org/lua-l.html"><span class="ext">»</span> Lua mailing list</a>. Of course | ||
91 | you may also send your bug reports <a href="contact.html">directly to me</a>, | ||
92 | especially when they contain lengthy debug output or if you require | ||
93 | confidentiality. | ||
94 | </li> | ||
95 | <li> | ||
96 | The 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, | ||
98 | Atom or K8/K10 to get the full benefit.<br> | ||
99 | If you run LuaJIT on older CPUs without SSE2 support, the JIT compiler | ||
100 | is disabled and the VM falls back to the LuaJIT interpreter. This is faster | ||
101 | than the Lua interpreter, but not nearly as fast as the JIT compiler of course. | ||
102 | Run 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> | ||
106 | The VM is complete in the sense that it <b>should</b> run all Lua code | ||
107 | just fine. It's considered a serious bug if the VM crashes or produces | ||
108 | unexpected results — please report this. There are only very few | ||
109 | known incompatibilities with standard Lua: | ||
110 | <ul> | ||
111 | <li> | ||
112 | The Lua <b>debug API</b> is missing a couple of features (return | ||
113 | hooks for non-Lua functions) and shows slightly different behavior | ||
114 | (no per-coroutine hooks, no tail call counting). | ||
115 | </li> | ||
116 | <li> | ||
117 | Some of the <b>configuration options</b> of Lua 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> | ||
121 | to enable line editing. It's planned to add support for loading it | ||
122 | on-demand.</li> | ||
123 | </ul> | ||
124 | </li> | ||
125 | <li> | ||
126 | Most other issues you're likely to find (e.g. with the existing test | ||
127 | suites) are differences in the <b>implementation-defined</b> behavior. | ||
128 | These either have a good reason (like early tail call resolving which | ||
129 | may cause differences in error reporting), are arbitrary design choices | ||
130 | or are due to quirks in the VM. The latter cases may get fixed if a | ||
131 | demonstrable need is shown. | ||
132 | </li> | ||
133 | </ul> | ||
134 | </li> | ||
135 | <li> | ||
136 | The <b>JIT compiler</b> falls back to the | ||
137 | interpreter in some cases. All of this works transparently, so unless | ||
138 | you use <tt>-jv</tt>, you'll probably never notice (the interpreter is | ||
139 | <a href="http://luajit.org/performance.html"><span class="ext">»</span> quite fast</a>, too). Here are the known issues: | ||
140 | <ul> | ||
141 | <li> | ||
142 | Most known issues cause a <b>NYI</b> (not yet implemented) trace abort | ||
143 | message. E.g. for calls to some internal library | ||
144 | functions. Reporting these is only mildly useful, except if you have good | ||
145 | example code that shows the problem. Obviously, reports accompanied with | ||
146 | a patch to fix the issue are more than welcome. But please check back | ||
147 | with me, before writing major improvements, to avoid duplication of | ||
148 | effort. | ||
149 | </li> | ||
150 | <li> | ||
151 | Some checks are missing in the JIT-compiled code for obscure situations | ||
152 | with <b>open upvalues aliasing</b> one of the SSA slots later on (or | ||
153 | vice versa). Bonus points, if you can find a real world test case for | ||
154 | this. | ||
155 | </li> | ||
156 | <li> | ||
157 | Currently some <b>out-of-memory</b> errors from <b>on-trace code</b> are not | ||
158 | handled 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> | ||
168 | Please refer to the | ||
169 | <a href="http://lua-users.org/lists/lua-l/2011-01/msg01238.html"><span class="ext">»</span> LuaJIT | ||
170 | Roadmap 2011</a> for the latest release plan. Here's the general | ||
171 | project plan for LuaJIT 2.0: | ||
172 | </p> | ||
173 | <ul> | ||
174 | <li> | ||
175 | The main goal right now is to stabilize LuaJIT 2.0 and get it out of | ||
176 | beta test. <b>Correctness</b> has priority over completeness. This | ||
177 | implies the first stable release will certainly NOT compile every | ||
178 | library function call and will fall back to the interpreter from time | ||
179 | to time. This is perfectly ok, since it still executes all Lua code, | ||
180 | just not at the highest possible speed. | ||
181 | </li> | ||
182 | <li> | ||
183 | The next step is to get it to compile more library functions and handle | ||
184 | more cases where the compiler currently bails out. This doesn't mean it | ||
185 | will compile every corner case. It's much more important that it | ||
186 | performs well in a majority of use cases. Every compiler has to make | ||
187 | these trade-offs — <b>completeness</b> just cannot be the | ||
188 | overriding goal for a low-footprint, low-overhead JIT compiler. | ||
189 | </li> | ||
190 | <li> | ||
191 | More <b>optimizations</b> will be added in parallel to the last step on | ||
192 | an as-needed basis. Sinking of stores | ||
193 | to aggregates and sinking of allocations are high on the list. | ||
194 | More complex optimizations with less pay-off, such as value-range-propagation | ||
195 | (VRP) will have to wait. | ||
196 | </li> | ||
197 | <li> | ||
198 | LuaJIT 2.0 has been designed with <b>portability</b> in mind. | ||
199 | Nonetheless, it compiles to native code and needs to be adapted to each | ||
200 | architecture. The two major work items are porting the the fast interpreter, | ||
201 | which is written in assembler, and porting the compiler backend. | ||
202 | Most other portability issues like endianess or 32 vs. 64 bit CPUs | ||
203 | have already been taken care of.<br> | ||
204 | Several ports are already available, thanks to the | ||
205 | <a href="http://luajit.org/sponsors.html"><span class="ext">»</span> LuaJIT sponsorship program</a>. | ||
206 | More ports will follow in the future — companies which are | ||
207 | interested in sponsoring a port to a particular architecture, please | ||
208 | use the given contact address. | ||
209 | </li> | ||
210 | <li> | ||
211 | <b>Documentation</b> about the <b>internals</b> of LuaJIT is still sorely | ||
212 | missing. Although the source code is included and is IMHO well | ||
213 | commented, many basic design decisions are in need of an explanation. | ||
214 | The rather un-traditional compiler architecture and the many highly | ||
215 | optimized data structures are a barrier for outside participation in | ||
216 | the development. Alas, as I've repeatedly stated, I'm better at | ||
217 | writing code than papers and I'm not in need of any academic merits. | ||
218 | Someday I will find the time for it. :-) | ||
219 | </li> | ||
220 | <li> | ||
221 | Producing good code for unbiased branches is a key problem for trace | ||
222 | compilers. This is the main cause for "trace explosion". | ||
223 | <b>Hyperblock scheduling</b> promises to solve this nicely at the | ||
224 | price of a major redesign of the compiler. This would also pave the | ||
225 | way for emitting predicated instructions, which is a prerequisite | ||
226 | for efficient <b>vectorization</b>. | ||
227 | </li> | ||
228 | </ul> | ||
229 | <br class="flush"> | ||
230 | </div> | ||
231 | <div id="foot"> | ||
232 | <hr class="hide"> | ||
233 | Copyright © 2005-2011 Mike Pall | ||
234 | <span class="noprint"> | ||
235 | · | ||
236 | <a href="contact.html">Contact</a> | ||
237 | </span> | ||
238 | </div> | ||
239 | </body> | ||
240 | </html> | ||