aboutsummaryrefslogtreecommitdiff
path: root/doc
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
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')
-rw-r--r--doc/api.html337
-rw-r--r--doc/changes.html7
-rw-r--r--doc/contact.html7
-rw-r--r--doc/ext_c_api.html174
-rw-r--r--doc/ext_jit.html177
-rw-r--r--doc/extensions.html303
-rw-r--r--doc/faq.html7
-rw-r--r--doc/install.html21
-rw-r--r--doc/luajit.html7
-rw-r--r--doc/running.html7
-rw-r--r--doc/status.html7
11 files changed, 703 insertions, 351 deletions
diff --git a/doc/api.html b/doc/api.html
deleted file mode 100644
index eee76afb..00000000
--- a/doc/api.html
+++ /dev/null
@@ -1,337 +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>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-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</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>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><li>
27<a class="current" href="api.html">API Extensions</a>
28</li></ul>
29</li><li>
30<a href="status.html">Status</a>
31<ul><li>
32<a href="changes.html">Changes</a>
33</li></ul>
34</li><li>
35<a href="faq.html">FAQ</a>
36</li><li>
37<a href="http://luajit.org/performance.html">Performance <span class="ext">&raquo;</span></a>
38</li><li>
39<a href="http://luajit.org/download.html">Download <span class="ext">&raquo;</span></a>
40</li></ul>
41</div>
42<div id="main">
43<p>
44LuaJIT is fully upwards-compatible with Lua 5.1. It supports all
45<a href="http://www.lua.org/manual/5.1/manual.html#5"><span class="ext">&raquo;</span>&nbsp;standard Lua
46library functions</a> and the full set of
47<a href="http://www.lua.org/manual/5.1/manual.html#3"><span class="ext">&raquo;</span>&nbsp;Lua/C API
48functions</a>.
49</p>
50<p>
51LuaJIT is also fully ABI-compatible to Lua 5.1 at the linker/dynamic
52loader level. This means you can compile a C&nbsp;module against the
53standard Lua headers and load the same shared library from either Lua
54or LuaJIT.
55</p>
56
57<h2 id="bit"><tt>bit.*</tt> &mdash; Bitwise Operations</h2>
58<p>
59LuaJIT supports all bitwise operations as defined by
60<a href="http://bitop.luajit.org"><span class="ext">&raquo;</span>&nbsp;Lua BitOp</a>:
61</p>
62<pre class="code">
63bit.tobit bit.tohex bit.bnot bit.band bit.bor bit.bxor
64bit.lshift bit.rshift bit.arshift bit.rol bit.ror bit.bswap
65</pre>
66<p>
67This module is a LuaJIT built-in &mdash; you don't need to download or
68install Lua BitOp. The Lua BitOp site has full documentation for all
69<a href="http://bitop.luajit.org/api.html"><span class="ext">&raquo;</span>&nbsp;Lua BitOp API functions</a>.
70</p>
71<p>
72Please make sure to <tt>require</tt> the module before using any of
73its functions:
74</p>
75<pre class="code">
76local bit = require("bit")
77</pre>
78<p>
79An already installed Lua BitOp module is ignored by LuaJIT.
80This way you can use bit operations from both Lua and LuaJIT on a
81shared installation.
82</p>
83
84<h2 id="jit"><tt>jit.*</tt> &mdash; JIT compiler control</h2>
85<p>
86The functions in this built-in module control the behavior
87of the JIT compiler engine.
88</p>
89
90<h3 id="jit_onoff"><tt>jit.on()<br>
91jit.off()</tt></h3>
92<p>
93Turns the whole JIT compiler on (default) or off.
94</p>
95<p>
96These functions are typically used with the command line options
97<tt>-j on</tt> or <tt>-j off</tt>.
98</p>
99
100<h3 id="jit_flush"><tt>jit.flush()</tt></h3>
101<p>
102Flushes the whole cache of compiled code.
103</p>
104
105<h3 id="jit_onoff_func"><tt>jit.on(func|true [,true|false])<br>
106jit.off(func|true [,true|false])<br>
107jit.flush(func|true [,true|false])</tt></h3>
108<p>
109<tt>jit.on</tt> enables JIT compilation for a Lua function (this is
110the default).
111</p>
112<p>
113<tt>jit.off</tt> disables JIT compilation for a Lua function and
114flushes any already compiled code from the code cache.
115</p>
116<p>
117<tt>jit.flush</tt> flushes the code, but doesn't affect the
118enable/disable status.
119</p>
120<p>
121The current function, i.e. the Lua function calling this library
122function, can also be specified by passing <tt>true</tt> as the first
123argument.
124</p>
125<p>
126If the second argument is <tt>true</tt>, JIT compilation is also
127enabled, disabled or flushed recursively for all sub-functions of a
128function. With <tt>false</tt> only the sub-functions are affected.
129</p>
130<p>
131The <tt>jit.on</tt> and <tt>jit.off</tt> functions only set a flag
132which is checked when the function is about to be compiled. They do
133not trigger immediate compilation.
134</p>
135<p>
136Typical usage is <tt>jit.off(true, true)</tt> in the main chunk
137of a module to turn off JIT compilation for the whole module for
138debugging purposes.
139</p>
140
141<h3 id="jit_flush_tr"><tt>jit.flush(tr)</tt></h3>
142<p>
143Flushes the specified root trace and all of its side traces from the cache.
144The code for the trace will be retained as long as there are any other
145traces which link to it.
146</p>
147
148<h3 id="jit_status"><tt>status, ... = jit.status()</tt></h3>
149<p>
150Returns the current status of the JIT compiler. The first result is
151either <tt>true</tt> or <tt>false</tt> if the JIT compiler is turned
152on or off. The remaining results are strings for CPU-specific features
153and enabled optimizations.
154</p>
155
156<h3 id="jit_version"><tt>jit.version</tt></h3>
157<p>
158Contains the LuaJIT version string.
159</p>
160
161<h3 id="jit_version_num"><tt>jit.version_num</tt></h3>
162<p>
163Contains the version number of the LuaJIT core. Version xx.yy.zz
164is represented by the decimal number xxyyzz.
165</p>
166
167<h3 id="jit_arch"><tt>jit.arch</tt></h3>
168<p>
169Contains the target architecture name (CPU and optional ABI).
170</p>
171
172<h2 id="jit_opt"><tt>jit.opt.*</tt> &mdash; JIT compiler optimization control</h2>
173<p>
174This module provides the backend for the <tt>-O</tt> command line
175option.
176</p>
177<p>
178You can also use it programmatically, e.g.:
179</p>
180<pre class="code">
181jit.opt.start(2) -- same as -O2
182jit.opt.start("-dce")
183jit.opt.start("hotloop=10", "hotexit=2")
184</pre>
185<p>
186Unlike in LuaJIT 1.x, the module is built-in and
187<b>optimization is turned on by default!</b>
188It's no longer necessary to run <tt>require("jit.opt").start()</tt>,
189which was one of the ways to enable optimization.
190</p>
191
192<h2 id="jit_util"><tt>jit.util.*</tt> &mdash; JIT compiler introspection</h2>
193<p>
194This module holds functions to introspect the bytecode, generated
195traces, the IR and the generated machine code. The functionality
196provided by this module is still in flux and therefore undocumented.
197</p>
198<p>
199The debug modules <tt>-jbc</tt>, <tt>-jv</tt> and <tt>-jdump</tt> make
200extensive use of these functions. Please check out their source code,
201if you want to know more.
202</p>
203
204<h2 id="c_api">C API extensions</h2>
205<p>
206LuaJIT adds some extensions to the Lua/C API. The LuaJIT include
207directory must be in the compiler search path (<tt>-I<i>path</i></tt>)
208to be able to include the required header for C code:
209</p>
210<pre class="code">
211#include "luajit.h"
212</pre>
213<p>
214Or for C++ code:
215</p>
216<pre class="code">
217#include "lua.hpp"
218</pre>
219
220<h2 id="luaJIT_setmode"><tt>luaJIT_setmode(L, idx, mode)</tt>
221&mdash; Control VM</h2>
222<p>
223This is a C API extension to allow control of the VM from C code. The
224full prototype of <tt>LuaJIT_setmode</tt> is:
225</p>
226<pre class="code">
227LUA_API int luaJIT_setmode(lua_State *L, int idx, int mode);
228</pre>
229<p>
230The returned status is either success (<tt>1</tt>) or failure (<tt>0</tt>).
231The second argument is either <tt>0</tt> or a stack index (similar to the
232other Lua/C API functions).
233</p>
234<p>
235The third argument specifies the mode, which is 'or'ed with a flag.
236The flag can be <tt>LUAJIT_MODE_OFF</tt> to turn a feature on,
237<tt>LUAJIT_MODE_ON</tt> to turn a feature off, or
238<tt>LUAJIT_MODE_FLUSH</tt> to flush cached code.
239</p>
240<p>
241The following modes are defined:
242</p>
243
244<h3 id="mode_engine"><tt>luaJIT_setmode(L, 0, LUAJIT_MODE_ENGINE|flag)</tt></h3>
245<p>
246Turn the whole JIT compiler on or off or flush the whole cache of compiled code.
247</p>
248
249<h3 id="mode_func"><tt>luaJIT_setmode(L, idx, LUAJIT_MODE_FUNC|flag)</tt><br>
250<tt>luaJIT_setmode(L, idx, LUAJIT_MODE_ALLFUNC|flag)</tt><br>
251<tt>luaJIT_setmode(L, idx, LUAJIT_MODE_ALLSUBFUNC|flag)</tt></h3>
252<p>
253This sets the mode for the function at the stack index <tt>idx</tt> or
254the parent of the calling function (<tt>idx = 0</tt>). It either
255enables JIT compilation for a function, disables it and flushes any
256already compiled code or only flushes already compiled code. This
257applies recursively to all sub-functions of the function with
258<tt>LUAJIT_MODE_ALLFUNC</tt> or only to the sub-functions with
259<tt>LUAJIT_MODE_ALLSUBFUNC</tt>.
260</p>
261
262<h3 id="mode_trace"><tt>luaJIT_setmode(L, trace,<br>
263&nbsp;&nbsp;LUAJIT_MODE_TRACE|LUAJIT_MODE_FLUSH)</tt></h3>
264<p>
265Flushes the specified root trace and all of its side traces from the cache.
266The code for the trace will be retained as long as there are any other
267traces which link to it.
268</p>
269
270<h3 id="mode_wrapcfunc"><tt>luaJIT_setmode(L, idx, LUAJIT_MODE_WRAPCFUNC|flag)</tt></h3>
271<p>
272This mode defines a wrapper function for calls to C functions. If
273called with <tt>LUAJIT_MODE_ON</tt>, the stack index at <tt>idx</tt>
274must be a <tt>lightuserdata</tt> object holding a pointer to the wrapper
275function. From now on all C functions are called through the wrapper
276function. If called with <tt>LUAJIT_MODE_OFF</tt> this mode is turned
277off and all C functions are directly called.
278</p>
279<p>
280The wrapper function can be used for debugging purposes or to catch
281and convert foreign exceptions. Recommended usage can be seen in this
282C++ code excerpt:
283</p>
284<pre class="code">
285#include &lt;exception&gt;
286#include "lua.hpp"
287
288// Catch C++ exceptions and convert them to Lua error messages.
289// Customize as needed for your own exception classes.
290static int wrap_exceptions(lua_State *L, lua_CFunction f)
291{
292 try {
293 return f(L); // Call wrapped function and return result.
294 } catch (const char *s) { // Catch and convert exceptions.
295 lua_pushstring(L, s);
296 } catch (std::exception& e) {
297 lua_pushstring(L, e.what());
298 } catch (...) {
299 lua_pushliteral(L, "caught (...)");
300 }
301 return lua_error(L); // Rethrow as a Lua error.
302}
303
304static int myinit(lua_State *L)
305{
306 ...
307 // Define wrapper function and enable it.
308 lua_pushlightuserdata(L, (void *)wrap_exceptions);
309 luaJIT_setmode(L, -1, LUAJIT_MODE_WRAPCFUNC|LUAJIT_MODE_ON);
310 lua_pop(L, 1);
311 ...
312}
313</pre>
314<p>
315Note that you can only define <b>a single global wrapper function</b>,
316so be careful when using this mechanism from multiple C++ modules.
317Also note that this mechanism is not without overhead.
318</p>
319<p>
320LuaJIT already intercepts exception handling for systems using DWARF2
321stack unwinding (e.g. Linux or OSX) and for Windows/x64 (but <b>not</b>
322for Windows/x86). This is a zero-cost mechanism and always enabled.
323You don't need to use any wrapper functions, except when you want to get
324a more specific error message than <tt>"C++&nbsp;exception"</tt>.
325</p>
326<br class="flush">
327</div>
328<div id="foot">
329<hr class="hide">
330Copyright &copy; 2005-2010 Mike Pall
331<span class="noprint">
332&middot;
333<a href="contact.html">Contact</a>
334</span>
335</div>
336</body>
337</html>
diff --git a/doc/changes.html b/doc/changes.html
index 54f17a16..b7ac0734 100644
--- a/doc/changes.html
+++ b/doc/changes.html
@@ -26,8 +26,13 @@ div.major { max-width: 600px; padding: 1em; margin: 1em 0 1em 0; }
26<a href="install.html">Installation</a> 26<a href="install.html">Installation</a>
27</li><li> 27</li><li>
28<a href="running.html">Running</a> 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_jit.html">jit.* Library</a>
29</li><li> 34</li><li>
30<a href="api.html">API Extensions</a> 35<a href="ext_c_api.html">Lua/C API</a>
31</li></ul> 36</li></ul>
32</li><li> 37</li><li>
33<a href="status.html">Status</a> 38<a href="status.html">Status</a>
diff --git a/doc/contact.html b/doc/contact.html
index afd17451..13175844 100644
--- a/doc/contact.html
+++ b/doc/contact.html
@@ -23,8 +23,13 @@
23<a href="install.html">Installation</a> 23<a href="install.html">Installation</a>
24</li><li> 24</li><li>
25<a href="running.html">Running</a> 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_jit.html">jit.* Library</a>
26</li><li> 31</li><li>
27<a href="api.html">API Extensions</a> 32<a href="ext_c_api.html">Lua/C API</a>
28</li></ul> 33</li></ul>
29</li><li> 34</li><li>
30<a href="status.html">Status</a> 35<a href="status.html">Status</a>
diff --git a/doc/ext_c_api.html b/doc/ext_c_api.html
new file mode 100644
index 00000000..1418b2a9
--- /dev/null
+++ b/doc/ext_c_api.html
@@ -0,0 +1,174 @@
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-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</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_jit.html">jit.* Library</a>
31</li><li>
32<a class="current" href="ext_c_api.html">Lua/C API</a>
33</li></ul>
34</li><li>
35<a href="status.html">Status</a>
36<ul><li>
37<a href="changes.html">Changes</a>
38</li></ul>
39</li><li>
40<a href="faq.html">FAQ</a>
41</li><li>
42<a href="http://luajit.org/performance.html">Performance <span class="ext">&raquo;</span></a>
43</li><li>
44<a href="http://luajit.org/download.html">Download <span class="ext">&raquo;</span></a>
45</li></ul>
46</div>
47<div id="main">
48<p>
49LuaJIT adds some extensions to the standard Lua/C API. The LuaJIT include
50directory must be in the compiler search path (<tt>-I<i>path</i></tt>)
51to be able to include the required header for C code:
52</p>
53<pre class="code">
54#include "luajit.h"
55</pre>
56<p>
57Or for C++ code:
58</p>
59<pre class="code">
60#include "lua.hpp"
61</pre>
62
63<h2 id="luaJIT_setmode"><tt>luaJIT_setmode(L, idx, mode)</tt>
64&mdash; Control VM</h2>
65<p>
66This is a C API extension to allow control of the VM from C code. The
67full prototype of <tt>LuaJIT_setmode</tt> is:
68</p>
69<pre class="code">
70LUA_API int luaJIT_setmode(lua_State *L, int idx, int mode);
71</pre>
72<p>
73The returned status is either success (<tt>1</tt>) or failure (<tt>0</tt>).
74The second argument is either <tt>0</tt> or a stack index (similar to the
75other Lua/C API functions).
76</p>
77<p>
78The third argument specifies the mode, which is 'or'ed with a flag.
79The flag can be <tt>LUAJIT_MODE_OFF</tt> to turn a feature on,
80<tt>LUAJIT_MODE_ON</tt> to turn a feature off, or
81<tt>LUAJIT_MODE_FLUSH</tt> to flush cached code.
82</p>
83<p>
84The following modes are defined:
85</p>
86
87<h3 id="mode_engine"><tt>luaJIT_setmode(L, 0, LUAJIT_MODE_ENGINE|flag)</tt></h3>
88<p>
89Turn the whole JIT compiler on or off or flush the whole cache of compiled code.
90</p>
91
92<h3 id="mode_func"><tt>luaJIT_setmode(L, idx, LUAJIT_MODE_FUNC|flag)</tt><br>
93<tt>luaJIT_setmode(L, idx, LUAJIT_MODE_ALLFUNC|flag)</tt><br>
94<tt>luaJIT_setmode(L, idx, LUAJIT_MODE_ALLSUBFUNC|flag)</tt></h3>
95<p>
96This sets the mode for the function at the stack index <tt>idx</tt> or
97the parent of the calling function (<tt>idx = 0</tt>). It either
98enables JIT compilation for a function, disables it and flushes any
99already compiled code or only flushes already compiled code. This
100applies recursively to all sub-functions of the function with
101<tt>LUAJIT_MODE_ALLFUNC</tt> or only to the sub-functions with
102<tt>LUAJIT_MODE_ALLSUBFUNC</tt>.
103</p>
104
105<h3 id="mode_trace"><tt>luaJIT_setmode(L, trace,<br>
106&nbsp;&nbsp;LUAJIT_MODE_TRACE|LUAJIT_MODE_FLUSH)</tt></h3>
107<p>
108Flushes the specified root trace and all of its side traces from the cache.
109The code for the trace will be retained as long as there are any other
110traces which link to it.
111</p>
112
113<h3 id="mode_wrapcfunc"><tt>luaJIT_setmode(L, idx, LUAJIT_MODE_WRAPCFUNC|flag)</tt></h3>
114<p>
115This mode defines a wrapper function for calls to C functions. If
116called with <tt>LUAJIT_MODE_ON</tt>, the stack index at <tt>idx</tt>
117must be a <tt>lightuserdata</tt> object holding a pointer to the wrapper
118function. From now on all C functions are called through the wrapper
119function. If called with <tt>LUAJIT_MODE_OFF</tt> this mode is turned
120off and all C functions are directly called.
121</p>
122<p>
123The wrapper function can be used for debugging purposes or to catch
124and convert foreign exceptions. But please read the section on
125<a href="extensions.html#exceptions">C++&nbsp;exception interoperability</a>
126first. Recommended usage can be seen in this C++ code excerpt:
127</p>
128<pre class="code">
129#include &lt;exception&gt;
130#include "lua.hpp"
131
132// Catch C++ exceptions and convert them to Lua error messages.
133// Customize as needed for your own exception classes.
134static int wrap_exceptions(lua_State *L, lua_CFunction f)
135{
136 try {
137 return f(L); // Call wrapped function and return result.
138 } catch (const char *s) { // Catch and convert exceptions.
139 lua_pushstring(L, s);
140 } catch (std::exception& e) {
141 lua_pushstring(L, e.what());
142 } catch (...) {
143 lua_pushliteral(L, "caught (...)");
144 }
145 return lua_error(L); // Rethrow as a Lua error.
146}
147
148static int myinit(lua_State *L)
149{
150 ...
151 // Define wrapper function and enable it.
152 lua_pushlightuserdata(L, (void *)wrap_exceptions);
153 luaJIT_setmode(L, -1, LUAJIT_MODE_WRAPCFUNC|LUAJIT_MODE_ON);
154 lua_pop(L, 1);
155 ...
156}
157</pre>
158<p>
159Note that you can only define <b>a single global wrapper function</b>,
160so be careful when using this mechanism from multiple C++ modules.
161Also note that this mechanism is not without overhead.
162</p>
163<br class="flush">
164</div>
165<div id="foot">
166<hr class="hide">
167Copyright &copy; 2005-2010 Mike Pall
168<span class="noprint">
169&middot;
170<a href="contact.html">Contact</a>
171</span>
172</div>
173</body>
174</html>
diff --git a/doc/ext_jit.html b/doc/ext_jit.html
new file mode 100644
index 00000000..d621476b
--- /dev/null
+++ b/doc/ext_jit.html
@@ -0,0 +1,177 @@
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-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</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 class="current" href="ext_jit.html">jit.* Library</a>
31</li><li>
32<a href="ext_c_api.html">Lua/C API</a>
33</li></ul>
34</li><li>
35<a href="status.html">Status</a>
36<ul><li>
37<a href="changes.html">Changes</a>
38</li></ul>
39</li><li>
40<a href="faq.html">FAQ</a>
41</li><li>
42<a href="http://luajit.org/performance.html">Performance <span class="ext">&raquo;</span></a>
43</li><li>
44<a href="http://luajit.org/download.html">Download <span class="ext">&raquo;</span></a>
45</li></ul>
46</div>
47<div id="main">
48<p>
49The functions in this built-in module control the behavior
50of the JIT compiler engine.
51</p>
52
53<h3 id="jit_onoff"><tt>jit.on()<br>
54jit.off()</tt></h3>
55<p>
56Turns the whole JIT compiler on (default) or off.
57</p>
58<p>
59These functions are typically used with the command line options
60<tt>-j on</tt> or <tt>-j off</tt>.
61</p>
62
63<h3 id="jit_flush"><tt>jit.flush()</tt></h3>
64<p>
65Flushes the whole cache of compiled code.
66</p>
67
68<h3 id="jit_onoff_func"><tt>jit.on(func|true [,true|false])<br>
69jit.off(func|true [,true|false])<br>
70jit.flush(func|true [,true|false])</tt></h3>
71<p>
72<tt>jit.on</tt> enables JIT compilation for a Lua function (this is
73the default).
74</p>
75<p>
76<tt>jit.off</tt> disables JIT compilation for a Lua function and
77flushes any already compiled code from the code cache.
78</p>
79<p>
80<tt>jit.flush</tt> flushes the code, but doesn't affect the
81enable/disable status.
82</p>
83<p>
84The current function, i.e. the Lua function calling this library
85function, can also be specified by passing <tt>true</tt> as the first
86argument.
87</p>
88<p>
89If the second argument is <tt>true</tt>, JIT compilation is also
90enabled, disabled or flushed recursively for all sub-functions of a
91function. With <tt>false</tt> only the sub-functions are affected.
92</p>
93<p>
94The <tt>jit.on</tt> and <tt>jit.off</tt> functions only set a flag
95which is checked when the function is about to be compiled. They do
96not trigger immediate compilation.
97</p>
98<p>
99Typical usage is <tt>jit.off(true, true)</tt> in the main chunk
100of a module to turn off JIT compilation for the whole module for
101debugging purposes.
102</p>
103
104<h3 id="jit_flush_tr"><tt>jit.flush(tr)</tt></h3>
105<p>
106Flushes the specified root trace and all of its side traces from the cache.
107The code for the trace will be retained as long as there are any other
108traces which link to it.
109</p>
110
111<h3 id="jit_status"><tt>status, ... = jit.status()</tt></h3>
112<p>
113Returns the current status of the JIT compiler. The first result is
114either <tt>true</tt> or <tt>false</tt> if the JIT compiler is turned
115on or off. The remaining results are strings for CPU-specific features
116and enabled optimizations.
117</p>
118
119<h3 id="jit_version"><tt>jit.version</tt></h3>
120<p>
121Contains the LuaJIT version string.
122</p>
123
124<h3 id="jit_version_num"><tt>jit.version_num</tt></h3>
125<p>
126Contains the version number of the LuaJIT core. Version xx.yy.zz
127is represented by the decimal number xxyyzz.
128</p>
129
130<h3 id="jit_arch"><tt>jit.arch</tt></h3>
131<p>
132Contains the target architecture name (CPU and optional ABI).
133</p>
134
135<h2 id="jit_opt"><tt>jit.opt.*</tt> &mdash; JIT compiler optimization control</h2>
136<p>
137This sub-module provides the backend for the <tt>-O</tt> command line
138option.
139</p>
140<p>
141You can also use it programmatically, e.g.:
142</p>
143<pre class="code">
144jit.opt.start(2) -- same as -O2
145jit.opt.start("-dce")
146jit.opt.start("hotloop=10", "hotexit=2")
147</pre>
148<p>
149Unlike in LuaJIT 1.x, the module is built-in and
150<b>optimization is turned on by default!</b>
151It's no longer necessary to run <tt>require("jit.opt").start()</tt>,
152which was one of the ways to enable optimization.
153</p>
154
155<h2 id="jit_util"><tt>jit.util.*</tt> &mdash; JIT compiler introspection</h2>
156<p>
157This sub-module holds functions to introspect the bytecode, generated
158traces, the IR and the generated machine code. The functionality
159provided by this module is still in flux and therefore undocumented.
160</p>
161<p>
162The debug modules <tt>-jbc</tt>, <tt>-jv</tt> and <tt>-jdump</tt> make
163extensive use of these functions. Please check out their source code,
164if you want to know more.
165</p>
166<br class="flush">
167</div>
168<div id="foot">
169<hr class="hide">
170Copyright &copy; 2005-2010 Mike Pall
171<span class="noprint">
172&middot;
173<a href="contact.html">Contact</a>
174</span>
175</div>
176</body>
177</html>
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>
diff --git a/doc/faq.html b/doc/faq.html
index 9404f788..c1d86db9 100644
--- a/doc/faq.html
+++ b/doc/faq.html
@@ -26,8 +26,13 @@ dd { margin-left: 1.5em; }
26<a href="install.html">Installation</a> 26<a href="install.html">Installation</a>
27</li><li> 27</li><li>
28<a href="running.html">Running</a> 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_jit.html">jit.* Library</a>
29</li><li> 34</li><li>
30<a href="api.html">API Extensions</a> 35<a href="ext_c_api.html">Lua/C API</a>
31</li></ul> 36</li></ul>
32</li><li> 37</li><li>
33<a href="status.html">Status</a> 38<a href="status.html">Status</a>
diff --git a/doc/install.html b/doc/install.html
index 775b3470..9dac37a3 100644
--- a/doc/install.html
+++ b/doc/install.html
@@ -13,19 +13,19 @@ table.compat {
13 line-height: 1.2; 13 line-height: 1.2;
14 width: 600px; 14 width: 600px;
15} 15}
16tr.compathead td { 16table.compat td {
17 border: 1px solid #bfcfff;
18 font-size: 90%;
19 height: 2.5em;
20}
21table.compat tr.compathead td {
17 font-weight: bold; 22 font-weight: bold;
18 border-bottom: 2px solid #bfcfff; 23 border-bottom: 2px solid #bfcfff;
19} 24}
20tr.compathead td.compatos { 25tr.compathead td.compatos {
21 vertical-align: top; 26 vertical-align: top;
22} 27}
23td { 28table.compat td.compatcpu {
24 border: 1px solid #bfcfff;
25 font-size: 90%;
26 height: 2.5em;
27}
28td.compatcpu {
29 width: 16%; 29 width: 16%;
30 border-right: 2px solid #bfcfff; 30 border-right: 2px solid #bfcfff;
31} 31}
@@ -52,8 +52,13 @@ td.compatno {
52<a class="current" href="install.html">Installation</a> 52<a class="current" href="install.html">Installation</a>
53</li><li> 53</li><li>
54<a href="running.html">Running</a> 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_jit.html">jit.* Library</a>
55</li><li> 60</li><li>
56<a href="api.html">API Extensions</a> 61<a href="ext_c_api.html">Lua/C API</a>
57</li></ul> 62</li></ul>
58</li><li> 63</li><li>
59<a href="status.html">Status</a> 64<a href="status.html">Status</a>
diff --git a/doc/luajit.html b/doc/luajit.html
index 71e6a19f..990cd630 100644
--- a/doc/luajit.html
+++ b/doc/luajit.html
@@ -24,8 +24,13 @@
24<a href="install.html">Installation</a> 24<a href="install.html">Installation</a>
25</li><li> 25</li><li>
26<a href="running.html">Running</a> 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_jit.html">jit.* Library</a>
27</li><li> 32</li><li>
28<a href="api.html">API Extensions</a> 33<a href="ext_c_api.html">Lua/C API</a>
29</li></ul> 34</li></ul>
30</li><li> 35</li><li>
31<a href="status.html">Status</a> 36<a href="status.html">Status</a>
diff --git a/doc/running.html b/doc/running.html
index e337d535..6991ef7a 100644
--- a/doc/running.html
+++ b/doc/running.html
@@ -45,8 +45,13 @@ td.param_default {
45<a href="install.html">Installation</a> 45<a href="install.html">Installation</a>
46</li><li> 46</li><li>
47<a class="current" href="running.html">Running</a> 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_jit.html">jit.* Library</a>
48</li><li> 53</li><li>
49<a href="api.html">API Extensions</a> 54<a href="ext_c_api.html">Lua/C API</a>
50</li></ul> 55</li></ul>
51</li><li> 56</li><li>
52<a href="status.html">Status</a> 57<a href="status.html">Status</a>
diff --git a/doc/status.html b/doc/status.html
index a508dca1..15e114c2 100644
--- a/doc/status.html
+++ b/doc/status.html
@@ -26,8 +26,13 @@ ul li { padding-bottom: 0.3em; }
26<a href="install.html">Installation</a> 26<a href="install.html">Installation</a>
27</li><li> 27</li><li>
28<a href="running.html">Running</a> 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_jit.html">jit.* Library</a>
29</li><li> 34</li><li>
30<a href="api.html">API Extensions</a> 35<a href="ext_c_api.html">Lua/C API</a>
31</li></ul> 36</li></ul>
32</li><li> 37</li><li>
33<a class="current" href="status.html">Status</a> 38<a class="current" href="status.html">Status</a>
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-03-20 17:02:10 +0000