LuaJIT API Extensions

LuaJIT provides several new API functions organized into two libraries.

LuaJIT includes Coco — so have a look at the Coco API Extensions, too.

Standard Library Functions

All standard library functions have the same behaviour as in the Lua distribution LuaJIT is based on.

The Lua loader used by the standard require() library function has been modified to turn off compilation of the main chunk of a module. The main chunk is only run once when the module is loaded for the first time. There is no point in compiling it.

You might want to adapt this behaviour if you use your own utility functions (and not require()) to load modules.

Note that the subfunctions defined in a loaded module are of course compiled. See below if you want to override this.

The jit.* Library

This library holds several functions to control the behaviour of the JIT engine.

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

Turns the JIT engine on (default) or off.

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

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

Enable (with jit.on, default) or disable (with jit.off) JIT compilation for a Lua function. The current function (the Lua function calling this library function) can be specified with true.

If the second argument is true, JIT compilation is also enabled/disabled recursively for all subfunctions of a function. With false only the subfunctions are affected.

Both library functions only set a flag which is checked when the function is executed for the first/next time. 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. Note that require() already turns off compilation for the main chunk itself.

`status = jit.compile(func [,args...])`

Compiles a Lua function and returns the compilation status. Successful compilation is indicated with a nil status. Failure is indicated with a numeric status (see jit.util.status).

The optimizer pass of the compiler tries to derive hints from the passed arguments. Not passing any arguments or passing untypical arguments (esp. the wrong types) reduces the efficiency of the optimizer. The compiled function will still run, but probably not with maximum speed.

This library function is typically used for Ahead-Of-Time (AOT) compilation of time-critical functions or for testing/debugging.

`status = jit.compilesub(func|true [,true])`

Recursively compile all subfunctions of a Lua function. The current function (the Lua function calling this library function) can be specified with true. Note that the function itself is not compiled (use jit.compile()).

If the second argument is true, compilation will stop when the first error is encountered. Otherwise compilation will continue with the next subfunction.

The returned status is nil, if all subfunctions have been compiled successfully. A numeric status (see jit.util.status) indicates that at least one compilation failed and gives the status of the last failure (this is only helpful when stop on error is true).

`jit.debug([level])`

Set the debug level for JIT compilation. If no level is given, the maximum debug level is set.

Level 0 disables debugging: no checks for hooks are compiled into the code. This is the default when LuaJIT is started and provides the maximum performance.
Level 1 enables function call debugging: call hooks and return hooks are checked in the function prologue and epilogue. This slows down function calls somewhat (by up to 10%).
Level 2 enables full debugging: all hooks are checked. This slows down execution quite a bit, even when the hooks are not active.

Note that some compiler optimizations are turned off when debugging is enabled.

This function is typically used with the command line options -j debug or -j debug=level.

`jit.attach(handler [, priority])`

Attach a handler to the compiler pipeline with the given priority. The handler is detached if no priority is given.

The inner workings of the compiler pipeline and the API for handlers are still in flux. Please see the source code for more details.

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

The jit.util.* Library

This library holds many utility functions used by the provided extension modules for LuaJIT (e.g. the optimizer). The API may change in future versions.

`stats = jit.util.stats(func)`

Retrieves information about a function. Returns nil for C functions. Returns a table with the following fields for Lua functions:

status: numeric compilation status (see jit.util.status).
stackslots: number of stack slots.
params: number of fixed parameters (arguments).
consts: number of constants.
upvalues: number of upvalues.
subs: number of subfunctions (sub prototypes).
bytecodes: number of bytecode instructions.
isvararg: fixarg (false) or vararg (true) function.
env: function environment table.
mcodesize: size of the compiled machine code.
mcodeaddr: start address of the compiled machine code.

mcodesize and mcodeaddr are not set if the function has not been compiled (yet).

`op, a, b, c, test = jit.util.bytecode(func, pc)`

Returns the fields of the bytecode instruction at the given pc for a Lua function. The first instruction is at pc = 1. Nothing is returned if pc is out of range.

The opcode name is returned as an uppercase string in op. The opcode arguments are returned as a, b and optionally c. Arguments that indicate an index into the array of constants are translated to negative numbers (the first constant is referred to with -1). Branch targets are signed numbers relative to the next instruction.

test is true if the instruction is a test (i.e. followed by a JMP).

`const, ok = jit.util.const(func, idx)`

Returns a constant from the array of constants for a Lua function. ok is true if idx is in range. Otherwise nothing is returned.

Constants are numbered starting with 1. A negative idx is mapped to a positive index.

`upvalue, ok = jit.util.upvalue(func, idx)`

Returns an upvalue from the array of upvalues for a Lua function. ok is true if idx is in range. Otherwise nothing is returned. Upvalues are numbered starting with 0.

`nup = jit.util.closurenup(func, idx)`

Returns the number of upvalues for the subfunction prototype with the given index idx for a Lua function. Nothing is returned if idx is out of range. Subfunctions are numbered starting with 0.

`addr, mcode, mfmiter = jit.util.mcode(func, block])`

Returns the numeric start address, the compiled machine code (converted to a string) and an iterator for the machine code fragment map for the specified machine code block associated with a Lua function.

Returns nil and a numeric status code (see jit.util.status) if the function has not been compiled yet or compilation has failed or compilation is disabled. Returns nothing if the selected machine code block does not exist.

The machine code fragment map is used for debugging and error handling. The format may change between versions and is an internal implementation detail of LuaJIT.

`addr [, mcode] = jit.util.jsubmcode([idx])`

If idx is omitted or nil: Returns the numeric start address and the compiled machine code (converted to a string) for internal subroutines used by the compiled machine code.

If idx is given: Returns the numeric start address of the machine code for a specific internal subroutine (0 based). Nothing is returned if idx is out of range.

`jit.util.status`

This is a table that bidirectionally maps status numbers and status names (strings):

Status Name	Description
OK	Ok, code has been compiled.
NONE	Nothing analyzed or compiled, yet (default).
OFF	Compilation disabled for this function.
ENGINE_OFF	JIT engine is turned off.
DELAYED	Compilation delayed (recursive invocation).
TOOLARGE	Bytecode or machine code is too large.
COMPILER_ERROR	Error from compiler frontend.
DASM_ERROR	Error from DynASM engine.

`jit.util.hints jit.util.fhints`

These two tables map compiler hint names to internal hint numbers.

The hint system is an internal implementation detail of LuaJIT. Please see the source code for more info.