Extensions

+LuaJIT is fully upwards-compatible with Lua 5.1. It supports all +» standard Lua +library functions and the full set of +» Lua/C API +functions. +

+LuaJIT is also fully ABI-compatible to Lua 5.1 at the linker/dynamic +loader level. This means you can compile a C module against the +standard Lua headers and load the same shared library from either Lua +or LuaJIT. +

+LuaJIT extends the standard Lua VM with new functionality and adds +several extension modules. Please note, this page is only about +functional enhancements and not about performance enhancements, +such as the optimized VM, the faster interpreter or the JIT compiler. +

+ +

Extensions Modules

+LuaJIT comes with several built-in extension modules: +

+ +

`bit.*` — Bitwise operations

+LuaJIT supports all bitwise operations as defined by +» Lua BitOp: +

+bit.tobit  bit.tohex  bit.bnot    bit.band bit.bor  bit.bxor
+bit.lshift bit.rshift bit.arshift bit.rol  bit.ror  bit.bswap
+

+This module is a LuaJIT built-in — you don't need to download or +install Lua BitOp. The Lua BitOp site has full documentation for all +» Lua BitOp API functions. +The FFI adds support for +64 bit bitwise operations, +using the same API functions. +

+Please make sure to require the module before using any of +its functions: +

+local bit = require("bit")
+

+An already installed Lua BitOp module is ignored by LuaJIT. +This way you can use bit operations from both Lua and LuaJIT on a +shared installation. +

+ +

`ffi.*` — FFI library

+The FFI library allows calling external +C functions and the use of C data structures from pure Lua +code. +

+ +

`jit.*` — JIT compiler control

+The functions in this module +control the behavior of the JIT compiler engine. +

+ +

C API extensions

+LuaJIT adds some +extra functions to the Lua/C API. +

+ +

Profiler

+LuaJIT has an integrated profiler. +

+ +

Enhanced Standard Library Functions

+ +

`xpcall(f, err [,args...])` passes arguments

+Unlike the standard implementation in Lua 5.1, xpcall() +passes any arguments after the error function to the function +which is called in a protected context. +

+ +

`loadfile()` etc. handle UTF-8 source code

+Non-ASCII characters are handled transparently by the Lua source code parser. +This allows the use of UTF-8 characters in identifiers and strings. +A UTF-8 BOM is skipped at the start of the source code. +

+ +

`tostring()` etc. canonicalize NaN and ±Inf

+All number-to-string conversions consistently convert non-finite numbers +to the same strings on all platforms. NaN results in "nan", +positive infinity results in "inf" and negative infinity results +in "-inf". +

+ +

`tonumber()` etc. use builtin string to number conversion

+All string-to-number conversions consistently convert integer and +floating-point inputs in decimal, hexadecimal and binary on all platforms. +strtod() is not used anymore, which avoids numerous +problems with poor C library implementations. The builtin conversion +function provides full precision according to the IEEE-754 standard, it +works independently of the current locale and it supports hex floating-point +numbers (e.g. 0x1.5p-3). +

+ +

`string.dump(f [,strip])` generates portable bytecode

+An extra argument has been added to string.dump(). If set to +true, 'stripped' bytecode without debug information is +generated. This speeds up later bytecode loading and reduces memory +usage. See also the +-b command line option. +

+The generated bytecode is portable and can be loaded on any architecture +that LuaJIT supports, independent of word size or endianess. However, the +bytecode compatibility versions must match. Bytecode stays compatible +for dot releases (x.y.0 → x.y.1), but may change with major or +minor releases (2.0 → 2.1) or between any beta release. Foreign +bytecode (e.g. from Lua 5.1) is incompatible and cannot be loaded. +

+Note: LJ_GC64 mode requires a different frame layout, which implies +a different, incompatible bytecode format for all 64 bit ports. This may be +rectified in the future. +

+ +

`table.new(narray, nhash)` allocates a pre-sized table

