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