doc/ext_c_api.html

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