aboutsummaryrefslogtreecommitdiff
path: root/doc/api.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/api.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/api.html')
-rw-r--r--doc/api.html337
1 files changed, 0 insertions, 337 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>
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2026-01-13 23:42:33 +0000