diff options
Diffstat (limited to 'doc/api.html')
-rw-r--r-- | doc/api.html | 337 |
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">»</span></a> | ||
38 | </li><li> | ||
39 | <a href="http://luajit.org/download.html">Download <span class="ext">»</span></a> | ||
40 | </li></ul> | ||
41 | </div> | ||
42 | <div id="main"> | ||
43 | <p> | ||
44 | LuaJIT 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">»</span> standard Lua | ||
46 | library functions</a> and the full set of | ||
47 | <a href="http://www.lua.org/manual/5.1/manual.html#3"><span class="ext">»</span> Lua/C API | ||
48 | functions</a>. | ||
49 | </p> | ||
50 | <p> | ||
51 | LuaJIT is also fully ABI-compatible to Lua 5.1 at the linker/dynamic | ||
52 | loader level. This means you can compile a C module against the | ||
53 | standard Lua headers and load the same shared library from either Lua | ||
54 | or LuaJIT. | ||
55 | </p> | ||
56 | |||
57 | <h2 id="bit"><tt>bit.*</tt> — Bitwise Operations</h2> | ||
58 | <p> | ||
59 | LuaJIT supports all bitwise operations as defined by | ||
60 | <a href="http://bitop.luajit.org"><span class="ext">»</span> Lua BitOp</a>: | ||
61 | </p> | ||
62 | <pre class="code"> | ||
63 | bit.tobit bit.tohex bit.bnot bit.band bit.bor bit.bxor | ||
64 | bit.lshift bit.rshift bit.arshift bit.rol bit.ror bit.bswap | ||
65 | </pre> | ||
66 | <p> | ||
67 | This module is a LuaJIT built-in — you don't need to download or | ||
68 | install Lua BitOp. The Lua BitOp site has full documentation for all | ||
69 | <a href="http://bitop.luajit.org/api.html"><span class="ext">»</span> Lua BitOp API functions</a>. | ||
70 | </p> | ||
71 | <p> | ||
72 | Please make sure to <tt>require</tt> the module before using any of | ||
73 | its functions: | ||
74 | </p> | ||
75 | <pre class="code"> | ||
76 | local bit = require("bit") | ||
77 | </pre> | ||
78 | <p> | ||
79 | An already installed Lua BitOp module is ignored by LuaJIT. | ||
80 | This way you can use bit operations from both Lua and LuaJIT on a | ||
81 | shared installation. | ||
82 | </p> | ||
83 | |||
84 | <h2 id="jit"><tt>jit.*</tt> — JIT compiler control</h2> | ||
85 | <p> | ||
86 | The functions in this built-in module control the behavior | ||
87 | of the JIT compiler engine. | ||
88 | </p> | ||
89 | |||
90 | <h3 id="jit_onoff"><tt>jit.on()<br> | ||
91 | jit.off()</tt></h3> | ||
92 | <p> | ||
93 | Turns the whole JIT compiler on (default) or off. | ||
94 | </p> | ||
95 | <p> | ||
96 | These 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> | ||
102 | Flushes the whole cache of compiled code. | ||
103 | </p> | ||
104 | |||
105 | <h3 id="jit_onoff_func"><tt>jit.on(func|true [,true|false])<br> | ||
106 | jit.off(func|true [,true|false])<br> | ||
107 | jit.flush(func|true [,true|false])</tt></h3> | ||
108 | <p> | ||
109 | <tt>jit.on</tt> enables JIT compilation for a Lua function (this is | ||
110 | the default). | ||
111 | </p> | ||
112 | <p> | ||
113 | <tt>jit.off</tt> disables JIT compilation for a Lua function and | ||
114 | flushes 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 | ||
118 | enable/disable status. | ||
119 | </p> | ||
120 | <p> | ||
121 | The current function, i.e. the Lua function calling this library | ||
122 | function, can also be specified by passing <tt>true</tt> as the first | ||
123 | argument. | ||
124 | </p> | ||
125 | <p> | ||
126 | If the second argument is <tt>true</tt>, JIT compilation is also | ||
127 | enabled, disabled or flushed recursively for all sub-functions of a | ||
128 | function. With <tt>false</tt> only the sub-functions are affected. | ||
129 | </p> | ||
130 | <p> | ||
131 | The <tt>jit.on</tt> and <tt>jit.off</tt> functions only set a flag | ||
132 | which is checked when the function is about to be compiled. They do | ||
133 | not trigger immediate compilation. | ||
134 | </p> | ||
135 | <p> | ||
136 | Typical usage is <tt>jit.off(true, true)</tt> in the main chunk | ||
137 | of a module to turn off JIT compilation for the whole module for | ||
138 | debugging purposes. | ||
139 | </p> | ||
140 | |||
141 | <h3 id="jit_flush_tr"><tt>jit.flush(tr)</tt></h3> | ||
142 | <p> | ||
143 | Flushes the specified root trace and all of its side traces from the cache. | ||
144 | The code for the trace will be retained as long as there are any other | ||
145 | traces which link to it. | ||
146 | </p> | ||
147 | |||
148 | <h3 id="jit_status"><tt>status, ... = jit.status()</tt></h3> | ||
149 | <p> | ||
150 | Returns the current status of the JIT compiler. The first result is | ||
151 | either <tt>true</tt> or <tt>false</tt> if the JIT compiler is turned | ||
152 | on or off. The remaining results are strings for CPU-specific features | ||
153 | and enabled optimizations. | ||
154 | </p> | ||
155 | |||
156 | <h3 id="jit_version"><tt>jit.version</tt></h3> | ||
157 | <p> | ||
158 | Contains the LuaJIT version string. | ||
159 | </p> | ||
160 | |||
161 | <h3 id="jit_version_num"><tt>jit.version_num</tt></h3> | ||
162 | <p> | ||
163 | Contains the version number of the LuaJIT core. Version xx.yy.zz | ||
164 | is represented by the decimal number xxyyzz. | ||
165 | </p> | ||
166 | |||
167 | <h3 id="jit_arch"><tt>jit.arch</tt></h3> | ||
168 | <p> | ||
169 | Contains the target architecture name (CPU and optional ABI). | ||
170 | </p> | ||
171 | |||
172 | <h2 id="jit_opt"><tt>jit.opt.*</tt> — JIT compiler optimization control</h2> | ||
173 | <p> | ||
174 | This module provides the backend for the <tt>-O</tt> command line | ||
175 | option. | ||
176 | </p> | ||
177 | <p> | ||
178 | You can also use it programmatically, e.g.: | ||
179 | </p> | ||
180 | <pre class="code"> | ||
181 | jit.opt.start(2) -- same as -O2 | ||
182 | jit.opt.start("-dce") | ||
183 | jit.opt.start("hotloop=10", "hotexit=2") | ||
184 | </pre> | ||
185 | <p> | ||
186 | Unlike in LuaJIT 1.x, the module is built-in and | ||
187 | <b>optimization is turned on by default!</b> | ||
188 | It's no longer necessary to run <tt>require("jit.opt").start()</tt>, | ||
189 | which was one of the ways to enable optimization. | ||
190 | </p> | ||
191 | |||
192 | <h2 id="jit_util"><tt>jit.util.*</tt> — JIT compiler introspection</h2> | ||
193 | <p> | ||
194 | This module holds functions to introspect the bytecode, generated | ||
195 | traces, the IR and the generated machine code. The functionality | ||
196 | provided by this module is still in flux and therefore undocumented. | ||
197 | </p> | ||
198 | <p> | ||
199 | The debug modules <tt>-jbc</tt>, <tt>-jv</tt> and <tt>-jdump</tt> make | ||
200 | extensive use of these functions. Please check out their source code, | ||
201 | if you want to know more. | ||
202 | </p> | ||
203 | |||
204 | <h2 id="c_api">C API extensions</h2> | ||
205 | <p> | ||
206 | LuaJIT adds some extensions to the Lua/C API. The LuaJIT include | ||
207 | directory must be in the compiler search path (<tt>-I<i>path</i></tt>) | ||
208 | to be able to include the required header for C code: | ||
209 | </p> | ||
210 | <pre class="code"> | ||
211 | #include "luajit.h" | ||
212 | </pre> | ||
213 | <p> | ||
214 | Or 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 | — Control VM</h2> | ||
222 | <p> | ||
223 | This is a C API extension to allow control of the VM from C code. The | ||
224 | full prototype of <tt>LuaJIT_setmode</tt> is: | ||
225 | </p> | ||
226 | <pre class="code"> | ||
227 | LUA_API int luaJIT_setmode(lua_State *L, int idx, int mode); | ||
228 | </pre> | ||
229 | <p> | ||
230 | The returned status is either success (<tt>1</tt>) or failure (<tt>0</tt>). | ||
231 | The second argument is either <tt>0</tt> or a stack index (similar to the | ||
232 | other Lua/C API functions). | ||
233 | </p> | ||
234 | <p> | ||
235 | The third argument specifies the mode, which is 'or'ed with a flag. | ||
236 | The 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> | ||
241 | The 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> | ||
246 | Turn 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> | ||
253 | This sets the mode for the function at the stack index <tt>idx</tt> or | ||
254 | the parent of the calling function (<tt>idx = 0</tt>). It either | ||
255 | enables JIT compilation for a function, disables it and flushes any | ||
256 | already compiled code or only flushes already compiled code. This | ||
257 | applies 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 | LUAJIT_MODE_TRACE|LUAJIT_MODE_FLUSH)</tt></h3> | ||
264 | <p> | ||
265 | Flushes the specified root trace and all of its side traces from the cache. | ||
266 | The code for the trace will be retained as long as there are any other | ||
267 | traces 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> | ||
272 | This mode defines a wrapper function for calls to C functions. If | ||
273 | called with <tt>LUAJIT_MODE_ON</tt>, the stack index at <tt>idx</tt> | ||
274 | must be a <tt>lightuserdata</tt> object holding a pointer to the wrapper | ||
275 | function. From now on all C functions are called through the wrapper | ||
276 | function. If called with <tt>LUAJIT_MODE_OFF</tt> this mode is turned | ||
277 | off and all C functions are directly called. | ||
278 | </p> | ||
279 | <p> | ||
280 | The wrapper function can be used for debugging purposes or to catch | ||
281 | and convert foreign exceptions. Recommended usage can be seen in this | ||
282 | C++ code excerpt: | ||
283 | </p> | ||
284 | <pre class="code"> | ||
285 | #include <exception> | ||
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. | ||
290 | static 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 | |||
304 | static 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> | ||
315 | Note that you can only define <b>a single global wrapper function</b>, | ||
316 | so be careful when using this mechanism from multiple C++ modules. | ||
317 | Also note that this mechanism is not without overhead. | ||
318 | </p> | ||
319 | <p> | ||
320 | LuaJIT already intercepts exception handling for systems using DWARF2 | ||
321 | stack unwinding (e.g. Linux or OSX) and for Windows/x64 (but <b>not</b> | ||
322 | for Windows/x86). This is a zero-cost mechanism and always enabled. | ||
323 | You don't need to use any wrapper functions, except when you want to get | ||
324 | a more specific error message than <tt>"C++ exception"</tt>. | ||
325 | </p> | ||
326 | <br class="flush"> | ||
327 | </div> | ||
328 | <div id="foot"> | ||
329 | <hr class="hide"> | ||
330 | Copyright © 2005-2010 Mike Pall | ||
331 | <span class="noprint"> | ||
332 | · | ||
333 | <a href="contact.html">Contact</a> | ||
334 | </span> | ||
335 | </div> | ||
336 | </body> | ||
337 | </html> | ||