1 files changed, 141 insertions, 6 deletions

diff --git a/doc/api.html b/doc/api.html
index 79788d95..3bb10967 100644
--- a/doc/api.html
+++ b/doc/api.html
@@ -100,12 +100,6 @@ These functions are typically used with the command line options
 Flushes the whole cache of compiled code.
 </p>
 
-<h3 id="jit_flush_tr"><tt>jit.flush(tr)</tt></h3>
-<p>
-Flushes the code for the specified root trace and all of its
-side traces from the cache.
-</p>
-
 <h3 id="jit_onoff_func"><tt>jit.on(func|true [,true|false])<br>
 jit.off(func|true [,true|false])<br>
 jit.flush(func|true [,true|false])</tt></h3>
@@ -142,6 +136,13 @@ of a module to turn off JIT compilation for the whole module for
 debugging purposes.
 </p>
 
+<h3 id="jit_flush_tr"><tt>status = jit.flush(tr)</tt></h3>
+<p>
+Tries to flush the code for the specified trace and all of its
+side traces from the cache. Returns <tt>true</tt> on success.
+Returns <tt>false</tt> if there are still links to this trace.
+</p>
+
 <h3 id="jit_version"><tt>jit.version</tt></h3>
 <p>
 Contains the LuaJIT version string.
@@ -189,6 +190,140 @@ The debug modules <tt>-jbc</tt>, <tt>-jv</tt> and <tt>-jdump</tt> make
 extensive use of these functions. Please check out their source code,
 if you want to know more.
 </p>
