summaryrefslogtreecommitdiff
path: root/doc/api.html
diff options
context:
space:
mode:
Diffstat (limited to 'doc/api.html')
-rw-r--r--doc/api.html203
1 files changed, 203 insertions, 0 deletions
diff --git a/doc/api.html b/doc/api.html
new file mode 100644
index 00000000..79788d95
--- /dev/null
+++ b/doc/api.html
@@ -0,0 +1,203 @@
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-2009, 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/download.html">Download <span class="ext">&raquo;</span></a>
38</li></ul>
39</div>
40<div id="main">
41<p>
42LuaJIT is fully upwards-compatible with Lua 5.1. It supports all
43<a href="http://www.lua.org/manual/5.1/manual.html#5"><span class="ext">&raquo;</span>&nbsp;standard Lua
44library functions</a> and the full set of
45<a href="http://www.lua.org/manual/5.1/manual.html#3"><span class="ext">&raquo;</span>&nbsp;Lua/C API
46functions</a>.
47</p>
48<p>
49LuaJIT is also fully ABI-compatible to Lua 5.1 at the linker/dynamic
50loader level. This means you can compile a C&nbsp;module against the
51standard Lua headers and load the same shared library from either Lua
52or LuaJIT.
53</p>
54
55<h2 id="bit"><tt>bit.*</tt> &mdash; Bitwise Operations</h2>
56<p>
57LuaJIT supports all bitwise operations as defined by
58<a href="http://bitop.luajit.org"><span class="ext">&raquo;</span>&nbsp;Lua BitOp</a>:
59</p>
60<pre class="code">
61bit.tobit bit.tohex bit.bnot bit.band bit.bor bit.bxor
62bit.lshift bit.rshift bit.arshift bit.rol bit.ror bit.bswap
63</pre>
64<p>
65This module is a LuaJIT built-in &mdash; you don't need to download or
66install Lua BitOp. The Lua BitOp site has full documentation for all
67<a href="http://bitop.luajit.org/api.html"><span class="ext">&raquo;</span>&nbsp;Lua BitOp API functions</a>.
68</p>
69<p>
70Please make sure to <tt>require</tt> the module before using any of
71its functions:
72</p>
73<pre class="code">
74local bit = require("bit")
75</pre>
76<p>
77An already installed Lua BitOp module is ignored by LuaJIT.
78This way you can use bit operations from both Lua and LuaJIT on a
79shared installation.
80</p>
81
82<h2 id="jit"><tt>jit.*</tt> &mdash; JIT compiler control</h2>
83<p>
84The functions in this built-in module control the behavior
85of the JIT compiler engine.
86</p>
87
88<h3 id="jit_onoff"><tt>jit.on()<br>
89jit.off()</tt></h3>
90<p>
91Turns the whole JIT compiler on (default) or off.
92</p>
93<p>
94These functions are typically used with the command line options
95<tt>-j on</tt> or <tt>-j off</tt>.
96</p>
97
98<h3 id="jit_flush"><tt>jit.flush()</tt></h3>
99<p>
100Flushes the whole cache of compiled code.
101</p>
102
103<h3 id="jit_flush_tr"><tt>jit.flush(tr)</tt></h3>
104<p>
105Flushes the code for the specified root trace and all of its
106side traces from the cache.
107</p>
108
109<h3 id="jit_onoff_func"><tt>jit.on(func|true [,true|false])<br>
110jit.off(func|true [,true|false])<br>
111jit.flush(func|true [,true|false])</tt></h3>
112<p>
113<tt>jit.on</tt> enables JIT compilation for a Lua function (this is
114the default).
115</p>
116<p>
117<tt>jit.off</tt> disables JIT compilation for a Lua function and
118flushes any already compiled code from the code cache.
119</p>
120<p>
121<tt>jit.flush</tt> flushes the code, but doesn't affect the
122enable/disable status.
123</p>
124<p>
125The current function, i.e. the Lua function calling this library
126function, can also be specified by passing <tt>true</tt> as the first
127argument.
128</p>
129<p>
130If the second argument is <tt>true</tt>, JIT compilation is also
131enabled, disabled or flushed recursively for all subfunctions of a
132function. With <tt>false</tt> only the subfunctions are affected.
133</p>
134<p>
135The <tt>jit.on</tt> and <tt>jit.off</tt> functions only set a flag
136which is checked when the function is about to be compiled. They do
137not trigger immediate compilation.
138</p>
139<p>
140Typical usage is <tt>jit.off(true, true)</tt> in the main chunk
141of a module to turn off JIT compilation for the whole module for
142debugging purposes.
143</p>
144
145<h3 id="jit_version"><tt>jit.version</tt></h3>
146<p>
147Contains the LuaJIT version string.
148</p>
149
150<h3 id="jit_version_num"><tt>jit.version_num</tt></h3>
151<p>
152Contains the version number of the LuaJIT core. Version xx.yy.zz
153is represented by the decimal number xxyyzz.
154</p>
155
156<h3 id="jit_arch"><tt>jit.arch</tt></h3>
157<p>
158Contains the target architecture name (CPU and optional ABI).
159</p>
160
161<h2 id="jit_opt"><tt>jit.opt.*</tt> &mdash; JIT compiler optimization control</h2>
162<p>
163This module provides the backend for the <tt>-O</tt> command line
164option.
165</p>
166<p>
167You can also use it programmatically, e.g.:
168</p>
169<pre class="code">
170jit.opt.start(2) -- same as -O2
171jit.opt.start("-dce")
172jit.opt.start("hotloop=10", "hotexit=2")
173</pre>
174<p>
175Unlike in LuaJIT 1.x, the module is built-in and
176<b>optimization is turned on by default!</b>
177It's no longer necessary to run <tt>require("jit.opt").start()</tt>,
178which was one of the ways to enable optimization.
179</p>
180
181<h2 id="jit_util"><tt>jit.util.*</tt> &mdash; JIT compiler introspection</h2>
182<p>
183This module holds functions to introspect the bytecode, generated
184traces, the IR and the generated machine code. The functionality
185provided by this module is still in flux and therefore undocumented.
186</p>
187<p>
188The debug modules <tt>-jbc</tt>, <tt>-jv</tt> and <tt>-jdump</tt> make
189extensive use of these functions. Please check out their source code,
190if you want to know more.
191</p>
192<br class="flush">
193</div>
194<div id="foot">
195<hr class="hide">
196Copyright &copy; 2005-2009 Mike Pall
197<span class="noprint">
198&middot;
199<a href="contact.html">Contact</a>
200</span>
201</div>
202</body>
203</html>
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2026-01-12 01:15:24 +0000