RELEASE LuaJIT-2.0.0-beta2

2009-12-08 19:49:20 +01:00
parent 55b1695971
commit 1d1fed48a0
46 changed files with 1289 additions and 441 deletions
--- 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">
--- a/doc/changes.html
+++ b/doc/changes.html
@@ -43,7 +43,7 @@ div.major { max-width: 600px; padding: 1em; margin: 1em 0 1em 0; }
 <div id="main">
 <p>
 This is a list of changes between the released versions of LuaJIT.<br>
-The current <span style="color: #c00000;">development version</span> is <strong>LuaJIT&nbsp;2.0.0-beta1</strong>.<br>
+The current <span style="color: #c00000;">development version</span> is <strong>LuaJIT&nbsp;2.0.0-beta2</strong>.<br>
 The current <span style="color: #0000c0;">stable version</span> is <strong>LuaJIT&nbsp;1.1.5</strong>.
 </p>
 <p>
@@ -53,6 +53,36 @@ to see whether newer versions are available.
 </p>

 <div class="major" style="background: #ffd0d0;">
+<h2 id="LuaJIT-2.0.0-beta2">LuaJIT 2.0.0-beta2 &mdash; 2009-11-09</h2>
+<ul>
+<li>Reorganize build system. Build static+shared library on POSIX.</li>
+<li>Allow C++ exception conversion on all platforms
+using a wrapper function.</li>
+<li>Automatically catch C++ exceptions and rethrow Lua error
+(ELF/DWARF2 only).</li>
+<li>Check for the correct x87 FPU precision at strategic points.</li>
+<li>Always use wrappers for libm functions.</li>
+<li>Resurrect metamethod name strings before copying them.</li>
+<li>Mark current trace, even if compiler is idle.</li>
+<li>Ensure FILE metatable is created only once.</li>
+<li>Fix type comparisons when different integer types are involved.</li>
+<li>Fix getmetatable() recording.</li>
+<li>Fix TDUP with dead keys in template table.</li>
+<li><tt>jit.flush(tr)</tt> returns status.
+Prevent manual flush of a trace that's still linked.</li>
+<li>Improve register allocation heuristics for invariant references.</li>
+<li>Compile the push/pop variants of <tt>table.insert()</tt> and
+<tt>table.remove()</tt>.</li>
+<li>Compatibility with MSVC <tt>link&nbsp/debug</tt>.</li>
+<li>Fix <tt>lua_iscfunction()</tt>.</li>
+<li>Fix <tt>math.random()</tt> when compiled with <tt>-fpic</tt> (OSX).</li>
+<li>Fix <tt>table.maxn()</tt>.</li>
+<li>Bump <tt>MACOSX_DEPLOYMENT_TARGET</tt> to <tt>10.4</tt></li>
+<li><tt>luaL_check*()</tt> and <tt>luaL_opt*()</tt> now support
+negative arguments, too.<br>
+This matches the behavior of Lua 5.1, but not the specification.</li>
+</ul>
+
 <h2 id="LuaJIT-2.0.0-beta1">LuaJIT 2.0.0-beta1 &mdash; 2009-10-31</h2>
 <ul>
 <li>This is the first public release of LuaJIT 2.0.</li>
--- a/doc/faq.html
+++ b/doc/faq.html
@@ -72,6 +72,7 @@ Search for: <a href="http://scholar.google.com/scholar?q=JIT+Compiler"><span cla
 Search for: <a href="http://scholar.google.com/scholar?q=Dynamic+Language+Optimizations"><span class="ext">&raquo;</span>&nbsp;Dynamic Language Optimizations</a><br>
 Search for: <a href="http://scholar.google.com/scholar?q=SSA+Form"><span class="ext">&raquo;</span>&nbsp;SSA Form</a><br>
 Search for: <a href="http://scholar.google.com/scholar?q=Linear+Scan+Register+Allocation"><span class="ext">&raquo;</span>&nbsp;Linear Scan Register Allocation</a><br>
+Here is a list of the <a href="http://article.gmane.org/gmane.comp.lang.lua.general/58908"><span class="ext">&raquo;</span>&nbsp;innovative features in LuaJIT</a>.<br>
 And, you know, reading the source is of course the only way to enlightenment. :-)
 </dd>
 </dl>
@@ -86,6 +87,28 @@ functions from Lua 5.0.<br>Please convert your code to the
 vararg syntax</a>.</dd>
 </dl>