+
+<h2 id="c_api">C API extensions</h2>
+<p>
+LuaJIT adds some extensions to the Lua/C API. The LuaJIT include
+directory must be in the compiler search path (<tt>-I<i>path</i></tt>)
+to be able to include the required header for C code:
+</p>
+<pre class="code">
+#include "luajit.h"
+</pre>
+<p>
+Or for C++ code:
+</p>
+<pre class="code">
+#include "lua.hpp"
+</pre>
+
+<h2 id="luaJIT_setmode"><tt>luaJIT_setmode(L, idx, mode)</tt>
+&mdash; Control VM</h2>
+<p>
+This is a C API extension to allow control of the VM from C code. The
+full prototype of <tt>LuaJIT_setmode</tt> is:
+</p>
+<pre class="code">
+LUA_API int luaJIT_setmode(lua_State *L, int idx, int mode);
+</pre>
+<p>
+The returned status is either success (<tt>1</tt>) or failure (<tt>0</tt>).
+The second argument is either <tt>0</tt> or a stack index (similar to the
+other Lua/C API functions).
+</p>
+<p>
+The third argument specifies the mode, which is 'or'ed with a flag.
+The flag can be <tt>LUAJIT_MODE_OFF</tt> to turn a feature on,
+<tt>LUAJIT_MODE_ON</tt> to turn a feature off, or
+<tt>LUAJIT_MODE_FLUSH</tt> to flush cached code.
+</p>
+<p>
+The following modes are defined:
+</p>
+
+<h3 id="mode_engine"><tt>luaJIT_setmode(L, 0, LUAJIT_MODE_ENGINE|flag)</tt></h3>
+<p>
+Turn the whole JIT compiler on or off or flush the whole cache of compiled code.
+</p>
+
+<h3 id="mode_func"><tt>luaJIT_setmode(L, idx, LUAJIT_MODE_FUNC|flag)</tt><br>
+<tt>luaJIT_setmode(L, idx, LUAJIT_MODE_ALLFUNC|flag)</tt><br>
+<tt>luaJIT_setmode(L, idx, LUAJIT_MODE_ALLSUBFUNC|flag)</tt></h3>
+<p>
+This sets the mode for the function at the stack index <tt>idx</tt> or
+the parent of the calling function (<tt>idx = 0</tt>). It either
+enables JIT compilation for a function, disables it and flushes any
+already compiled code or only flushes already compiled code. This
+applies recursively to all subfunctions of the function with
+<tt>LUAJIT_MODE_ALLFUNC</tt> or only to the subfunctions with
+<tt>LUAJIT_MODE_ALLSUBFUNC</tt>.
+</p>
+
+<h3 id="mode_engine"><tt>luaJIT_setmode(L, trace,<br>
+&nbsp;&nbsp;LUAJIT_MODE_TRACE|LUAJIT_MODE_FLUSH)</tt></h3>
+<p>
+Tries to flush the code for the specified trace and all of its
+side traces from the cache.
+</p>
+
+<h3 id="mode_engine"><tt>luaJIT_setmode(L, idx, LUAJIT_MODE_WRAPCFUNC|flag)</tt></h3>
+<p>
+This mode defines a wrapper function for calls to C functions. The
+first time this is called with <tt>LUAJIT_MODE_ON</tt>, the stack
+index at <tt>idx</tt> must be a <tt>lightuserdata</tt> object holding
+a pointer to the wrapper function. All <b>subsequently created C
+functions</b> are called through the wrapper functions. After the initial
+definition <tt>idx</tt> can be left at <tt>0</tt> when turning the mode
+on or off.
+</p>
+<p>
+The wrapper function can be used for debugging purposes or to catch
+and convert foreign exceptions. Recommended usage can be seen in this
+C++ code excerpt:
+</p>
+<pre class="code">
+#include &lt;exception&gt;
+#include "lua.hpp"
+
+// Catch C++ exceptions and convert them to Lua error messages.
+// Customize as needed for your own exception classes.
+static int wrap_exceptions(lua_State *L, lua_CFunction f)
+{
+  try {
+    return f(L);  // Call wrapped function and return result.
+  } catch (const char *s) {  // Catch and convert exceptions.
+    lua_pushstring(L, s);
+  } catch (std::exception& e) {
+    lua_pushstring(L, e.what());
+  } catch (...) {
+    lua_pushliteral(L, "caught (...)");
+  }
+  return lua_error(L);  // Rethrow as a Lua error.
+}
+
+static int myregister(lua_State *L)
+{
+  ...
+  // Define wrapper function and enable it.
+  lua_pushlightuserdata(L, (void *)wrap_exceptions);
+  luaJIT_setmode(L, -1, LUAJIT_MODE_WRAPCFUNC|LUAJIT_MODE_ON);
+  lua_pop(L, 1);
+  luaL_register(L, "mymodule", myfuncs);  // Pass luaL_Reg list.
+  luaJIT_setmode(L, 0, LUAJIT_MODE_WRAPCFUNC|LUAJIT_MODE_OFF);
+  ...
+  // Wrap some more C++ functions which might throw an exception.
+  luaJIT_setmode(L, 0, LUAJIT_MODE_WRAPCFUNC|LUAJIT_MODE_ON);
+  lua_pushcfunction(L, mythrowingfunc1);
+  lua_pushcclosure(L, mythrowingfunc2, 1);
+  luaJIT_setmode(L, 0, LUAJIT_MODE_WRAPCFUNC|LUAJIT_MODE_OFF);
+  ...
+}
+</pre>
+<p>
+Note that you can only define <b>a single global wrapper function</b>,
+so be careful when using this mechanism from multiple C++ modules.
+Also note that this mechanism is not without overhead. It should only
+be enabled for definitions of C++ functions that can actually throw
+exceptions. If you're embedding LuaJIT into an application, only
+enable it <b>after</b> running <tt>luaL_openlibs</tt>.
+</p>
+<p>
+LuaJIT already intercepts exception handling for systems using
+ELF/DWARF2 stack unwinding (e.g. Linux). This is a zero-cost mechanism
+and always enabled. You don't need to use any wrapper functions,
+except when you want to get a more specific error message than
+<tt>"C++&nbsp;exception"</tt>.
+</p>
 <br class="flush">
 </div>
 <div id="foot">