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