doc/extensions.html

   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.</li>
 430 <li>Throwing Lua errors across C++ frames is safe. C++ destructors
 431 will be called.</li>
 432 </ul>
 433 <p>
 434 <b style="color: #c06000;">Limited interoperability</b> means:
 435 </p>
 436 <ul>
 437 <li>C++&nbsp;exceptions can be caught on the Lua side with <tt>pcall()</tt>,
 438 <tt>lua_pcall()</tt> etc.</li>
 439 <li>C++&nbsp;exceptions will be converted to the generic Lua error
 440 <tt>"C++&nbsp;exception"</tt>, unless you use the
 441 <a href="ext_c_api.html#mode_wrapcfunc">C&nbsp;call wrapper</a> feature.</li>
 442 <li>C++&nbsp;exceptions will be caught by non-protected Lua frames and
 443 are rethrown as a generic Lua error. The C++&nbsp;exception object will
 444 be destroyed.</li>
 445 <li>Lua errors <b>cannot</b> be caught on the C++ side.</li>
 446 <li>Throwing Lua errors across C++ frames will <b>not</b> call
 447 C++ destructors.</li>
 448 </ul>
 449
 450 <p>
 451 <b style="color: #a00000;">No interoperability</b> means:
 452 </p>
 453 <ul>
 454 <li>It's <b>not</b> safe to throw C++&nbsp;exceptions across Lua frames.</li>
 455 <li>C++&nbsp;exceptions <b>cannot</b> be caught on the Lua side.</li>
 456 <li>Lua errors <b>cannot</b> be caught on the C++ side.</li>
 457 <li>Throwing Lua errors across C++ frames will <b>not</b> call
 458 C++ destructors.</li>
 459 </ul>
 460 <br class="flush">
 461 </div>
 462 <div id="foot">
 463 <hr class="hide">
 464 Copyright &copy; 2005-2023
 465 <span class="noprint">
 466 &middot;
 467 <a href="contact.html">Contact</a>
 468 </span>
 469 </div>
 470 </body>
 471 </html>