+<dl>
+<dt>Q: Why do I get this error: "bad FPU precision"?<br>
+<dt>Q: I get weird behavior after initializing Direct3D.<br>
+<dt>Q: Some FPU operations crash after I load a Delphi DLL.<br>
+</dt>
+<dd>
+
+DirectX/Direct3D (up to version 9) sets the x87 FPU to single-precision
+mode by default. This violates the Windows ABI and interferes with the
+operation of many programs &mdash; LuaJIT is affected, too. Please make
+sure you always use the <tt>D3DCREATE_FPU_PRESERVE</tt> flag when
+initializing Direct3D.<br>
+
+Direct3D version 10 or higher do not show this behavior anymore.
+Consider testing your application with older versions, too.<br>
+
+Similarly, the Borland/Delphi runtime modifies the FPU control word and
+enables FP exceptions. Of course this violates the Windows ABI, too.
+Please check the Delphi docs for the Set8087CW method.
+
+</dl>
+
 <dl>
 <dt>Q: Sometimes Ctrl-C fails to stop my Lua program. Why?</dt>
 <dd>The interrupt signal handler sets a Lua debug hook. But this is
--- a/doc/install.html
+++ b/doc/install.html
@@ -58,17 +58,15 @@ application under x64-based systems, too.
 <h2>Configuring LuaJIT</h2>
 <p>
 The standard configuration should work fine for most installations.
-Usually there is no need to tweak the settings, except when you want to
-install to a non-standard path. The following three files hold all
-user-configurable settings:
+Usually there is no need to tweak the settings. The following files
+hold all user-configurable settings:
 </p>
 <ul>
-<li><tt>src/luaconf.h</tt> sets some configuration variables, in
-particular the default paths for loading modules.</li>
-<li><tt>Makefile</tt> has settings for installing LuaJIT (POSIX
+<li><tt>src/luaconf.h</tt> sets some configuration variables.</li>
+<li><tt>Makefile</tt> has settings for <b>installing</b> LuaJIT (POSIX
 only).</li>
-<li><tt>src/Makefile</tt> has settings for compiling LuaJIT under POSIX,
-MinGW and Cygwin.</li>
+<li><tt>src/Makefile</tt> has settings for <b>compiling</b> LuaJIT
+under POSIX, MinGW and Cygwin.</li>
 <li><tt>src/msvcbuild.bat</tt> has settings for compiling LuaJIT with
 MSVC.</li>
 </ul>
@@ -97,9 +95,8 @@ terminal window and change to this directory. Now unpack the archive
 and change to the newly created directory:
 </p>
 <pre class="code">
-tar zxf LuaJIT-2.0.0-beta1.tar.gz
-cd LuaJIT-2.0.0-beta1
-</pre>
+tar zxf LuaJIT-2.0.0-beta2.tar.gz
+cd LuaJIT-2.0.0-beta2</pre>
 <h3>Building LuaJIT</h3>
 <p>
 The supplied Makefiles try to auto-detect the settings needed for your
@@ -109,6 +106,18 @@ which is probably the default on your system, anyway. Simply run:
 <pre class="code">
 make
 </pre>
+<p>
+By default modules are only searched under the prefix <tt>/usr/local</tt>.
+You can add an extra prefix to the search paths by appending the
+<tt>PREFIX</tt> option, e.g.:
+</p>
+<pre class="code">
+make PREFIX=/home/myself/lj2
+</pre>
+<p>
+Note for OSX: <tt>MACOSX_DEPLOYMENT_TARGET</tt> is set to <tt>10.4</tt>
+in <tt>src/Makefile</tt>. Change it, if you want to build on an older version.
+</p>
 <h3>Installing LuaJIT</h3>
 <p>
 The top-level Makefile installs LuaJIT by default under
@@ -124,20 +133,19 @@ sudo make install
 Otherwise specify the directory prefix as an absolute path, e.g.:
 </p>
 <pre class="code">
-sudo make install PREFIX=/opt/lj2
+make install PREFIX=/home/myself/lj2
 </pre>
 <p>
-But note that the installation prefix and the prefix for the module paths
-(configured in <tt>src/luaconf.h</tt>) must match.
+Obviously the prefixes given during build and installation need to be the same.
 </p>
 <p style="color: #c00000;">
 Note: to avoid overwriting a previous version, the beta test releases
 only install the LuaJIT executable under the versioned name (i.e.
-<tt>luajit-2.0.0-beta1</tt>). You probably want to create a symlink
+<tt>luajit-2.0.0-beta2</tt>). You probably want to create a symlink
 for convenience, with a command like this:
 </p>
 <pre class="code" style="color: #c00000;">
-sudo ln -sf luajit-2.0.0-beta1 /usr/local/bin/luajit
+sudo ln -sf luajit-2.0.0-beta2&nbsp;/usr/local/bin/luajit
 </pre>

 <h2 id="windows">Windows Systems</h2>
@@ -145,8 +153,8 @@ sudo ln -sf luajit-2.0.0-beta1 /usr/local/bin/luajit
 <p>
 Either install one of the open source SDKs
 (<a href="http://mingw.org/"><span class="ext">&raquo;</span>&nbsp;MinGW</a> or
-<a href="http://www.cygwin.com/"><span class="ext">&raquo;</span>&nbsp;Cygwin</a>) which come with modified
-versions of GCC plus the required development headers.
+<a href="http://www.cygwin.com/"><span class="ext">&raquo;</span>&nbsp;Cygwin</a>), which come with a modified
+GCC plus the required development headers.
 </p>
 <p>
 Or install Microsoft's Visual C++ (MSVC) &mdash; the freely downloadable
