diff options
author | David Walter Seikel | 2012-01-23 23:36:30 +1000 |
---|---|---|
committer | David Walter Seikel | 2012-01-23 23:36:30 +1000 |
commit | 6523585c66c04cea54df50013df8886b589847d8 (patch) | |
tree | 0b22aee7064166d88595eda260ca2d17c0773da5 /libraries/luajit-2.0/doc/extensions.html | |
parent | Update the EFL to what I'm actually using, coz I'm using some stuff not yet r... (diff) | |
download | SledjHamr-6523585c66c04cea54df50013df8886b589847d8.zip SledjHamr-6523585c66c04cea54df50013df8886b589847d8.tar.gz SledjHamr-6523585c66c04cea54df50013df8886b589847d8.tar.bz2 SledjHamr-6523585c66c04cea54df50013df8886b589847d8.tar.xz |
Add luaproc and LuaJIT libraries.
Two versions of LuaJIT, the stable release, and the dev version. Try the dev version first, until ih fails badly.
Diffstat (limited to '')
-rw-r--r-- | libraries/luajit-2.0/doc/extensions.html | 336 |
1 files changed, 336 insertions, 0 deletions
diff --git a/libraries/luajit-2.0/doc/extensions.html b/libraries/luajit-2.0/doc/extensions.html new file mode 100644 index 0000000..b0e1164 --- /dev/null +++ b/libraries/luajit-2.0/doc/extensions.html | |||
@@ -0,0 +1,336 @@ | |||
1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> | ||
2 | <html> | ||
3 | <head> | ||
4 | <title>Extensions</title> | ||
5 | <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> | ||
6 | <meta name="Author" content="Mike Pall"> | ||
7 | <meta name="Copyright" content="Copyright (C) 2005-2011, Mike Pall"> | ||
8 | <meta name="Language" content="en"> | ||
9 | <link rel="stylesheet" type="text/css" href="bluequad.css" media="screen"> | ||
10 | <link rel="stylesheet" type="text/css" href="bluequad-print.css" media="print"> | ||
11 | <style type="text/css"> | ||
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> | ||