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. -

-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. -

- -

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 and hexadecimal 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. -

- -

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. -

- -

`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().
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().

-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). -

- -

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
POSIX/x64, DWARF2 unwinding	GCC 4.3+	Full
Other platforms, DWARF2 unwinding	GCC	Limited
Windows/x64	MSVC or WinSDK	Full
Windows/x86	Any	No
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.
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.
Additionally, on Windows/x86 with SEH-based C++ exceptions: -it's not safe to throw a Lua error across any frames containing -a C++ function with any try/catch construct or using variables with -(implicit) destructors. This also applies to any functions which may be -inlined in such a function. It doesn't matter whether lua_error() -is called inside or outside of a try/catch or whether any object actually -needs to be destroyed: the SEH chain is corrupted and this will eventually -lead to the termination of the process.

-
-

Extensions

Extensions Modules

bit.* — Bitwise operations

ffi.* — FFI library

jit.* — JIT compiler control

C API extensions

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

Enhanced PRNG for math.random()

io.* functions handle 64 bit file offsets

debug.* functions identify metamethods