@@ -159,8 +167,8 @@ Next, download the source package and unpack it using an archive manager
 </p>
 <h3>Building with MSVC</h3>
 <p>
-Open a "Visual Studio .NET Command Prompt" and <tt>cd</tt> to the
-directory where you've unpacked the sources. Then run this command:
+Open a "Visual Studio .NET Command Prompt", <tt>cd</tt> to the
+directory where you've unpacked the sources and run these commands:
 </p>
 <pre class="code">
 cd src
@@ -176,14 +184,12 @@ are in your path. Then <tt>cd</tt> to the directory where
 you've unpacked the sources and run this command for MinGW:
 </p>
 <pre class="code">
-cd src
 mingw32-make
 </pre>
 <p>
 Or this command for Cygwin:
 </p>
 <pre class="code">
-cd src
 make
 </pre>
 <p>
@@ -191,10 +197,11 @@ Then follow the installation instructions below.
 </p>
 <h3>Installing LuaJIT</h3>
 <p>
-Copy <tt>luajit.exe</tt> and <tt>lua51.dll</tt>
-to a newly created directory (any location is ok). Add <tt>lua</tt>
-and <tt>lua\jit</tt> directories below it and copy all Lua files
-from the <tt>lib</tt> directory of the distribution to the latter directory.
+Copy <tt>luajit.exe</tt> and <tt>lua51.dll</tt> (built in the <tt>src</tt>
+directory) to a newly created directory (any location is ok).
+Add <tt>lua</tt> and <tt>lua\jit</tt> directories below it and copy
+all Lua files from the <tt>lib</tt> directory of the distribution
+to the latter directory.
 </p>
 <p>
 There are no hardcoded
--- a/doc/running.html
+++ b/doc/running.html
@@ -69,11 +69,11 @@ interactive mode, too.
 <p class="indent" style="color: #c00000;">
 Note: the beta test releases only install under the versioned name on
 POSIX systems (to avoid overwriting a previous version). You either need
-to type <tt>luajit-2.0.0-beta1</tt> to start it or create a symlink
+to type <tt>luajit-2.0.0-beta2</tt> to start it or create a symlink
 with a command like this:
 </p>
 <pre class="code" style="color: #c00000;">
-sudo ln -sf luajit-2.0.0-beta1 /usr/local/bin/luajit
+sudo ln -sf luajit-2.0.0-beta2&nbsp;/usr/local/bin/luajit
 </pre>
 <p>
 Unlike previous versions <b>optimization is turned on by default</b> in
@@ -119,7 +119,7 @@ itself. For a description of their options and output format, please
 read the comment block at the start of their source.
 They can be found in the <tt>lib</tt> directory of the source
 distribution or installed under the <tt>jit</tt> directory. By default
-this is <tt>/usr/local/share/luajit-2.0.0-beta1/jit</tt> on POSIX
+this is <tt>/usr/local/share/luajit-2.0.0-beta2/jit</tt> on POSIX
 systems.
 </p>

--- a/doc/status.html
+++ b/doc/status.html
@@ -90,7 +90,22 @@ known incompatibilities with standard Lua:
 <ul>
 <li>
 The Lua <b>debug API</b> is missing a couple of features (call/return
-hooks) and shows slightly different behavior (no per-coroutine hooks).
+hooks) and shows slightly different behavior (no per-coroutine hooks,
+no tail call counting).
+</li>
+<li>
+<b>Bytecode</b> currently cannot be loaded or dumped. Note that
+the bytecode format differs from Lua&nbsp;5.1 &mdash; loading foreign
+bytecode is not supported at all.
+</li>
+<li>
+Some of the <b>configuration options</b> of Lua&nbsp;5.1 are not supported:
+<ul>
+<li>The <b>number type</b> cannot be changed (it's always a <tt>double</tt>).</li>
+<li>The stand-alone executable cannot be linked with <b>readline</b>
+to enable line editing. It's planned to add support for loading it
+on-demand.</li>
+</ul>
 </li>
 <li>
 Most other issues you're likely to find (e.g. with the existing test
@@ -105,7 +120,7 @@ demonstrable need is shown.
 <li>
 The <b>JIT compiler</b> is not complete (yet) and falls back to the
 interpreter in some cases. All of this works transparently, so unless
-you use -jv, you'll probably never notice (the interpreter is quite
+you use <tt>-jv</tt>, you'll probably never notice (the interpreter is quite
 fast, too). Here are the known issues:
 <ul>
 <li>
@@ -119,7 +134,7 @@ effort.
 </li>
 <li>
 <b>Recursion</b> is not traced yet. Often no trace will be generated at
-all or some unroll limit will catch it and aborts the trace.
+all or some unroll limit will catch it and abort the trace.
 </li>
 <li>
 The trace compiler currently does not back off specialization for