aboutsummaryrefslogtreecommitdiffstatshomepage
path: root/libraries/luajit-2.0/doc/extensions.html
diff options
context:
space:
mode:
Diffstat (limited to 'libraries/luajit-2.0/doc/extensions.html')
-rw-r--r--libraries/luajit-2.0/doc/extensions.html336
1 files changed, 0 insertions, 336 deletions
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">
12table.exc {
13 line-height: 1.2;
14}
15tr.exchead td {
16 font-weight: bold;
17}
18td.excplatform {
19 width: 48%;
20}
21td.exccompiler {
22 width: 29%;
23}
24td.excinterop {
25 width: 23%;
26}
27</style>
28</head>
29<body>
30<div id="site">
31<a href="http://luajit.org"><span>Lua<span id="logo">JIT</span></span></a>
32</div>
33<div id="head">
34<h1>Extensions</h1>
35</div>
36<div id="nav">
37<ul><li>
38<a href="luajit.html">LuaJIT</a>
39<ul><li>
40<a href="install.html">Installation</a>
41</li><li>
42<a href="running.html">Running</a>
43</li></ul>
44</li><li>
45<a class="current" href="extensions.html">Extensions</a>
46<ul><li>
47<a href="ext_ffi.html">FFI Library</a>
48<ul><li>
49<a href="ext_ffi_tutorial.html">FFI Tutorial</a>
50</li><li>
51<a href="ext_ffi_api.html">ffi.* API</a>
52</li><li>
53<a href="ext_ffi_semantics.html">FFI Semantics</a>
54</li></ul>
55</li><li>
56<a href="ext_jit.html">jit.* Library</a>
57</li><li>
58<a href="ext_c_api.html">Lua/C API</a>
59</li></ul>
60</li><li>
61<a href="status.html">Status</a>
62<ul><li>
63<a href="changes.html">Changes</a>
64</li></ul>
65</li><li>
66<a href="faq.html">FAQ</a>
67</li><li>
68<a href="http://luajit.org/performance.html">Performance <span class="ext">&raquo;</span></a>
69</li><li>
70<a href="http://luajit.org/download.html">Download <span class="ext">&raquo;</span></a>
71</li></ul>
72</div>
73<div id="main">
74<p>
75LuaJIT is fully upwards-compatible with Lua 5.1. It supports all
76<a href="http://www.lua.org/manual/5.1/manual.html#5"><span class="ext">&raquo;</span>&nbsp;standard Lua
77library functions</a> and the full set of
78<a href="http://www.lua.org/manual/5.1/manual.html#3"><span class="ext">&raquo;</span>&nbsp;Lua/C API
79functions</a>.
80</p>
81<p>
82LuaJIT is also fully ABI-compatible to Lua 5.1 at the linker/dynamic
83loader level. This means you can compile a C&nbsp;module against the
84standard Lua headers and load the same shared library from either Lua
85or LuaJIT.
86</p>
87<p>
88LuaJIT extends the standard Lua VM with new functionality and adds
89several extension modules. Please note that this page is only about
90<em>functional</em> enhancements and not about performance enhancements,
91such as the optimized VM, the faster interpreter or the JIT compiler.
92</p>
93
94<h2 id="modules">Extensions Modules</h2>
95<p>
96LuaJIT comes with several built-in extension modules:
97</p>
98
99<h3 id="bit"><tt>bit.*</tt> &mdash; Bitwise operations</h3>
100<p>
101LuaJIT supports all bitwise operations as defined by
102<a href="http://bitop.luajit.org"><span class="ext">&raquo;</span>&nbsp;Lua BitOp</a>:
103</p>
104<pre class="code">
105bit.tobit bit.tohex bit.bnot bit.band bit.bor bit.bxor
106bit.lshift bit.rshift bit.arshift bit.rol bit.ror bit.bswap
107</pre>
108<p>
109This module is a LuaJIT built-in &mdash; you don't need to download or
110install Lua BitOp. The Lua BitOp site has full documentation for all
111<a href="http://bitop.luajit.org/api.html"><span class="ext">&raquo;</span>&nbsp;Lua BitOp API functions</a>.
112</p>
113<p>
114Please make sure to <tt>require</tt> the module before using any of
115its functions:
116</p>
117<pre class="code">
118local bit = require("bit")
119</pre>
120<p>
121An already installed Lua BitOp module is ignored by LuaJIT.
122This way you can use bit operations from both Lua and LuaJIT on a
123shared installation.
124</p>
125
126<h3 id="ffi"><tt>ffi.*</tt> &mdash; FFI library</h3>
127<p>
128The <a href="ext_ffi.html">FFI library</a> allows calling external
129C&nbsp;functions and the use of C&nbsp;data structures from pure Lua
130code.
131</p>
132
133<h3 id="jit"><tt>jit.*</tt> &mdash; JIT compiler control</h3>
134<p>
135The functions in this module
136<a href="ext_jit.html">control the behavior of the JIT compiler engine</a>.
137</p>
138
139<h3 id="c_api">C API extensions</h3>
140<p>
141LuaJIT adds some
142<a href="ext_c_api.html">extra functions to the Lua/C API</a>.
143</p>
144
145<h2 id="library">Enhanced Standard Library Functions</h2>
146
147<h3 id="xpcall"><tt>xpcall(f, err [,args...])</tt> passes arguments</h3>
148<p>
149Unlike the standard implementation in Lua 5.1, <tt>xpcall()</tt>
150passes any arguments after the error function to the function
151which is called in a protected context.
152</p>
153
154<h3 id="load"><tt>loadfile()</tt> etc. handle UTF-8 source code</h3>
155<p>
156Non-ASCII characters are handled transparently by the Lua source code parser.
157This allows the use of UTF-8 characters in identifiers and strings.
158A UTF-8 BOM is skipped at the start of the source code.
159</p>
160
161<h3 id="tostring"><tt>tostring()</tt> etc. canonicalize NaN and &plusmn;Inf</h3>
162<p>
163All number-to-string conversions consistently convert non-finite numbers
164to the same strings on all platforms. NaN results in <tt>"nan"</tt>,
165positive infinity results in <tt>"inf"</tt> and negative infinity results
166in <tt>"-inf"</tt>.
167</p>
168
169<h3 id="string_dump"><tt>string.dump(f [,strip])</tt> generates portable bytecode</h3>
170<p>
171An extra argument has been added to <tt>string.dump()</tt>. If set to
172<tt>true</tt>, 'stripped' bytecode without debug information is
173generated. This speeds up later bytecode loading and reduces memory
174usage. See also the
175<a href="running.html#opt_b"><tt>-b</tt> command line option</a>.
176</p>
177<p>
178The generated bytecode is portable and can be loaded on any architecture
179that LuaJIT supports, independent of word size or endianess. However the
180bytecode compatibility versions must match. Bytecode stays compatible
181for dot releases (x.y.0 &rarr; x.y.1), but may change with major or
182minor releases (2.0 &rarr; 2.1) or between any beta release. Foreign
183bytecode (e.g. from Lua 5.1) is incompatible and cannot be loaded.
184</p>
185
186<h3 id="math_random">Enhanced PRNG for <tt>math.random()</tt></h3>
187<p>
188LuaJIT uses a Tausworthe PRNG with period 2^223 to implement
189<tt>math.random()</tt> and <tt>math.randomseed()</tt>. The quality of
190the PRNG results is much superior compared to the standard Lua
191implementation which uses the platform-specific ANSI rand().
192</p>
193<p>
194The PRNG generates the same sequences from the same seeds on all
195platforms and makes use of all bits in the seed argument.
196<tt>math.random()</tt> without arguments generates 52 pseudo-random bits
197for every call. The result is uniformly distributed between 0 and 1.
198It's correctly scaled up and rounded for <tt>math.random(n&nbsp;[,m])</tt> to
199preserve uniformity.
200</p>
201
202<h3 id="io"><tt>io.*</tt> functions handle 64&nbsp;bit file offsets</h3>
203<p>
204The file I/O functions in the standard <tt>io.*</tt> library handle
20564&nbsp;bit file offsets. In particular this means it's possible
206to open files larger than 2&nbsp;Gigabytes and to reposition or obtain
207the current file position for offsets beyond 2&nbsp;GB
208(<tt>fp:seek()</tt> method).
209</p>
210
211<h3 id="debug_meta"><tt>debug.*</tt> functions identify metamethods</h3>
212<p>
213<tt>debug.getinfo()</tt> and <tt>lua_getinfo()</tt> also return information
214about invoked metamethods. The <tt>namewhat</tt> field is set to
215<tt>"metamethod"</tt> and the <tt>name</tt> field has the name of
216the corresponding metamethod (e.g. <tt>"__index"</tt>).
217</p>
218
219<h2 id="resumable">Fully Resumable VM</h2>
220<p>
221The LuaJIT 2.x VM is fully resumable. This means you can yield from a
222coroutine even across contexts, where this would not possible with
223the standard Lua&nbsp;5.1 VM: e.g. you can yield across <tt>pcall()</tt>
224and <tt>xpcall()</tt>, across iterators and across metamethods.
225</p>
226<p>
227Note however that LuaJIT 2.x doesn't use
228<a href="http://coco.luajit.org/"><span class="ext">&raquo;</span>&nbsp;Coco</a> anymore. This means the
229overhead for creating coroutines is much smaller and no extra
230C&nbsp;stacks need to be allocated. OTOH you can no longer yield
231across arbitrary C&nbsp;functions. Keep this in mind when
232upgrading from LuaJIT 1.x.
233</p>
234
235<h2 id="exceptions">C++ Exception Interoperability</h2>
236<p>
237LuaJIT has built-in support for interoperating with C++&nbsp;exceptions.
238The available range of features depends on the target platform and
239the toolchain used to compile LuaJIT:
240</p>
241<table class="exc">
242<tr class="exchead">
243<td class="excplatform">Platform</td>
244<td class="exccompiler">Compiler</td>
245<td class="excinterop">Interoperability</td>
246</tr>
247<tr class="odd separate">
248<td class="excplatform">POSIX/x64, DWARF2 unwinding</td>
249<td class="exccompiler">GCC 4.3+</td>
250<td class="excinterop"><b style="color: #00a000;">Full</b></td>
251</tr>
252<tr class="even">
253<td class="excplatform">Other platforms, DWARF2 unwinding</td>
254<td class="exccompiler">GCC</td>
255<td class="excinterop"><b style="color: #c06000;">Limited</b></td>
256</tr>
257<tr class="odd">
258<td class="excplatform">Windows/x64</td>
259<td class="exccompiler">MSVC or WinSDK</td>
260<td class="excinterop"><b style="color: #00a000;">Full</b></td>
261</tr>
262<tr class="even">
263<td class="excplatform">Windows/x86</td>
264<td class="exccompiler">Any</td>
265<td class="excinterop"><b style="color: #a00000;">No</b></td>
266</tr>
267<tr class="odd">
268<td class="excplatform">Other platforms</td>
269<td class="exccompiler">Other compilers</td>
270<td class="excinterop"><b style="color: #a00000;">No</b></td>
271</tr>
272</table>
273<p>
274<b style="color: #00a000;">Full interoperability</b> means:
275</p>
276<ul>
277<li>C++&nbsp;exceptions can be caught on the Lua side with <tt>pcall()</tt>,
278<tt>lua_pcall()</tt> etc.</li>
279<li>C++&nbsp;exceptions will be converted to the generic Lua error
280<tt>"C++&nbsp;exception"</tt>, unless you use the
281<a href="ext_c_api.html#mode_wrapcfunc">C&nbsp;call wrapper</a> feature.</li>
282<li>It's safe to throw C++&nbsp;exceptions across non-protected Lua frames
283on the C&nbsp;stack. The contents of the C++&nbsp;exception object
284pass through unmodified.</li>
285<li>Lua errors can be caught on the C++ side with <tt>catch(...)</tt>.
286The corresponding Lua error message can be retrieved from the Lua stack.</li>
287<li>Throwing Lua errors across C++ frames is safe. C++ destructors
288will be called.</li>
289</ul>
290<p>
291<b style="color: #c06000;">Limited interoperability</b> means:
292</p>
293<ul>
294<li>C++&nbsp;exceptions can be caught on the Lua side with <tt>pcall()</tt>,
295<tt>lua_pcall()</tt> etc.</li>
296<li>C++&nbsp;exceptions will be converted to the generic Lua error
297<tt>"C++&nbsp;exception"</tt>, unless you use the
298<a href="ext_c_api.html#mode_wrapcfunc">C&nbsp;call wrapper</a> feature.</li>
299<li>C++&nbsp;exceptions will be caught by non-protected Lua frames and
300are rethrown as a generic Lua error. The C++&nbsp;exception object will
301be destroyed.</li>
302<li>Lua errors <b>cannot</b> be caught on the C++ side.</li>
303<li>Throwing Lua errors across C++ frames will <b>not</b> call
304C++ destructors.</li>
305</ul>
306
307<p>
308<b style="color: #a00000;">No interoperability</b> means:
309</p>
310<ul>
311<li>It's <b>not</b> safe to throw C++&nbsp;exceptions across Lua frames.</li>
312<li>C++&nbsp;exceptions <b>cannot</b> be caught on the Lua side.</li>
313<li>Lua errors <b>cannot</b> be caught on the C++ side.</li>
314<li>Throwing Lua errors across C++ frames will <b>not</b> call
315C++ destructors.</li>
316<li>Additionally, on Windows/x86 with SEH-based C++&nbsp;exceptions:
317it's <b>not</b> safe to throw a Lua error across any frames containing
318a C++ function with any try/catch construct or using variables with
319(implicit) destructors. This also applies to any functions which may be
320inlined in such a function. It doesn't matter whether <tt>lua_error()</tt>
321is called inside or outside of a try/catch or whether any object actually
322needs to be destroyed: the SEH chain is corrupted and this will eventually
323lead to the termination of the process.</li>
324</ul>
325<br class="flush">
326</div>
327<div id="foot">
328<hr class="hide">
329Copyright &copy; 2005-2011 Mike Pall
330<span class="noprint">
331&middot;
332<a href="contact.html">Contact</a>
333</span>
334</div>
335</body>
336</html>
generated by cgit v1.1 at 2024-07-12 02:21:45 +0000