From 1d1fed48a002dfc0919135911057ebc255a53e0a Mon Sep 17 00:00:00 2001 From: Mike Pall Date: Tue, 8 Dec 2009 19:49:20 +0100 Subject: RELEASE LuaJIT-2.0.0-beta2 --- doc/api.html | 147 ++++++++++++++++++++++++++++++++++++++++++++++++++++--- doc/changes.html | 32 +++++++++++- doc/faq.html | 23 +++++++++ doc/install.html | 59 ++++++++++++---------- doc/running.html | 6 +-- doc/status.html | 21 ++++++-- 6 files changed, 249 insertions(+), 39 deletions(-) (limited to 'doc') 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.

-

jit.flush(tr)

-

-Flushes the code for the specified root trace and all of its -side traces from the cache. -

-

jit.on(func|true [,true|false])
jit.off(func|true [,true|false])
jit.flush(func|true [,true|false])

@@ -142,6 +136,13 @@ of a module to turn off JIT compilation for the whole module for debugging purposes.

+

status = jit.flush(tr)

+

+Tries to flush the code for the specified trace and all of its +side traces from the cache. Returns true on success. +Returns false if there are still links to this trace. +

+

jit.version

Contains the LuaJIT version string. @@ -189,6 +190,140 @@ The debug modules -jbc, -jv and -jdump make extensive use of these functions. Please check out their source code, if you want to know more.

+ +

C API extensions

+

+LuaJIT adds some extensions to the Lua/C API. The LuaJIT include +directory must be in the compiler search path (-Ipath) +to be able to include the required header for C code: +

+
+#include "luajit.h"
+
+

+Or for C++ code: +

+
+#include "lua.hpp"
+
+ +

luaJIT_setmode(L, idx, mode) +— Control VM

+

+This is a C API extension to allow control of the VM from C code. The +full prototype of LuaJIT_setmode is: +

+
+LUA_API int luaJIT_setmode(lua_State *L, int idx, int mode);
+
+

+The returned status is either success (1) or failure (0). +The second argument is either 0 or a stack index (similar to the +other Lua/C API functions). +

+

+The third argument specifies the mode, which is 'or'ed with a flag. +The flag can be LUAJIT_MODE_OFF to turn a feature on, +LUAJIT_MODE_ON to turn a feature off, or +LUAJIT_MODE_FLUSH to flush cached code. +

+

+The following modes are defined: +

+ +

luaJIT_setmode(L, 0, LUAJIT_MODE_ENGINE|flag)

+

+Turn the whole JIT compiler on or off or flush the whole cache of compiled code. +

+ +

luaJIT_setmode(L, idx, LUAJIT_MODE_FUNC|flag)
+luaJIT_setmode(L, idx, LUAJIT_MODE_ALLFUNC|flag)
+luaJIT_setmode(L, idx, LUAJIT_MODE_ALLSUBFUNC|flag)

+

+This sets the mode for the function at the stack index idx or +the parent of the calling function (idx = 0). 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 +LUAJIT_MODE_ALLFUNC or only to the subfunctions with +LUAJIT_MODE_ALLSUBFUNC. +

+ +

luaJIT_setmode(L, trace,
+  LUAJIT_MODE_TRACE|LUAJIT_MODE_FLUSH)

+

+Tries to flush the code for the specified trace and all of its +side traces from the cache. +

+ +

luaJIT_setmode(L, idx, LUAJIT_MODE_WRAPCFUNC|flag)

+

+This mode defines a wrapper function for calls to C functions. The +first time this is called with LUAJIT_MODE_ON, the stack +index at idx must be a lightuserdata object holding +a pointer to the wrapper function. All subsequently created C +functions are called through the wrapper functions. After the initial +definition idx can be left at 0 when turning the mode +on or off. +

+

+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: +

+
+#include <exception>
+#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);
+  ...
+}
+
+

+Note that you can only define a single global wrapper function, +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 after running luaL_openlibs. +

+

+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 +"C++ exception". +