LuaJIT API Extensions

LuaJIT

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

Copyright © 2005-2008 Mike Pall · Contact