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