ext_c_api.html (6042B)
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> 2 <html> 3 <head> 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-2016, 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"> 11 </head> 12 <body> 13 <div id="site"> 14 <a href="http://luajit.org"><span>Lua<span id="logo">JIT</span></span></a> 15 </div> 16 <div id="head"> 17 <h1>Lua/C API Extensions</h1> 18 </div> 19 <div id="nav"> 20 <ul><li> 21 <a href="luajit.html">LuaJIT</a> 22 <ul><li> 23 <a href="http://luajit.org/download.html">Download <span class="ext">»</span></a> 24 </li><li> 25 <a href="install.html">Installation</a> 26 </li><li> 27 <a href="running.html">Running</a> 28 </li></ul> 29 </li><li> 30 <a href="extensions.html">Extensions</a> 31 <ul><li> 32 <a href="ext_ffi.html">FFI Library</a> 33 <ul><li> 34 <a href="ext_ffi_tutorial.html">FFI Tutorial</a> 35 </li><li> 36 <a href="ext_ffi_api.html">ffi.* API</a> 37 </li><li> 38 <a href="ext_ffi_semantics.html">FFI Semantics</a> 39 </li></ul> 40 </li><li> 41 <a href="ext_jit.html">jit.* Library</a> 42 </li><li> 43 <a class="current" href="ext_c_api.html">Lua/C API</a> 44 </li><li> 45 <a href="ext_profiler.html">Profiler</a> 46 </li></ul> 47 </li><li> 48 <a href="status.html">Status</a> 49 <ul><li> 50 <a href="changes.html">Changes</a> 51 </li></ul> 52 </li><li> 53 <a href="faq.html">FAQ</a> 54 </li><li> 55 <a href="http://luajit.org/performance.html">Performance <span class="ext">»</span></a> 56 </li><li> 57 <a href="http://wiki.luajit.org/">Wiki <span class="ext">»</span></a> 58 </li><li> 59 <a href="http://luajit.org/list.html">Mailing List <span class="ext">»</span></a> 60 </li></ul> 61 </div> 62 <div id="main"> 63 <p> 64 LuaJIT adds some extensions to the standard Lua/C API. The LuaJIT include 65 directory must be in the compiler search path (<tt>-I<i>path</i></tt>) 66 to be able to include the required header for C code: 67 </p> 68 <pre class="code"> 69 #include "luajit.h" 70 </pre> 71 <p> 72 Or for C++ code: 73 </p> 74 <pre class="code"> 75 #include "lua.hpp" 76 </pre> 77 78 <h2 id="luaJIT_setmode"><tt>luaJIT_setmode(L, idx, mode)</tt> 79 — Control VM</h2> 80 <p> 81 This is a C API extension to allow control of the VM from C code. The 82 full prototype of <tt>LuaJIT_setmode</tt> is: 83 </p> 84 <pre class="code"> 85 LUA_API int luaJIT_setmode(lua_State *L, int idx, int mode); 86 </pre> 87 <p> 88 The returned status is either success (<tt>1</tt>) or failure (<tt>0</tt>). 89 The second argument is either <tt>0</tt> or a stack index (similar to the 90 other Lua/C API functions). 91 </p> 92 <p> 93 The third argument specifies the mode, which is 'or'ed with a flag. 94 The flag can be <tt>LUAJIT_MODE_OFF</tt> to turn a feature on, 95 <tt>LUAJIT_MODE_ON</tt> to turn a feature off, or 96 <tt>LUAJIT_MODE_FLUSH</tt> to flush cached code. 97 </p> 98 <p> 99 The following modes are defined: 100 </p> 101 102 <h3 id="mode_engine"><tt>luaJIT_setmode(L, 0, LUAJIT_MODE_ENGINE|flag)</tt></h3> 103 <p> 104 Turn the whole JIT compiler on or off or flush the whole cache of compiled code. 105 </p> 106 107 <h3 id="mode_func"><tt>luaJIT_setmode(L, idx, LUAJIT_MODE_FUNC|flag)</tt><br> 108 <tt>luaJIT_setmode(L, idx, LUAJIT_MODE_ALLFUNC|flag)</tt><br> 109 <tt>luaJIT_setmode(L, idx, LUAJIT_MODE_ALLSUBFUNC|flag)</tt></h3> 110 <p> 111 This sets the mode for the function at the stack index <tt>idx</tt> or 112 the parent of the calling function (<tt>idx = 0</tt>). It either 113 enables JIT compilation for a function, disables it and flushes any 114 already compiled code or only flushes already compiled code. This 115 applies recursively to all sub-functions of the function with 116 <tt>LUAJIT_MODE_ALLFUNC</tt> or only to the sub-functions with 117 <tt>LUAJIT_MODE_ALLSUBFUNC</tt>. 118 </p> 119 120 <h3 id="mode_trace"><tt>luaJIT_setmode(L, trace,<br> 121 LUAJIT_MODE_TRACE|LUAJIT_MODE_FLUSH)</tt></h3> 122 <p> 123 Flushes the specified root trace and all of its side traces from the cache. 124 The code for the trace will be retained as long as there are any other 125 traces which link to it. 126 </p> 127 128 <h3 id="mode_wrapcfunc"><tt>luaJIT_setmode(L, idx, LUAJIT_MODE_WRAPCFUNC|flag)</tt></h3> 129 <p> 130 This mode defines a wrapper function for calls to C functions. If 131 called with <tt>LUAJIT_MODE_ON</tt>, the stack index at <tt>idx</tt> 132 must be a <tt>lightuserdata</tt> object holding a pointer to the wrapper 133 function. From now on all C functions are called through the wrapper 134 function. If called with <tt>LUAJIT_MODE_OFF</tt> this mode is turned 135 off and all C functions are directly called. 136 </p> 137 <p> 138 The wrapper function can be used for debugging purposes or to catch 139 and convert foreign exceptions. But please read the section on 140 <a href="extensions.html#exceptions">C++ exception interoperability</a> 141 first. Recommended usage can be seen in this C++ code excerpt: 142 </p> 143 <pre class="code"> 144 #include <exception> 145 #include "lua.hpp" 146 147 // Catch C++ exceptions and convert them to Lua error messages. 148 // Customize as needed for your own exception classes. 149 static int wrap_exceptions(lua_State *L, lua_CFunction f) 150 { 151 try { 152 return f(L); // Call wrapped function and return result. 153 } catch (const char *s) { // Catch and convert exceptions. 154 lua_pushstring(L, s); 155 } catch (std::exception& e) { 156 lua_pushstring(L, e.what()); 157 } catch (...) { 158 lua_pushliteral(L, "caught (...)"); 159 } 160 return lua_error(L); // Rethrow as a Lua error. 161 } 162 163 static int myinit(lua_State *L) 164 { 165 ... 166 // Define wrapper function and enable it. 167 lua_pushlightuserdata(L, (void *)wrap_exceptions); 168 luaJIT_setmode(L, -1, LUAJIT_MODE_WRAPCFUNC|LUAJIT_MODE_ON); 169 lua_pop(L, 1); 170 ... 171 } 172 </pre> 173 <p> 174 Note that you can only define <b>a single global wrapper function</b>, 175 so be careful when using this mechanism from multiple C++ modules. 176 Also note that this mechanism is not without overhead. 177 </p> 178 <br class="flush"> 179 </div> 180 <div id="foot"> 181 <hr class="hide"> 182 Copyright © 2005-2016 Mike Pall 183 <span class="noprint"> 184 · 185 <a href="contact.html">Contact</a> 186 </span> 187 </div> 188 </body> 189 </html>