Mercurial

comparison third_party/luajit/doc/extensions.html @ 178:94705b5986b3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[ThirdParty] Added WRK and luajit for load testing.
author MrJuneJune <me@mrjunejune.com>
date Thu, 22 Jan 2026 20:10:30 -0800
parents
children
comparison
equal deleted inserted replaced
177:24fe8ff94056 178:94705b5986b3
1 <!DOCTYPE html>
2 <html>
3 <head>
4 <title>Extensions</title>
5 <meta charset="utf-8">
6 <meta name="Copyright" content="Copyright (C) 2005-2023">
7 <meta name="Language" content="en">
8 <link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
9 <link rel="stylesheet" type="text/css" href="bluequad-print.css" media="print">
10 <style type="text/css">
11 table.exc {
12 line-height: 1.2;
13 }
14 tr.exchead td {
15 font-weight: bold;
16 }
17 td.excplatform {
18 width: 48%;
19 }
20 td.exccompiler {
21 width: 29%;
22 }
23 td.excinterop {
24 width: 23%;
25 }
26 </style>
27 </head>
28 <body>
29 <div id="site">
30 <a href="https://luajit.org"><span>Lua<span id="logo">JIT</span></span></a>
31 </div>
32 <div id="head">
33 <h1>Extensions</h1>
34 </div>
35 <div id="nav">
36 <ul><li>
37 <a href="luajit.html">LuaJIT</a>
38 <ul><li>
39 <a href="https://luajit.org/download.html">Download <span class="ext">&raquo;</span></a>
40 </li><li>
41 <a href="install.html">Installation</a>
42 </li><li>
43 <a href="running.html">Running</a>
44 </li></ul>
45 </li><li>
46 <a class="current" href="extensions.html">Extensions</a>
47 <ul><li>
48 <a href="ext_ffi.html">FFI Library</a>
49 <ul><li>
50 <a href="ext_ffi_tutorial.html">FFI Tutorial</a>
51 </li><li>
52 <a href="ext_ffi_api.html">ffi.* API</a>
53 </li><li>
54 <a href="ext_ffi_semantics.html">FFI Semantics</a>
55 </li></ul>
56 </li><li>
57 <a href="ext_buffer.html">String Buffers</a>
58 </li><li>
59 <a href="ext_jit.html">jit.* Library</a>
60 </li><li>
61 <a href="ext_c_api.html">Lua/C API</a>
62 </li><li>
63 <a href="ext_profiler.html">Profiler</a>
64 </li></ul>
65 </li><li>
66 <a href="https://luajit.org/status.html">Status <span class="ext">&raquo;</span></a>
67 </li><li>
68 <a href="https://luajit.org/faq.html">FAQ <span class="ext">&raquo;</span></a>
69 </li><li>
70 <a href="https://luajit.org/list.html">Mailing List <span class="ext">&raquo;</span></a>
71 </li></ul>
72 </div>
73 <div id="main">
74
75 <p>
76 LuaJIT is fully upwards-compatible with Lua 5.1. It supports all
77 <a href="https://www.lua.org/manual/5.1/manual.html#5"><span class="ext">&raquo;</span>&nbsp;standard Lua
78 library functions</a> and the full set of
79 <a href="https://www.lua.org/manual/5.1/manual.html#3"><span class="ext">&raquo;</span>&nbsp;Lua/C API
80 functions</a>.
81 </p>
82 <p>
83 LuaJIT is also fully ABI-compatible to Lua 5.1 at the linker/dynamic
84 loader level. This means you can compile a C&nbsp;module against the
85 standard Lua headers and load the same shared library from either Lua
86 or LuaJIT.
87 </p>
88 <p>
89 LuaJIT extends the standard Lua VM with new functionality and adds
90 several extension modules. Please note, this page is only about
91 <em>functional</em> enhancements and not about performance enhancements,
92 such as the optimized VM, the faster interpreter or the JIT compiler.
93 </p>
94
95 <h2 id="modules">Extensions Modules</h2>
96 <p>
97 LuaJIT comes with several built-in extension modules:
98 </p>
99
100 <h3 id="bit"><tt>bit.*</tt> &mdash; Bitwise operations</h3>
101 <p>
102 LuaJIT supports all bitwise operations as defined by
103 <a href="https://bitop.luajit.org"><span class="ext">&raquo;</span>&nbsp;Lua BitOp</a>:
104 </p>
105 <pre class="code">
106 bit.tobit bit.tohex bit.bnot bit.band bit.bor bit.bxor
107 bit.lshift bit.rshift bit.arshift bit.rol bit.ror bit.bswap
108 </pre>
109 <p>
110 This module is a LuaJIT built-in &mdash; you don't need to download or
111 install Lua BitOp. The Lua BitOp site has full documentation for all
112 <a href="https://bitop.luajit.org/api.html"><span class="ext">&raquo;</span>&nbsp;Lua BitOp API functions</a>.
113 The FFI adds support for
114 <a href="ext_ffi_semantics.html#cdata_arith">64&nbsp;bit bitwise operations</a>,
115 using the same API functions.
116 </p>
117 <p>
118 Please make sure to <tt>require</tt> the module before using any of
119 its functions:
120 </p>
121 <pre class="code">
122 local bit = require("bit")
123 </pre>
124 <p>
125 An already installed Lua BitOp module is ignored by LuaJIT.
126 This way you can use bit operations from both Lua and LuaJIT on a
127 shared installation.
128 </p>
129
130 <h3 id="ffi"><tt>ffi.*</tt> &mdash; FFI library</h3>
131 <p>
132 The <a href="ext_ffi.html">FFI library</a> allows calling external
133 C&nbsp;functions and the use of C&nbsp;data structures from pure Lua
134 code.
135 </p>
136
137 <h3 id="jit"><tt>jit.*</tt> &mdash; JIT compiler control</h3>
138 <p>
139 The functions in this module
140 <a href="ext_jit.html">control the behavior of the JIT compiler engine</a>.
141 </p>
142
143 <h3 id="c_api">C API extensions</h3>
144 <p>
145 LuaJIT adds some
146 <a href="ext_c_api.html">extra functions to the Lua/C API</a>.
147 </p>
148
149 <h3 id="profiler">Profiler</h3>
150 <p>
151 LuaJIT has an <a href="ext_profiler.html">integrated profiler</a>.
152 </p>
153
154 <h2 id="library">Enhanced Standard Library Functions</h2>
155
156 <h3 id="xpcall"><tt>xpcall(f, err [,args...])</tt> passes arguments</h3>
157 <p>
158 Unlike the standard implementation in Lua 5.1, <tt>xpcall()</tt>
159 passes any arguments after the error function to the function
160 which is called in a protected context.
161 </p>
162
163 <h3 id="load"><tt>loadfile()</tt> etc. handle UTF-8 source code</h3>
164 <p>
165 Non-ASCII characters are handled transparently by the Lua source code parser.
166 This allows the use of UTF-8 characters in identifiers and strings.
167 A UTF-8 BOM is skipped at the start of the source code.
168 </p>
169
170 <h3 id="tostring"><tt>tostring()</tt> etc. canonicalize NaN and &plusmn;Inf</h3>
171 <p>
172 All number-to-string conversions consistently convert non-finite numbers
173 to the same strings on all platforms. NaN results in <tt>"nan"</tt>,
174 positive infinity results in <tt>"inf"</tt> and negative infinity results
175 in <tt>"-inf"</tt>.
176 </p>
177
178 <h3 id="tonumber"><tt>tonumber()</tt> etc. use builtin string to number conversion</h3>
179 <p>
180 All string-to-number conversions consistently convert integer and
181 floating-point inputs in decimal, hexadecimal and binary on all platforms.
182 <tt>strtod()</tt> is <em>not</em> used anymore, which avoids numerous
183 problems with poor C library implementations. The builtin conversion
184 function provides full precision according to the IEEE-754 standard, it
185 works independently of the current locale and it supports hex floating-point
186 numbers (e.g. <tt>0x1.5p-3</tt>).
187 </p>
188
189 <h3 id="string_dump"><tt>string.dump(f [,strip])</tt> generates portable bytecode</h3>
190 <p>
191 An extra argument has been added to <tt>string.dump()</tt>. If set to
192 <tt>true</tt>, 'stripped' bytecode without debug information is
193 generated. This speeds up later bytecode loading and reduces memory
194 usage. See also the
195 <a href="running.html#opt_b"><tt>-b</tt> command line option</a>.
196 </p>
197 <p>
198 The generated bytecode is portable and can be loaded on any architecture
199 that LuaJIT supports, independent of word size or endianess. However, the
200 bytecode compatibility versions must match. Bytecode stays compatible
201 for dot releases (x.y.0 &rarr; x.y.1), but may change with major or
202 minor releases (2.0 &rarr; 2.1) or between any beta release. Foreign
203 bytecode (e.g. from Lua 5.1) is incompatible and cannot be loaded.
204 </p>
205 <p>
206 Note: <tt>LJ_GC64</tt> mode requires a different frame layout, which implies
207 a different, incompatible bytecode format for all 64 bit ports. This may be
208 rectified in the future.
209 </p>
210
211 <h3 id="table_new"><tt>table.new(narray, nhash)</tt> allocates a pre-sized table</h3>
212 <p>
213 An extra library function <tt>table.new()</tt> can be made available via
214 <tt>require("table.new")</tt>. This creates a pre-sized table, just like
215 the C API equivalent <tt>lua_createtable()</tt>. This is useful for big
216 tables if the final table size is known and automatic table resizing is
217 too expensive.
218 </p>
219
220 <h3 id="table_clear"><tt>table.clear(tab)</tt> clears a table</h3>
221 <p>
222 An extra library function <tt>table.clear()</tt> can be made available
223 via <tt>require("table.clear")</tt>. This clears all keys and values
224 from a table, but preserves the allocated array/hash sizes. This is
225 useful when a table, which is linked from multiple places, needs to be
226 cleared and/or when recycling a table for use by the same context. This
227 avoids managing backlinks, saves an allocation and the overhead of
228 incremental array/hash part growth.
229 </p>
230 <p>
231 Please note, this function is meant for very specific situations. In most
232 cases it's better to replace the (usually single) link with a new table
233 and let the GC do its work.
234 </p>
235
236 <h3 id="math_random">Enhanced PRNG for <tt>math.random()</tt></h3>
237 <p>
238 LuaJIT uses a Tausworthe PRNG with period 2^223 to implement
239 <tt>math.random()</tt> and <tt>math.randomseed()</tt>. The quality of
240 the PRNG results is much superior compared to the standard Lua
241 implementation, which uses the platform-specific ANSI rand().
242 </p>
243 <p>
244 The PRNG generates the same sequences from the same seeds on all
245 platforms and makes use of all bits in the seed argument.
246 <tt>math.random()</tt> without arguments generates 52 pseudo-random bits
247 for every call. The result is uniformly distributed between 0.0 and 1.0.
248 It's correctly scaled up and rounded for <tt>math.random(n&nbsp;[,m])</tt> to
249 preserve uniformity.
250 </p>
251 <p>
252 Important: Neither this nor any other PRNG based on the simplistic
253 <tt>math.random()</tt> API is suitable for cryptographic use.
254 </p>
255
256 <h3 id="io"><tt>io.*</tt> functions handle 64&nbsp;bit file offsets</h3>
257 <p>
258 The file I/O functions in the standard <tt>io.*</tt> library handle
259 64&nbsp;bit file offsets. In particular, this means it's possible
260 to open files larger than 2&nbsp;Gigabytes and to reposition or obtain
261 the current file position for offsets beyond 2&nbsp;GB
262 (<tt>fp:seek()</tt> method).
263 </p>
264
265 <h3 id="debug_meta"><tt>debug.*</tt> functions identify metamethods</h3>
266 <p>
267 <tt>debug.getinfo()</tt> and <tt>lua_getinfo()</tt> also return information
268 about invoked metamethods. The <tt>namewhat</tt> field is set to
269 <tt>"metamethod"</tt> and the <tt>name</tt> field has the name of
270 the corresponding metamethod (e.g. <tt>"__index"</tt>).
271 </p>
272
273 <h2 id="resumable">Fully Resumable VM</h2>
274 <p>
275 The LuaJIT VM is fully resumable. This means you can yield from a
276 coroutine even across contexts, where this would not possible with
277 the standard Lua&nbsp;5.1 VM: e.g. you can yield across <tt>pcall()</tt>
278 and <tt>xpcall()</tt>, across iterators and across metamethods.
279 </p>
280
281 <h2 id="lua52">Extensions from Lua 5.2</h2>
282 <p>
283 LuaJIT supports some language and library extensions from Lua&nbsp;5.2.
284 Features that are unlikely to break existing code are unconditionally
285 enabled:
286 </p>
287 <ul>
288 <li><tt>goto</tt> and <tt>::labels::</tt>.</li>
289 <li>Hex escapes <tt>'\x3F'</tt> and <tt>'\*'</tt> escape in strings.</li>
290 <li><tt>load(string|reader [, chunkname [,mode [,env]]])</tt>.</li>
291 <li><tt>loadstring()</tt> is an alias for <tt>load()</tt>.</li>
292 <li><tt>loadfile(filename [,mode [,env]])</tt>.</li>
293 <li><tt>math.log(x [,base])</tt>.</li>
294 <li><tt>string.rep(s, n [,sep])</tt>.</li>
295 <li><tt>string.format()</tt>: <tt>%q</tt> reversible.
296 <tt>%s</tt> checks <tt>__tostring</tt>.
297 <tt>%a</tt> and <tt>"%A</tt> added.</li>
298 <li>String matching pattern <tt>%g</tt> added.</li>
299 <li><tt>io.read("*L")</tt>.</li>
300 <li><tt>io.lines()</tt> and <tt>file:lines()</tt> process
301 <tt>io.read()</tt> options.</li>
302 <li><tt>os.exit(status|true|false [,close])</tt>.</li>
303 <li><tt>package.searchpath(name, path [, sep [, rep]])</tt>.</li>
304 <li><tt>package.loadlib(name, "*")</tt>.</li>
305 <li><tt>debug.getinfo()</tt> returns <tt>nparams</tt> and <tt>isvararg</tt>
306 for option <tt>"u"</tt>.</li>
307 <li><tt>debug.getlocal()</tt> accepts function instead of level.</li>
308 <li><tt>debug.getlocal()</tt> and <tt>debug.setlocal()</tt> accept negative
309 indexes for varargs.</li>
310 <li><tt>debug.getupvalue()</tt> and <tt>debug.setupvalue()</tt> handle
311 C&nbsp;functions.</li>
312 <li><tt>debug.upvalueid()</tt> and <tt>debug.upvaluejoin()</tt>.</li>
313 <li>Lua/C API extensions:
314 <tt>lua_version()</tt>
315 <tt>lua_upvalueid()</tt>
316 <tt>lua_upvaluejoin()</tt>
317 <tt>lua_loadx()</tt>
318 <tt>lua_copy()</tt>
319 <tt>lua_tonumberx()</tt>
320 <tt>lua_tointegerx()</tt>
321 <tt>luaL_fileresult()</tt>
322 <tt>luaL_execresult()</tt>
323 <tt>luaL_loadfilex()</tt>
324 <tt>luaL_loadbufferx()</tt>
325 <tt>luaL_traceback()</tt>
326 <tt>luaL_setfuncs()</tt>
327 <tt>luaL_pushmodule()</tt>
328 <tt>luaL_newlibtable()</tt>
329 <tt>luaL_newlib()</tt>
330 <tt>luaL_testudata()</tt>
331 <tt>luaL_setmetatable()</tt>
332 </li>
333 <li>Command line option <tt>-E</tt>.</li>
334 <li>Command line checks <tt>__tostring</tt> for errors.</li>
335 </ul>
336 <p>
337 Other features are only enabled, if LuaJIT is built with
338 <tt>-DLUAJIT_ENABLE_LUA52COMPAT</tt>:
339 </p>
340 <ul>
341 <li><tt>goto</tt> is a keyword and not a valid variable name anymore.</li>
342 <li><tt>break</tt> can be placed anywhere. Empty statements (<tt>;;</tt>)
343 are allowed.</li>
344 <li><tt>__lt</tt>, <tt>__le</tt> are invoked for mixed types.</li>
345 <li><tt>__len</tt> for tables. <tt>rawlen()</tt> library function.</li>
346 <li><tt>pairs()</tt> and <tt>ipairs()</tt> check for <tt>__pairs</tt> and
347 <tt>__ipairs</tt>.</li>
348 <li><tt>coroutine.running()</tt> returns two results.</li>
349 <li><tt>table.pack()</tt> and <tt>table.unpack()</tt>
350 (same as <tt>unpack()</tt>).</li>
351 <li><tt>io.write()</tt> and <tt>file:write()</tt> return file handle
352 instead of <tt>true</tt>.</li>
353 <li><tt>os.execute()</tt> and <tt>pipe:close()</tt> return detailed
354 exit status.</li>
355 <li><tt>debug.setmetatable()</tt> returns object.</li>
356 <li><tt>debug.getuservalue()</tt> and <tt>debug.setuservalue()</tt>.</li>
357 <li>Remove <tt>math.mod()</tt>, <tt>string.gfind()</tt>.</li>
358 <li><tt>package.searchers</tt>.</li>
359 <li><tt>module()</tt> returns the module table.</li>
360 </ul>
361 <p>
362 Note: this provides only partial compatibility with Lua 5.2 at the
363 language and Lua library level. LuaJIT is API+ABI-compatible with
364 Lua&nbsp;5.1, which prevents implementing features that would otherwise
365 break the Lua/C API and ABI (e.g. <tt>_ENV</tt>).
366 </p>
367
368 <h2 id="lua53">Extensions from Lua 5.3</h2>
369 <p>
370 LuaJIT supports some extensions from Lua&nbsp;5.3:
371 <ul>
372 <li>Unicode escape <tt>'\u{XX...}'</tt> embeds the UTF-8 encoding in string literals.</li>
373 <li>The argument table <tt>arg</tt> can be read (and modified) by <tt>LUA_INIT</tt> and <tt>-e</tt> chunks.</li>
374 <li><tt>io.read()</tt> and <tt>file:read()</tt> accept formats with or without a leading <tt>*</tt>.</li>
375 <li><tt>assert()</tt> accepts any type of error object.</li>
376 <li><tt>table.move(a1, f, e, t [,a2])</tt>.</li>
377 <li><tt>coroutine.isyieldable()</tt>.</li>
378 <li>Lua/C API extensions:
379 <tt>lua_isyieldable()</tt>
380 </li>
381 </ul>
382
383 <h2 id="exceptions">C++ Exception Interoperability</h2>
384 <p>
385 LuaJIT has built-in support for interoperating with C++&nbsp;exceptions.
386 The available range of features depends on the target platform and
387 the toolchain used to compile LuaJIT:
388 </p>
389 <table class="exc">
390 <tr class="exchead">
391 <td class="excplatform">Platform</td>
392 <td class="exccompiler">Compiler</td>
393 <td class="excinterop">Interoperability</td>
394 </tr>
395 <tr class="odd separate">
396 <td class="excplatform">External frame unwinding</td>
397 <td class="exccompiler">GCC, Clang, MSVC</td>
398 <td class="excinterop"><b style="color: #00a000;">Full</b></td>
399 </tr>
400 <tr class="even">
401 <td class="excplatform">Internal frame unwinding + DWARF2</td>
402 <td class="exccompiler">GCC, Clang</td>
403 <td class="excinterop"><b style="color: #c06000;">Limited</b></td>
404 </tr>
405 <tr class="odd">
406 <td class="excplatform">Windows 64 bit</td>
407 <td class="exccompiler">non-MSVC</td>
408 <td class="excinterop"><b style="color: #c06000;">Limited</b></td>
409 </tr>
410 <tr class="even">
411 <td class="excplatform">Other platforms</td>
412 <td class="exccompiler">Other compilers</td>
413 <td class="excinterop"><b style="color: #a00000;">No</b></td>
414 </tr>
415 </table>
416 <p>
417 <b style="color: #00a000;">Full interoperability</b> means:
418 </p>
419 <ul>
420 <li>C++&nbsp;exceptions can be caught on the Lua side with <tt>pcall()</tt>,
421 <tt>lua_pcall()</tt> etc.</li>
422 <li>C++&nbsp;exceptions will be converted to the generic Lua error
423 <tt>"C++&nbsp;exception"</tt>, unless you use the
424 <a href="ext_c_api.html#mode_wrapcfunc">C&nbsp;call wrapper</a> feature.</li>
425 <li>It's safe to throw C++&nbsp;exceptions across non-protected Lua frames
426 on the C&nbsp;stack. The contents of the C++&nbsp;exception object
427 pass through unmodified.</li>
428 <li>Lua errors can be caught on the C++ side with <tt>catch(...)</tt>.
429 The corresponding Lua error message can be retrieved from the Lua stack.<br>
430 For MSVC for Windows 64 bit this requires compilation of your C++ code
431 with <tt>/EHa</tt>.</li>
432 <li>Throwing Lua errors across C++ frames is safe. C++ destructors
433 will be called.</li>
434 </ul>
435 <p>
436 <b style="color: #c06000;">Limited interoperability</b> means:
437 </p>
438 <ul>
439 <li>C++&nbsp;exceptions can be caught on the Lua side with <tt>pcall()</tt>,
440 <tt>lua_pcall()</tt> etc.</li>
441 <li>C++&nbsp;exceptions will be converted to the generic Lua error
442 <tt>"C++&nbsp;exception"</tt>, unless you use the
443 <a href="ext_c_api.html#mode_wrapcfunc">C&nbsp;call wrapper</a> feature.</li>
444 <li>C++&nbsp;exceptions will be caught by non-protected Lua frames and
445 are rethrown as a generic Lua error. The C++&nbsp;exception object will
446 be destroyed.</li>
447 <li>Lua errors <b>cannot</b> be caught on the C++ side.</li>
448 <li>Throwing Lua errors across C++ frames will <b>not</b> call
449 C++ destructors.</li>
450 </ul>
451
452 <p>
453 <b style="color: #a00000;">No interoperability</b> means:
454 </p>
455 <ul>
456 <li>It's <b>not</b> safe to throw C++&nbsp;exceptions across Lua frames.</li>
457 <li>C++&nbsp;exceptions <b>cannot</b> be caught on the Lua side.</li>
458 <li>Lua errors <b>cannot</b> be caught on the C++ side.</li>
459 <li>Throwing Lua errors across C++ frames will <b>not</b> call
460 C++ destructors.</li>
461 </ul>
462 <br class="flush">
463 </div>
464 <div id="foot">
465 <hr class="hide">
466 Copyright &copy; 2005-2023
467 <span class="noprint">
468 &middot;
469 <a href="contact.html">Contact</a>
470 </span>
471 </div>
472 </body>
473 </html>