1 <!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
4 <title>Lua/C API Extensions
</title>
5 <meta http-equiv=
"Content-Type" content=
"text/html; charset=iso-8859-1">
6 <meta name=
"Author" content=
"Mike Pall">
7 <meta name=
"Copyright" content=
"Copyright (C) 2005-2013, Mike Pall">
8 <meta name=
"Language" content=
"en">
9 <link rel=
"stylesheet" type=
"text/css" href=
"bluequad.css" media=
"screen">
10 <link rel=
"stylesheet" type=
"text/css" href=
"bluequad-print.css" media=
"print">
14 <a href=
"http://luajit.org"><span>Lua
<span id=
"logo">JIT
</span></span></a>
17 <h1>Lua/C API Extensions
</h1>
21 <a href=
"luajit.html">LuaJIT
</a>
23 <a href=
"http://luajit.org/download.html">Download
<span class=
"ext">»</span></a>
25 <a href=
"install.html">Installation
</a>
27 <a href=
"running.html">Running
</a>
30 <a href=
"extensions.html">Extensions
</a>
32 <a href=
"ext_ffi.html">FFI Library
</a>
34 <a href=
"ext_ffi_tutorial.html">FFI Tutorial
</a>
36 <a href=
"ext_ffi_api.html">ffi.* API
</a>
38 <a href=
"ext_ffi_semantics.html">FFI Semantics
</a>
41 <a href=
"ext_jit.html">jit.* Library
</a>
43 <a class=
"current" href=
"ext_c_api.html">Lua/C API
</a>
46 <a href=
"status.html">Status
</a>
48 <a href=
"changes.html">Changes
</a>
51 <a href=
"faq.html">FAQ
</a>
53 <a href=
"http://luajit.org/performance.html">Performance
<span class=
"ext">»</span></a>
55 <a href=
"http://wiki.luajit.org/">Wiki
<span class=
"ext">»</span></a>
57 <a href=
"http://luajit.org/list.html">Mailing List
<span class=
"ext">»</span></a>
62 LuaJIT adds some extensions to the standard Lua/C API. The LuaJIT include
63 directory must be in the compiler search path (
<tt>-I
<i>path
</i></tt>)
64 to be able to include the required header for C code:
76 <h2 id=
"luaJIT_setmode"><tt>luaJIT_setmode(L, idx, mode)
</tt>
77 — Control VM
</h2>
79 This is a C API extension to allow control of the VM from C code. The
80 full prototype of
<tt>LuaJIT_setmode
</tt> is:
83 LUA_API int luaJIT_setmode(lua_State *L, int idx, int mode);
86 The returned status is either success (
<tt>1</tt>) or failure (
<tt>0</tt>).
87 The second argument is either
<tt>0</tt> or a stack index (similar to the
88 other Lua/C API functions).
91 The third argument specifies the mode, which is 'or'ed with a flag.
92 The flag can be
<tt>LUAJIT_MODE_OFF
</tt> to turn a feature on,
93 <tt>LUAJIT_MODE_ON
</tt> to turn a feature off, or
94 <tt>LUAJIT_MODE_FLUSH
</tt> to flush cached code.
97 The following modes are defined:
100 <h3 id=
"mode_engine"><tt>luaJIT_setmode(L,
0, LUAJIT_MODE_ENGINE|flag)
</tt></h3>
102 Turn the whole JIT compiler on or off or flush the whole cache of compiled code.
105 <h3 id=
"mode_func"><tt>luaJIT_setmode(L, idx, LUAJIT_MODE_FUNC|flag)
</tt><br>
106 <tt>luaJIT_setmode(L, idx, LUAJIT_MODE_ALLFUNC|flag)
</tt><br>
107 <tt>luaJIT_setmode(L, idx, LUAJIT_MODE_ALLSUBFUNC|flag)
</tt></h3>
109 This sets the mode for the function at the stack index
<tt>idx
</tt> or
110 the parent of the calling function (
<tt>idx =
0</tt>). It either
111 enables JIT compilation for a function, disables it and flushes any
112 already compiled code or only flushes already compiled code. This
113 applies recursively to all sub-functions of the function with
114 <tt>LUAJIT_MODE_ALLFUNC
</tt> or only to the sub-functions with
115 <tt>LUAJIT_MODE_ALLSUBFUNC
</tt>.
118 <h3 id=
"mode_trace"><tt>luaJIT_setmode(L, trace,
<br>
119 LUAJIT_MODE_TRACE|LUAJIT_MODE_FLUSH)
</tt></h3>
121 Flushes the specified root trace and all of its side traces from the cache.
122 The code for the trace will be retained as long as there are any other
123 traces which link to it.
126 <h3 id=
"mode_wrapcfunc"><tt>luaJIT_setmode(L, idx, LUAJIT_MODE_WRAPCFUNC|flag)
</tt></h3>
128 This mode defines a wrapper function for calls to C functions. If
129 called with
<tt>LUAJIT_MODE_ON
</tt>, the stack index at
<tt>idx
</tt>
130 must be a
<tt>lightuserdata
</tt> object holding a pointer to the wrapper
131 function. From now on all C functions are called through the wrapper
132 function. If called with
<tt>LUAJIT_MODE_OFF
</tt> this mode is turned
133 off and all C functions are directly called.
136 The wrapper function can be used for debugging purposes or to catch
137 and convert foreign exceptions. But please read the section on
138 <a href=
"extensions.html#exceptions">C++
exception interoperability
</a>
139 first. Recommended usage can be seen in this C++ code excerpt:
142 #include
<exception
>
145 // Catch C++ exceptions and convert them to Lua error messages.
146 // Customize as needed for your own exception classes.
147 static int wrap_exceptions(lua_State *L, lua_CFunction f)
150 return f(L); // Call wrapped function and return result.
151 } catch (const char *s) { // Catch and convert exceptions.
152 lua_pushstring(L, s);
153 } catch (std::exception& e) {
154 lua_pushstring(L, e.what());
156 lua_pushliteral(L,
"caught (...)");
158 return lua_error(L); // Rethrow as a Lua error.
161 static int myinit(lua_State *L)
164 // Define wrapper function and enable it.
165 lua_pushlightuserdata(L, (void *)wrap_exceptions);
166 luaJIT_setmode(L, -
1, LUAJIT_MODE_WRAPCFUNC|LUAJIT_MODE_ON);
172 Note that you can only define
<b>a single global wrapper function
</b>,
173 so be careful when using this mechanism from multiple C++ modules.
174 Also note that this mechanism is not without overhead.
180 Copyright
© 2005-
2013 Mike Pall
181 <span class=
"noprint">
183 <a href=
"contact.html">Contact
</a>