+An extra library function table.new() can be made available via +require("table.new"). This creates a pre-sized table, just like +the C API equivalent lua_createtable(). This is useful for big +tables if the final table size is known and automatic table resizing is +too expensive. +

+ +

`table.clear(tab)` clears a table

+An extra library function table.clear() can be made available +via require("table.clear"). This clears all keys and values +from a table, but preserves the allocated array/hash sizes. This is +useful when a table, which is linked from multiple places, needs to be +cleared and/or when recycling a table for use by the same context. This +avoids managing backlinks, saves an allocation and the overhead of +incremental array/hash part growth. +

+Please note, this function is meant for very specific situations. In most +cases it's better to replace the (usually single) link with a new table +and let the GC do its work. +

+ +

Enhanced PRNG for `math.random()`

+LuaJIT uses a Tausworthe PRNG with period 2^223 to implement +math.random() and math.randomseed(). The quality of +the PRNG results is much superior compared to the standard Lua +implementation, which uses the platform-specific ANSI rand(). +

+The PRNG generates the same sequences from the same seeds on all +platforms and makes use of all bits in the seed argument. +math.random() without arguments generates 52 pseudo-random bits +for every call. The result is uniformly distributed between 0.0 and 1.0. +It's correctly scaled up and rounded for math.random(n [,m]) to +preserve uniformity. +

+Important: Neither this nor any other PRNG based on the simplistic +math.random() API is suitable for cryptographic use. +

+ +

`io.*` functions handle 64 bit file offsets

+The file I/O functions in the standard io.* library handle +64 bit file offsets. In particular, this means it's possible +to open files larger than 2 Gigabytes and to reposition or obtain +the current file position for offsets beyond 2 GB +(fp:seek() method). +

+ +

`debug.*` functions identify metamethods

+debug.getinfo() and lua_getinfo() also return information +about invoked metamethods. The namewhat field is set to +"metamethod" and the name field has the name of +the corresponding metamethod (e.g. "__index"). +

+ +

Fully Resumable VM

+The LuaJIT VM is fully resumable. This means you can yield from a +coroutine even across contexts, where this would not possible with +the standard Lua 5.1 VM: e.g. you can yield across pcall() +and xpcall(), across iterators and across metamethods. +

+ +

Extensions from Lua 5.2

+LuaJIT supports some language and library extensions from Lua 5.2. +Features that are unlikely to break existing code are unconditionally +enabled: +

goto and ::labels::.
Hex escapes '\x3F' and '\*' escape in strings.
load(string|reader [, chunkname [,mode [,env]]]).
loadstring() is an alias for load().
loadfile(filename [,mode [,env]]).
math.log(x [,base]).
string.rep(s, n [,sep]).
string.format(): %q reversible. +%s checks __tostring. +%a and "%A added.
String matching pattern %g added.
io.read("*L").
io.lines() and file:lines() process +io.read() options.
os.exit(status|true|false [,close]).
package.searchpath(name, path [, sep [, rep]]).
package.loadlib(name, "*").
debug.getinfo() returns nparams and isvararg +for option "u".
debug.getlocal() accepts function instead of level.
debug.getlocal() and debug.setlocal() accept negative +indexes for varargs.
debug.getupvalue() and debug.setupvalue() handle +C functions.
debug.upvalueid() and debug.upvaluejoin().
Lua/C API extensions: +lua_version() +lua_upvalueid() +lua_upvaluejoin() +lua_loadx() +lua_copy() +lua_tonumberx() +lua_tointegerx() +luaL_fileresult() +luaL_execresult() +luaL_loadfilex() +luaL_loadbufferx() +luaL_traceback() +luaL_setfuncs() +luaL_pushmodule() +luaL_newlibtable() +luaL_newlib() +luaL_testudata() +luaL_setmetatable() +
Command line option -E.
Command line checks __tostring for errors.

