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

- -

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

- -

`jit.*` — JIT compiler control

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

- -

`jit.on() -jit.off()`

-Turns the whole JIT compiler on (default) or off. -

-These functions are typically used with the command line options --j on or -j off. -

- -

`jit.flush()`

-Flushes the whole cache of compiled code. -

- -

`jit.on(func|true [,true|false]) -jit.off(func|true [,true|false]) -jit.flush(func|true [,true|false])`

-jit.on enables JIT compilation for a Lua function (this is -the default). -

-jit.off disables JIT compilation for a Lua function and -flushes any already compiled code from the code cache. -

-jit.flush flushes the code, but doesn't affect the -enable/disable status. -

-The current function, i.e. the Lua function calling this library -function, can also be specified by passing true as the first -argument. -

-If the second argument is true, JIT compilation is also -enabled, disabled or flushed recursively for all sub-functions of a -function. With false only the sub-functions are affected. -

-The jit.on and jit.off functions only set a flag -which is checked when the function is about to be compiled. They do -not trigger immediate compilation. -

-Typical usage is jit.off(true, true) in the main chunk -of a module to turn off JIT compilation for the whole module for -debugging purposes. -

- -

`jit.flush(tr)`

-Flushes the specified root trace and all of its side traces from the cache. -The code for the trace will be retained as long as there are any other -traces which link to it. -

- -

`status, ... = jit.status()`

-Returns the current status of the JIT compiler. The first result is -either true or false if the JIT compiler is turned -on or off. The remaining results are strings for CPU-specific features -and enabled optimizations. -

- -

`jit.version`

-Contains the LuaJIT version string. -

- -

`jit.version_num`

-Contains the version number of the LuaJIT core. Version xx.yy.zz -is represented by the decimal number xxyyzz. -

- -

`jit.arch`

-Contains the target architecture name (CPU and optional ABI). -

- -

`jit.opt.*` — JIT compiler optimization control

-This module provides the backend for the -O command line -option. -

-You can also use it programmatically, e.g.: -

-jit.opt.start(2) -- same as -O2
-jit.opt.start("-dce")
-jit.opt.start("hotloop=10", "hotexit=2")
-

-Unlike in LuaJIT 1.x, the module is built-in and -optimization is turned on by default! -It's no longer necessary to run require("jit.opt").start(), -which was one of the ways to enable optimization. -

- -

`jit.util.*` — JIT compiler introspection

-This module holds functions to introspect the bytecode, generated -traces, the IR and the generated machine code. The functionality -provided by this module is still in flux and therefore undocumented. -

-The debug modules -jbc, -jv and -jdump make -extensive use of these functions. Please check out their source code, -if you want to know more. -

- -

C API extensions

-LuaJIT adds some extensions to the Lua/C API. The LuaJIT include -directory must be in the compiler search path (-Ipath) -to be able to include the required header for C code: -

-#include "luajit.h"
-

-Or for C++ code: -

-#include "lua.hpp"
-

- -

`luaJIT_setmode(L, idx, mode)` -— Control VM

-This is a C API extension to allow control of the VM from C code. The -full prototype of LuaJIT_setmode is: -

-LUA_API int luaJIT_setmode(lua_State *L, int idx, int mode);
-

-The returned status is either success (1) or failure (0). -The second argument is either 0 or a stack index (similar to the -other Lua/C API functions). -

-The third argument specifies the mode, which is 'or'ed with a flag. -The flag can be LUAJIT_MODE_OFF to turn a feature on, -LUAJIT_MODE_ON to turn a feature off, or -LUAJIT_MODE_FLUSH to flush cached code. -

-The following modes are defined: -

- -

`luaJIT_setmode(L, 0, LUAJIT_MODE_ENGINE|flag)`

-Turn the whole JIT compiler on or off or flush the whole cache of compiled code. -

- -

`luaJIT_setmode(L, idx, LUAJIT_MODE_FUNC|flag)`
-`luaJIT_setmode(L, idx, LUAJIT_MODE_ALLFUNC|flag)`
-`luaJIT_setmode(L, idx, LUAJIT_MODE_ALLSUBFUNC|flag)`

-This sets the mode for the function at the stack index idx or -the parent of the calling function (idx = 0). It either -enables JIT compilation for a function, disables it and flushes any -already compiled code or only flushes already compiled code. This -applies recursively to all sub-functions of the function with -LUAJIT_MODE_ALLFUNC or only to the sub-functions with -LUAJIT_MODE_ALLSUBFUNC. -

- -

`luaJIT_setmode(L, trace, - LUAJIT_MODE_TRACE|LUAJIT_MODE_FLUSH)`

-Flushes the specified root trace and all of its side traces from the cache. -The code for the trace will be retained as long as there are any other -traces which link to it. -

- -

`luaJIT_setmode(L, idx, LUAJIT_MODE_WRAPCFUNC|flag)`

-This mode defines a wrapper function for calls to C functions. If -called with LUAJIT_MODE_ON, the stack index at idx -must be a lightuserdata object holding a pointer to the wrapper -function. From now on all C functions are called through the wrapper -function. If called with LUAJIT_MODE_OFF this mode is turned -off and all C functions are directly called. -

-The wrapper function can be used for debugging purposes or to catch -and convert foreign exceptions. Recommended usage can be seen in this -C++ code excerpt: -

-#include <exception>
-#include "lua.hpp"
-
-// Catch C++ exceptions and convert them to Lua error messages.
-// Customize as needed for your own exception classes.
-static int wrap_exceptions(lua_State *L, lua_CFunction f)
-{
-  try {
-    return f(L);  // Call wrapped function and return result.
-  } catch (const char *s) {  // Catch and convert exceptions.
-    lua_pushstring(L, s);
-  } catch (std::exception& e) {
-    lua_pushstring(L, e.what());
-  } catch (...) {
-    lua_pushliteral(L, "caught (...)");
-  }
-  return lua_error(L);  // Rethrow as a Lua error.
-}
-
-static int myinit(lua_State *L)
-{
-  ...
-  // Define wrapper function and enable it.
-  lua_pushlightuserdata(L, (void *)wrap_exceptions);
-  luaJIT_setmode(L, -1, LUAJIT_MODE_WRAPCFUNC|LUAJIT_MODE_ON);
-  lua_pop(L, 1);
-  ...
-}
-

-Note that you can only define a single global wrapper function, -so be careful when using this mechanism from multiple C++ modules. -Also note that this mechanism is not without overhead. -

-LuaJIT already intercepts exception handling for systems using DWARF2 -stack unwinding (e.g. Linux or OSX) and for Windows/x64 (but not -for Windows/x86). This is a zero-cost mechanism and always enabled. -You don't need to use any wrapper functions, except when you want to get -a more specific error message than "C++ exception". -

-
-

API Extensions

bit.* — Bitwise Operations

jit.* — JIT compiler control

jit.on() -jit.off()

jit.flush()

jit.on(func|true [,true|false]) -jit.off(func|true [,true|false]) -jit.flush(func|true [,true|false])

jit.flush(tr)

status, ... = jit.status()

jit.version

jit.version_num

jit.arch

jit.opt.* — JIT compiler optimization control

jit.util.* — JIT compiler introspection