aboutsummaryrefslogtreecommitdiffstatshomepage
path: root/libraries/LuaJIT-1.1.7/jitdoc/luajit_api.html
diff options
context:
space:
mode:
Diffstat (limited to 'libraries/LuaJIT-1.1.7/jitdoc/luajit_api.html')
-rw-r--r--libraries/LuaJIT-1.1.7/jitdoc/luajit_api.html372
1 files changed, 372 insertions, 0 deletions
diff --git a/libraries/LuaJIT-1.1.7/jitdoc/luajit_api.html b/libraries/LuaJIT-1.1.7/jitdoc/luajit_api.html
new file mode 100644
index 0000000..58ac809
--- /dev/null
+++ b/libraries/LuaJIT-1.1.7/jitdoc/luajit_api.html
@@ -0,0 +1,372 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
2<html>
3<head>
4<title>LuaJIT 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-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">
12td.stname { width: 10em; }
13tr.sthead td { font-weight: bold; }
14</style>
15</head>
16<body>
17<div id="site">
18<a href="http://luajit.org/"><span>Lua<span id="logo">JIT</span></span></a>
19</div>
20<div id="head">
21<h1>LuaJIT API Extensions</h1>
22</div>
23<div id="nav">
24<ul><li>
25<a href="index.html">Index</a>
26</li><li>
27<a href="luajit.html">LuaJIT</a>
28<ul><li>
29<a href="luajit_features.html">Features</a>
30</li><li>
31<a href="luajit_install.html">Installation</a>
32</li><li>
33<a href="luajit_run.html">Running</a>
34</li><li>
35<a class="current" href="luajit_api.html">API Extensions</a>
36</li><li>
37<a href="luajit_intro.html">Introduction</a>
38</li><li>
39<a href="luajit_performance.html">Performance</a>
40</li><li>
41<a href="luajit_debug.html">Debugging</a>
42</li><li>
43<a href="luajit_changes.html">Changes</a>
44</li></ul>
45</li><li>
46<a href="coco.html">Coco</a>
47<ul><li>
48<a href="coco_portability.html">Portability</a>
49</li><li>
50<a href="coco_api.html">API Extensions</a>
51</li><li>
52<a href="coco_changes.html">Changes</a>
53</li></ul>
54</li><li>
55<a href="dynasm.html">DynASM</a>
56<ul><li>
57<a href="dynasm_features.html">Features</a>
58</li><li>
59<a href="dynasm_examples.html">Examples</a>
60</li></ul>
61</li><li>
62<a href="http://luajit.org/download.html">Download <span class="ext">&raquo;</span></a>
63</li></ul>
64</div>
65<div id="main">
66<p>
67LuaJIT provides several new API functions organized into two
68libraries.
69</p>
70<p>
71LuaJIT includes Coco &mdash; so have a look at the
72<a href="coco_api.html">Coco API Extensions</a>, too.
73</p>
74
75<h2>Standard Library Functions</h2>
76<p>
77All standard library functions have the same behaviour as
78in the Lua distribution LuaJIT is based on.
79</p>
80<p>
81The Lua loader used by the standard <tt>require()</tt> library
82function has been modified to turn off compilation of the main
83chunk of a module. The main chunk is only run once when the module
84is loaded for the first time. There is no point in compiling it.
85</p>
86<p>
87You might want to adapt this behaviour if you use your own utility
88functions (and not <tt>require()</tt>) to load modules.
89</p>
90<p>
91Note that the subfunctions defined in a loaded module <em>are</em>
92of course compiled. See below if you want to override this.
93</p>
94
95<h2>The jit.* Library</h2>
96<p>
97This library holds several functions to control the behaviour
98of the JIT engine.
99</p>
100
101<h3 id="jit_onoff"><tt>jit.on()<br>
102jit.off()</tt></h3>
103<p>
104Turns the JIT engine on (default) or off.
105</p>
106<p>
107These functions are typically used with the command line options
108<tt>-j on</tt> or <tt>-j off</tt>.
109</p>
110
111<h3 id="jit_onoff_func"><tt>jit.on(func|true [,true|false])<br>
112jit.off(func|true [,true|false])</tt></h3>
113<p>
114Enable (with <tt>jit.on</tt>, default) or disable (with <tt>jit.off</tt>)
115JIT compilation for a Lua function. The current function (the Lua function
116calling this library function) can be specified with <tt>true</tt>.
117</p>
118<p>
119If the second argument is <tt>true</tt>, JIT compilation is also
120enabled/disabled recursively for all subfunctions of a function.
121With <tt>false</tt> only the subfunctions are affected.
122</p>
123<p>
124Both library functions only set a flag which is checked when
125the function is executed for the first/next time. They do not
126trigger immediate compilation.
127</p>
128<p>
129Typical usage is <tt>jit.off(true, true)</tt> in the main chunk
130of a module to turn off JIT compilation for the whole module.
131Note that <tt>require()</tt> already turns off compilation for
132the main chunk itself.
133</p>
134
135<h3 id="jit_compile"><tt>status = jit.compile(func [,args...])</tt></h3>
136<p>
137Compiles a Lua function and returns the compilation status.
138Successful compilation is indicated with a <tt>nil</tt> status.
139Failure is indicated with a numeric status (see <tt>jit.util.status</tt>).
140</p>
141<p>
142The optimizer pass of the compiler tries to derive hints from the
143passed arguments. Not passing any arguments or passing untypical
144arguments (esp. the wrong types) reduces the efficiency of the
145optimizer. The compiled function will still run, but probably not
146with maximum speed.
147</p>
148<p>
149This library function is typically used for Ahead-Of-Time (AOT)
150compilation of time-critical functions or for testing/debugging.
151</p>
152
153<h3 id="jit_compilesub"><tt>status = jit.compilesub(func|true [,true])</tt></h3>
154<p>
155Recursively compile all subfunctions of a Lua function.
156The current function (the Lua function calling this library function)
157can be specified with <tt>true</tt>. Note that the function
158<em>itself</em> is not compiled (use <tt>jit.compile()</tt>).
159</p>
160<p>
161If the second argument is <tt>true</tt>, compilation will stop
162when the first error is encountered. Otherwise compilation will
163continue with the next subfunction.
164</p>
165<p>
166The returned status is <tt>nil</tt>, if all subfunctions have been
167compiled successfully. A numeric status (see <tt>jit.util.status</tt>)
168indicates that at least one compilation failed and gives the status
169of the last failure (this is only helpful when stop on error
170is <tt>true</tt>).
171</p>
172
173<h3 id="jit_debug"><tt>jit.debug([level])</tt></h3>
174<p>
175Set the debug level for JIT compilation. If no <tt>level</tt> is given,
176the maximum debug level is set.
177</p>
178<ul>
179<li>Level 0 disables debugging: no checks for hooks are compiled
180into the code. This is the default when LuaJIT is started and
181provides the maximum performance.</li>
182<li>Level 1 enables function call debugging: call hooks and
183return hooks are checked in the function prologue and epilogue.
184This slows down function calls somewhat (by up to 10%).</li>
185<li>Level 2 enables full debugging: all hooks are checked.
186This slows down execution quite a bit, even when the hooks
187are not active.</li>
188</ul>
189<p>
190Note that some compiler optimizations are turned off when
191debugging is enabled.
192</p>
193<p>
194This function is typically used with the command line options
195<tt>-j debug</tt> or <tt>-j debug=level</tt>.
196</p>
197
198<h3 id="jit_attach"><tt>jit.attach(handler [, priority])</tt></h3>
199<p>
200Attach a handler to the compiler pipeline with the given priority.
201The handler is detached if no priority is given.
202</p>
203<p>
204The inner workings of the compiler pipeline and the API for handlers
205are still in flux. Please see the source code for more details.
206</p>
207
208<h3 id="jit_version"><tt>jit.version</tt></h3>
209<p>
210Contains the LuaJIT version string.
211</p>
212
213<h3 id="jit_version_num"><tt>jit.version_num</tt></h3>
214<p>
215Contains the version number of the LuaJIT core. Version xx.yy.zz
216is represented by the decimal number xxyyzz.
217</p>
218
219<h3 id="jit_arch"><tt>jit.arch</tt></h3>
220<p>
221Contains the target architecture name (CPU and optional ABI).
222</p>
223
224
225<h2 id="jit_util">The jit.util.* Library</h2>
226<p>
227This library holds many utility functions used by the provided
228extension modules for LuaJIT (e.g. the optimizer). The API may
229change in future versions.
230</p>
231
232<h3 id="jit_util_stats"><tt>stats = jit.util.stats(func)</tt></h3>
233<p>
234Retrieves information about a function. Returns <tt>nil</tt>
235for C functions. Returns a table with the following fields for
236Lua functions:
237</p>
238<ul>
239<li><tt>status</tt>: numeric compilation status (see <tt>jit.util.status</tt>).</li>
240<li><tt>stackslots</tt>: number of stack slots.</li>
241<li><tt>params</tt>: number of fixed parameters (arguments).</li>
242<li><tt>consts</tt>: number of constants.</li>
243<li><tt>upvalues</tt>: number of upvalues.</li>
244<li><tt>subs</tt>: number of subfunctions (sub prototypes).</li>
245<li><tt>bytecodes</tt>: number of bytecode instructions.</li>
246<li><tt>isvararg</tt>: fixarg (false) or vararg (true) function.</li>
247<li><tt>env</tt>: function environment table.</li>
248<li><tt>mcodesize</tt>: size of the compiled machine code.</li>
249<li><tt>mcodeaddr</tt>: start address of the compiled machine code.</li>
250</ul>
251<p>
252<tt>mcodesize</tt> and <tt>mcodeaddr</tt> are not set if the
253function has not been compiled (yet).
254</p>
255
256<h3 id="jit_util_bytecode"><tt>op, a, b, c, test = jit.util.bytecode(func, pc)</tt></h3>
257<p>
258Returns the fields of the bytecode instruction at the given <tt>pc</tt>
259for a Lua function. The first instruction is at <tt>pc</tt> = 1.
260Nothing is returned if <tt>pc</tt> is out of range.
261</p>
262<p>
263The opcode name is returned as an uppercase string in <tt>op</tt>.
264The opcode arguments are returned as <tt>a</tt>, <tt>b</tt> and
265optionally <tt>c</tt>. Arguments that indicate an index into the
266array of constants are translated to negative numbers (the first
267constant is referred to with -1). Branch targets are signed numbers
268relative to the next instruction.
269</p>
270<p>
271<tt>test</tt> is true if the instruction is a test (i.e. followed
272by a JMP).
273</p>
274
275<h3 id="jit_util_const"><tt>const, ok = jit.util.const(func, idx)</tt></h3>
276<p>
277Returns a constant from the array of constants for a Lua function.
278<tt>ok</tt> is true if <tt>idx</tt> is in range. Otherwise nothing
279is returned.
280</p>
281<p>
282Constants are numbered starting with 1. A negative <tt>idx</tt>
283is mapped to a positive index.
284</p>
285
286<h3 id="jit_util_upvalue"><tt>upvalue, ok = jit.util.upvalue(func, idx)</tt></h3>
287<p>
288Returns an upvalue from the array of upvalues for a Lua function.
289<tt>ok</tt> is true if <tt>idx</tt> is in range. Otherwise nothing
290is returned. Upvalues are numbered starting with 0.
291</p>
292
293<h3 id="jit_util_closurenup"><tt>nup = jit.util.closurenup(func, idx)</tt></h3>
294<p>
295Returns the number of upvalues for the subfunction prototype with
296the given index <tt>idx</tt> for a Lua function. Nothing is returned
297if <tt>idx</tt> is out of range. Subfunctions are numbered starting
298with 0.
299</p>
300
301<h3 id="jit_util_mcode"><tt>addr, mcode, mfmiter = jit.util.mcode(func, block])</tt></h3>
302<p>
303Returns the numeric start address, the compiled machine code
304(converted to a string) and an iterator for the machine code fragment map
305for the specified machine code block associated with a Lua function.
306</p>
307<p>
308Returns <tt>nil</tt> and a numeric status code (see <tt>jit.util.status</tt>)
309if the function has not been compiled yet or compilation has failed
310or compilation is disabled. Returns nothing if the selected
311machine code block does not exist.
312</p>
313<p>
314The machine code fragment map is used for debugging and error handling.
315The format may change between versions and is an internal implementation
316detail of LuaJIT.
317</p>
318
319<h3 id="jit_util_jsubmcode"><tt>addr [, mcode] = jit.util.jsubmcode([idx])</tt></h3>
320<p>
321If <tt>idx</tt> is omitted or nil:
322Returns the numeric start address and the compiled machine code
323(converted to a string) for internal subroutines used by the
324compiled machine code.
325</p>
326<p>
327If <tt>idx</tt> is given:
328Returns the numeric start address of the machine code for a specific
329internal subroutine (0&nbsp;based). Nothing is returned if <tt>idx</tt> is
330out of range.
331</p>
332
333<h3 id="jit_util_status"><tt>jit.util.status</tt></h3>
334<p>
335This is a table that bidirectionally maps status numbers and
336status names (strings):
337</p>
338<div class="tablewrap">
339<table>
340<tr class="sthead"><td class="stname">Status Name</td><td>Description</td></tr>
341<tr class="odd"><td class="stname">OK</td><td>Ok, code has been compiled.</td></tr>
342<tr class="even"><td class="stname">NONE</td><td>Nothing analyzed or compiled, yet (default).</td></tr>
343<tr class="odd"><td class="stname">OFF</td><td>Compilation disabled for this function.</td></tr>
344<tr class="even"><td class="stname">ENGINE_OFF</td><td>JIT engine is turned off.</td></tr>
345<tr class="odd"><td class="stname">DELAYED</td><td>Compilation delayed (recursive invocation).</td></tr>
346<tr class="even"><td class="stname">TOOLARGE</td><td>Bytecode or machine code is too large.</td></tr>
347<tr class="odd"><td class="stname">COMPILER_ERROR</td><td>Error from compiler frontend.</td></tr>
348<tr class="even"><td class="stname">DASM_ERROR</td><td>Error from DynASM engine.</td></tr>
349</table>
350</div>
351
352<h3 id="jit_util_hints"><tt>jit.util.hints<br>
353jit.util.fhints</tt></h3>
354<p>
355These two tables map compiler hint names to internal hint numbers.
356</p>
357<p>
358The hint system is an internal implementation detail of LuaJIT.
359Please see the source code for more info.
360</p>
361<br class="flush">
362</div>
363<div id="foot">
364<hr class="hide">
365Copyright &copy; 2005-2011 Mike Pall
366<span class="noprint">
367&middot;
368<a href="contact.html">Contact</a>
369</span>
370</div>
371</body>
372</html>
generated by cgit v1.1 at 2024-07-01 04:35:21 +0000