+Other features are only enabled, if LuaJIT is built with +-DLUAJIT_ENABLE_LUA52COMPAT: +

goto is a keyword and not a valid variable name anymore.
break can be placed anywhere. Empty statements (;;) +are allowed.
__lt, __le are invoked for mixed types.
__len for tables. rawlen() library function.
pairs() and ipairs() check for __pairs and +__ipairs.
coroutine.running() returns two results.
table.pack() and table.unpack() +(same as unpack()).
io.write() and file:write() return file handle +instead of true.
os.execute() and pipe:close() return detailed +exit status.
debug.setmetatable() returns object.
debug.getuservalue() and debug.setuservalue().
Remove math.mod(), string.gfind().
package.searchers.
module() returns the module table.

+Note: this provides only partial compatibility with Lua 5.2 at the +language and Lua library level. LuaJIT is API+ABI-compatible with +Lua 5.1, which prevents implementing features that would otherwise +break the Lua/C API and ABI (e.g. _ENV). +

+ +

Extensions from Lua 5.3

+LuaJIT supports some extensions from Lua 5.3: +

Unicode escape '\u{XX...}' embeds the UTF-8 encoding in string literals.
The argument table arg can be read (and modified) by LUA_INIT and -e chunks.
io.read() and file:read() accept formats with or without a leading *.
assert() accepts any type of error object.
table.move(a1, f, e, t [,a2]).
coroutine.isyieldable().
Lua/C API extensions: +lua_isyieldable() +

+ +

C++ Exception Interoperability

+LuaJIT has built-in support for interoperating with C++ exceptions. +The available range of features depends on the target platform and +the toolchain used to compile LuaJIT: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + +

Platform	Compiler	Interoperability
External frame unwinding	GCC, Clang, MSVC	Full
Internal frame unwinding + DWARF2	GCC, Clang	Limited
Windows 64 bit	non-MSVC	Limited
Other platforms	Other compilers	No

+Full interoperability means: +

C++ exceptions can be caught on the Lua side with pcall(), +lua_pcall() etc.
C++ exceptions will be converted to the generic Lua error +"C++ exception", unless you use the +C call wrapper feature.
It's safe to throw C++ exceptions across non-protected Lua frames +on the C stack. The contents of the C++ exception object +pass through unmodified.
Lua errors can be caught on the C++ side with catch(...). +The corresponding Lua error message can be retrieved from the Lua stack.
+For MSVC for Windows 64 bit this requires compilation of your C++ code +with /EHa.
Throwing Lua errors across C++ frames is safe. C++ destructors +will be called.

+Limited interoperability means: +

C++ exceptions can be caught on the Lua side with pcall(), +lua_pcall() etc.
C++ exceptions will be converted to the generic Lua error +"C++ exception", unless you use the +C call wrapper feature.
C++ exceptions will be caught by non-protected Lua frames and +are rethrown as a generic Lua error. The C++ exception object will +be destroyed.
Lua errors cannot be caught on the C++ side.
Throwing Lua errors across C++ frames will not call +C++ destructors.

+ +

+No interoperability means: +

It's not safe to throw C++ exceptions across Lua frames.
C++ exceptions cannot be caught on the Lua side.
Lua errors cannot be caught on the C++ side.
Throwing Lua errors across C++ frames will not call +C++ destructors.

+
+

Extensions

Extensions Modules

bit.* — Bitwise operations

ffi.* — FFI library

jit.* — JIT compiler control

C API extensions

Profiler

Enhanced Standard Library Functions

xpcall(f, err [,args...]) passes arguments

loadfile() etc. handle UTF-8 source code

tostring() etc. canonicalize NaN and ±Inf

tonumber() etc. use builtin string to number conversion

string.dump(f [,strip]) generates portable bytecode

table.new(narray, nhash) allocates a pre-sized table

table.clear(tab) clears a table

Enhanced PRNG for math.random()

io.* functions handle 64 bit file offsets

debug.* functions identify metamethods