56 | If you want to report bugs, propose fixes or suggest enhancements, 57 | please use the 58 | » GitHub issue tracker. 59 |
60 |61 | Please send general questions to the 62 | » LuaJIT mailing list. 63 |
64 |65 | You can also send any questions you have directly to me: 66 |
67 | 68 | 76 | 80 |
84 |
85 | 87 | All documentation is 88 | Copyright © 2005-2022 Mike Pall. 89 |
90 | 91 | 92 |56 | LuaJIT adds some extensions to the standard Lua/C API. The LuaJIT include 57 | directory must be in the compiler search path (-Ipath) 58 | to be able to include the required header for C code: 59 |
60 |61 | #include "luajit.h" 62 |63 |
64 | Or for C++ code: 65 |
66 |67 | #include "lua.hpp" 68 |69 | 70 |
73 | This is a C API extension to allow control of the VM from C code. The 74 | full prototype of LuaJIT_setmode is: 75 |
76 |77 | LUA_API int luaJIT_setmode(lua_State *L, int idx, int mode); 78 |79 |
80 | The returned status is either success (1) or failure (0). 81 | The second argument is either 0 or a stack index (similar to the 82 | other Lua/C API functions). 83 |
84 |85 | The third argument specifies the mode, which is 'or'ed with a flag. 86 | The flag can be LUAJIT_MODE_OFF to turn a feature off, 87 | LUAJIT_MODE_ON to turn a feature on, or 88 | LUAJIT_MODE_FLUSH to flush cached code. 89 |
90 |91 | The following modes are defined: 92 |
93 | 94 |96 | Turn the whole JIT compiler on or off or flush the whole cache of compiled code. 97 |
98 | 99 |103 | This sets the mode for the function at the stack index idx or 104 | the parent of the calling function (idx = 0). It either 105 | enables JIT compilation for a function, disables it and flushes any 106 | already compiled code or only flushes already compiled code. This 107 | applies recursively to all sub-functions of the function with 108 | LUAJIT_MODE_ALLFUNC or only to the sub-functions with 109 | LUAJIT_MODE_ALLSUBFUNC. 110 |
111 | 112 |115 | Flushes the specified root trace and all of its side traces from the cache. 116 | The code for the trace will be retained as long as there are any other 117 | traces which link to it. 118 |
119 | 120 |122 | This mode defines a wrapper function for calls to C functions. If 123 | called with LUAJIT_MODE_ON, the stack index at idx 124 | must be a lightuserdata object holding a pointer to the wrapper 125 | function. From now on all C functions are called through the wrapper 126 | function. If called with LUAJIT_MODE_OFF this mode is turned 127 | off and all C functions are directly called. 128 |
129 |130 | The wrapper function can be used for debugging purposes or to catch 131 | and convert foreign exceptions. But please read the section on 132 | C++ exception interoperability 133 | first. Recommended usage can be seen in this C++ code excerpt: 134 |
135 |
136 | #include <exception>
137 | #include "lua.hpp"
138 |
139 | // Catch C++ exceptions and convert them to Lua error messages.
140 | // Customize as needed for your own exception classes.
141 | static int wrap_exceptions(lua_State *L, lua_CFunction f)
142 | {
143 | try {
144 | return f(L); // Call wrapped function and return result.
145 | } catch (const char *s) { // Catch and convert exceptions.
146 | lua_pushstring(L, s);
147 | } catch (std::exception& e) {
148 | lua_pushstring(L, e.what());
149 | } catch (...) {
150 | lua_pushliteral(L, "caught (...)");
151 | }
152 | return lua_error(L); // Rethrow as a Lua error.
153 | }
154 |
155 | static int myinit(lua_State *L)
156 | {
157 | ...
158 | // Define wrapper function and enable it.
159 | lua_pushlightuserdata(L, (void *)wrap_exceptions);
160 | luaJIT_setmode(L, -1, LUAJIT_MODE_WRAPCFUNC|LUAJIT_MODE_ON);
161 | lua_pop(L, 1);
162 | ...
163 | }
164 |
165 | 166 | Note that you can only define a single global wrapper function, 167 | so be careful when using this mechanism from multiple C++ modules. 168 | Also note that this mechanism is not without overhead. 169 |
170 |56 | The functions in this built-in module control the behavior of the JIT 57 | compiler engine. Note that JIT-compilation is fully automatic — 58 | you probably won't need to use any of the following functions unless 59 | you have special needs. 60 |
61 | 62 |65 | Turns the whole JIT compiler on (default) or off. 66 |
67 |68 | These functions are typically used with the command line options 69 | -j on or -j off. 70 |
71 | 72 |74 | Flushes the whole cache of compiled code. 75 |
76 | 77 |81 | jit.on enables JIT compilation for a Lua function (this is 82 | the default). 83 |
84 |85 | jit.off disables JIT compilation for a Lua function and 86 | flushes any already compiled code from the code cache. 87 |
88 |89 | jit.flush flushes the code, but doesn't affect the 90 | enable/disable status. 91 |
92 |93 | The current function, i.e. the Lua function calling this library 94 | function, can also be specified by passing true as the first 95 | argument. 96 |
97 |98 | If the second argument is true, JIT compilation is also 99 | enabled, disabled or flushed recursively for all sub-functions of a 100 | function. With false only the sub-functions are affected. 101 |
102 |103 | The jit.on and jit.off functions only set a flag 104 | which is checked when the function is about to be compiled. They do 105 | not trigger immediate compilation. 106 |
107 |108 | Typical usage is jit.off(true, true) in the main chunk 109 | of a module to turn off JIT compilation for the whole module for 110 | debugging purposes. 111 |
112 | 113 |115 | Flushes the root trace, specified by its number, and all of its side 116 | traces from the cache. The code for the trace will be retained as long 117 | as there are any other traces which link to it. 118 |
119 | 120 |122 | Returns the current status of the JIT compiler. The first result is 123 | either true or false if the JIT compiler is turned 124 | on or off. The remaining results are strings for CPU-specific features 125 | and enabled optimizations. 126 |
127 | 128 |130 | Contains the LuaJIT version string. 131 |
132 | 133 |135 | Contains the version number of the LuaJIT core. Version xx.yy.zz 136 | is represented by the decimal number xxyyzz. 137 |
138 | 139 |141 | Contains the target OS name: 142 | "Windows", "Linux", "OSX", "BSD", "POSIX" or "Other". 143 |
144 | 145 |147 | Contains the target architecture name: 148 | "x86", "x64", "arm", "ppc", "ppcspe", or "mips". 149 |
150 | 151 |153 | This sub-module provides the backend for the -O command line 154 | option. 155 |
156 |157 | You can also use it programmatically, e.g.: 158 |
159 |
160 | jit.opt.start(2) -- same as -O2
161 | jit.opt.start("-dce")
162 | jit.opt.start("hotloop=10", "hotexit=2")
163 |
164 | 165 | Unlike in LuaJIT 1.x, the module is built-in and 166 | optimization is turned on by default! 167 | It's no longer necessary to run require("jit.opt").start(), 168 | which was one of the ways to enable optimization. 169 |
170 | 171 |173 | This sub-module holds functions to introspect the bytecode, generated 174 | traces, the IR and the generated machine code. The functionality 175 | provided by this module is still in flux and therefore undocumented. 176 |
177 |178 | The debug modules -jbc, -jv and -jdump make 179 | extensive use of these functions. Please check out their source code, 180 | if you want to know more. 181 |
182 |59 | This documentation is for LuaJIT 2.0.5. Please check the doc 60 | directory in each git branch for the version-specific documentation. 61 |
62 |63 | The currently developed branches are LuaJIT 2.1 and LuaJIT 2.0. 64 |
65 |66 | LuaJIT 2.0 is in feature-freeze — new features will only 67 | be added to LuaJIT 2.1. 68 |
69 | 70 |72 | LuaJIT ought to run all Lua 5.1-compatible source code just fine. 73 | It's considered a serious bug if the VM crashes or produces unexpected 74 | results — please report this. 75 |
76 |77 | Known incompatibilities and issues in LuaJIT 2.0: 78 |
79 |