From b45e3246cee8c92b72622808f03b5cb7d539e244 Mon Sep 17 00:00:00 2001
From: Mike Pall <mike>
Date: Tue, 9 Nov 2010 18:11:35 +0100
Subject: Split up extension/API docs into sub-pages.
---
doc/api.html | 337 ----------------------------------------------------
doc/changes.html | 7 +-
doc/contact.html | 7 +-
doc/ext_c_api.html | 174 +++++++++++++++++++++++++++
doc/ext_jit.html | 177 +++++++++++++++++++++++++++
doc/extensions.html | 303 ++++++++++++++++++++++++++++++++++++++++++++++
doc/faq.html | 7 +-
doc/install.html | 21 ++--
doc/luajit.html | 7 +-
doc/running.html | 7 +-
doc/status.html | 7 +-
11 files changed, 703 insertions(+), 351 deletions(-)
delete mode 100644 doc/api.html
create mode 100644 doc/ext_c_api.html
create mode 100644 doc/ext_jit.html
create mode 100644 doc/extensions.html
(limited to 'doc')
diff --git a/doc/api.html b/doc/api.html
deleted file mode 100644
index eee76afb..00000000
--- a/doc/api.html
+++ /dev/null
@@ -1,337 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
-<html>
-<head>
-<title>API Extensions</title>
-<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
-<meta name="Author" content="Mike Pall">
-<meta name="Copyright" content="Copyright (C) 2005-2010, Mike Pall">
-<meta name="Language" content="en">
-<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
-<link rel="stylesheet" type="text/css" href="bluequad-print.css" media="print">
-</head>
-<body>
-<div id="site">
-<a href="http://luajit.org"><span>Lua<span id="logo">JIT</span></span></a>
-</div>
-<div id="head">
-<h1>API Extensions</h1>
-</div>
-<div id="nav">
-<ul><li>
-<a href="luajit.html">LuaJIT</a>
-<ul><li>
-<a href="install.html">Installation</a>
-</li><li>
-<a href="running.html">Running</a>
-</li><li>
-<a class="current" href="api.html">API Extensions</a>
-</li></ul>
-</li><li>
-<a href="status.html">Status</a>
-<ul><li>
-<a href="changes.html">Changes</a>
-</li></ul>
-</li><li>
-<a href="faq.html">FAQ</a>
-</li><li>
-<a href="http://luajit.org/performance.html">Performance <span class="ext">»</span></a>
-</li><li>
-<a href="http://luajit.org/download.html">Download <span class="ext">»</span></a>
-</li></ul>
-</div>
-<div id="main">
-<p>
-LuaJIT is fully upwards-compatible with Lua 5.1. It supports all
-<a href="http://www.lua.org/manual/5.1/manual.html#5"><span class="ext">»</span> standard Lua
-library functions</a> and the full set of
-<a href="http://www.lua.org/manual/5.1/manual.html#3"><span class="ext">»</span> Lua/C API
-functions</a>.
-</p>
-<p>
-LuaJIT is also fully ABI-compatible to Lua 5.1 at the linker/dynamic
-loader level. This means you can compile a C module against the
-standard Lua headers and load the same shared library from either Lua
-or LuaJIT.
-</p>
-
-<h2 id="bit"><tt>bit.*</tt> — Bitwise Operations</h2>
-<p>
-LuaJIT supports all bitwise operations as defined by
-<a href="http://bitop.luajit.org"><span class="ext">»</span> Lua BitOp</a>:
-</p>
-<pre class="code">
-bit.tobit bit.tohex bit.bnot bit.band bit.bor bit.bxor
-bit.lshift bit.rshift bit.arshift bit.rol bit.ror bit.bswap
-</pre>
-<p>
-This module is a LuaJIT built-in — you don't need to download or
-install Lua BitOp. The Lua BitOp site has full documentation for all
-<a href="http://bitop.luajit.org/api.html"><span class="ext">»</span> Lua BitOp API functions</a>.
-</p>
-<p>
-Please make sure to <tt>require</tt> the module before using any of
-its functions:
-</p>
-<pre class="code">
-local bit = require("bit")
-</pre>
-<p>
-An already installed Lua BitOp module is ignored by LuaJIT.
-This way you can use bit operations from both Lua and LuaJIT on a
-shared installation.
-</p>
-
-<h2 id="jit"><tt>jit.*</tt> — JIT compiler control</h2>
-<p>
-The functions in this built-in module control the behavior
-of the JIT compiler engine.
-</p>
-
-<h3 id="jit_onoff"><tt>jit.on()<br>
-jit.off()</tt></h3>
-<p>
-Turns the whole JIT compiler on (default) or off.
-</p>
-<p>
-These functions are typically used with the command line options
-<tt>-j on</tt> or <tt>-j off</tt>.
-</p>
-
-<h3 id="jit_flush"><tt>jit.flush()</tt></h3>
-<p>
-Flushes the whole cache of compiled code.
-</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>
-<p>
-<tt>jit.on</tt> enables JIT compilation for a Lua function (this is
-the default).
-</p>
-<p>
-<tt>jit.off</tt> disables JIT compilation for a Lua function and
-flushes any already compiled code from the code cache.
-</p>
-<p>
-<tt>jit.flush</tt> flushes the code, but doesn't affect the
-enable/disable status.
-</p>
-<p>
-The current function, i.e. the Lua function calling this library
-function, can also be specified by passing <tt>true</tt> as the first
-argument.
-</p>
-<p>
-If the second argument is <tt>true</tt>, JIT compilation is also
-enabled, disabled or flushed recursively for all sub-functions of a
-function. With <tt>false</tt> only the sub-functions are affected.
-</p>
-<p>
-The <tt>jit.on</tt> and <tt>jit.off</tt> functions only set a flag
-which is checked when the function is about to be compiled. They do
-not trigger immediate compilation.
-</p>
-<p>
-Typical usage is <tt>jit.off(true, true)</tt> in the main chunk
-of a module to turn off JIT compilation for the whole module for
-debugging purposes.
-</p>
-
-<h3 id="jit_flush_tr"><tt>jit.flush(tr)</tt></h3>
-<p>
-Flushes the specified root trace and all of its side traces from the cache.
-The code for the trace will be retained as long as there are any other
-traces which link to it.
-</p>
-
-<h3 id="jit_status"><tt>status, ... = jit.status()</tt></h3>
-<p>
-Returns the current status of the JIT compiler. The first result is
-either <tt>true</tt> or <tt>false</tt> if the JIT compiler is turned
-on or off. The remaining results are strings for CPU-specific features
-and enabled optimizations.
-</p>
-
-<h3 id="jit_version"><tt>jit.version</tt></h3>
-<p>
-Contains the LuaJIT version string.
-</p>
-
-<h3 id="jit_version_num"><tt>jit.version_num</tt></h3>
-<p>
-Contains the version number of the LuaJIT core. Version xx.yy.zz
-is represented by the decimal number xxyyzz.
-</p>
-
-<h3 id="jit_arch"><tt>jit.arch</tt></h3>
-<p>
-Contains the target architecture name (CPU and optional ABI).
-</p>
-
-<h2 id="jit_opt"><tt>jit.opt.*</tt> — JIT compiler optimization control</h2>
-<p>
-This module provides the backend for the <tt>-O</tt> command line
-option.
-</p>
-<p>
-You can also use it programmatically, e.g.:
-</p>
-<pre class="code">
-jit.opt.start(2) -- same as -O2
-jit.opt.start("-dce")
-jit.opt.start("hotloop=10", "hotexit=2")
-</pre>
-<p>
-Unlike in LuaJIT 1.x, the module is built-in and
-<b>optimization is turned on by default!</b>
-It's no longer necessary to run <tt>require("jit.opt").start()</tt>,
-which was one of the ways to enable optimization.
-</p>
-
-<h2 id="jit_util"><tt>jit.util.*</tt> — JIT compiler introspection</h2>
-<p>
-This module holds functions to introspect the bytecode, generated
-traces, the IR and the generated machine code. The functionality
-provided by this module is still in flux and therefore undocumented.
-</p>
-<p>
-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>
-— 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 sub-functions of the function with
-<tt>LUAJIT_MODE_ALLFUNC</tt> or only to the sub-functions with
-<tt>LUAJIT_MODE_ALLSUBFUNC</tt>.
-</p>
-
-<h3 id="mode_trace"><tt>luaJIT_setmode(L, trace,<br>
- LUAJIT_MODE_TRACE|LUAJIT_MODE_FLUSH)</tt></h3>
-<p>
-Flushes the specified root trace and all of its side traces from the cache.
-The code for the trace will be retained as long as there are any other
-traces which link to it.
-</p>
-
-<h3 id="mode_wrapcfunc"><tt>luaJIT_setmode(L, idx, LUAJIT_MODE_WRAPCFUNC|flag)</tt></h3>
-<p>
-This mode defines a wrapper function for calls to C functions. If
-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. From now on all C functions are called through the wrapper
-function. If called with <tt>LUAJIT_MODE_OFF</tt> this mode is turned
-off and all C functions are directly called.
-</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 <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 myinit(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);
- ...
-}
-</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.
-</p>
-<p>
-LuaJIT already intercepts exception handling for systems using DWARF2
-stack unwinding (e.g. Linux or OSX) and for Windows/x64 (but <b>not</b>
-for Windows/x86). 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++ exception"</tt>.
-</p>
-<br class="flush">
-</div>
-<div id="foot">
-<hr class="hide">
-Copyright © 2005-2010 Mike Pall
-<span class="noprint">
-·
-<a href="contact.html">Contact</a>
-</span>
-</div>
-</body>
-</html>
diff --git a/doc/changes.html b/doc/changes.html
index 54f17a16..b7ac0734 100644
--- a/doc/changes.html
+++ b/doc/changes.html
@@ -26,8 +26,13 @@ div.major { max-width: 600px; padding: 1em; margin: 1em 0 1em 0; }
<a href="install.html">Installation</a>
</li><li>
<a href="running.html">Running</a>
+</li></ul>
+</li><li>
+<a href="extensions.html">Extensions</a>
+<ul><li>
+<a href="ext_jit.html">jit.* Library</a>
</li><li>
-<a href="api.html">API Extensions</a>
+<a href="ext_c_api.html">Lua/C API</a>
</li></ul>
</li><li>
<a href="status.html">Status</a>
diff --git a/doc/contact.html b/doc/contact.html
index afd17451..13175844 100644
--- a/doc/contact.html
+++ b/doc/contact.html
@@ -23,8 +23,13 @@
<a href="install.html">Installation</a>
</li><li>
<a href="running.html">Running</a>
+</li></ul>
+</li><li>
+<a href="extensions.html">Extensions</a>
+<ul><li>
+<a href="ext_jit.html">jit.* Library</a>
</li><li>
-<a href="api.html">API Extensions</a>
+<a href="ext_c_api.html">Lua/C API</a>
</li></ul>
</li><li>
<a href="status.html">Status</a>
diff --git a/doc/ext_c_api.html b/doc/ext_c_api.html
new file mode 100644
index 00000000..1418b2a9
--- /dev/null
+++ b/doc/ext_c_api.html
@@ -0,0 +1,174 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+<title>Lua/C API Extensions</title>
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+<meta name="Author" content="Mike Pall">
+<meta name="Copyright" content="Copyright (C) 2005-2010, Mike Pall">
+<meta name="Language" content="en">
+<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
+<link rel="stylesheet" type="text/css" href="bluequad-print.css" media="print">
+</head>
+<body>
+<div id="site">
+<a href="http://luajit.org"><span>Lua<span id="logo">JIT</span></span></a>
+</div>
+<div id="head">
+<h1>Lua/C API Extensions</h1>
+</div>
+<div id="nav">
+<ul><li>
+<a href="luajit.html">LuaJIT</a>
+<ul><li>
+<a href="install.html">Installation</a>
+</li><li>
+<a href="running.html">Running</a>
+</li></ul>
+</li><li>
+<a href="extensions.html">Extensions</a>
+<ul><li>
+<a href="ext_jit.html">jit.* Library</a>
+</li><li>
+<a class="current" href="ext_c_api.html">Lua/C API</a>
+</li></ul>
+</li><li>
+<a href="status.html">Status</a>
+<ul><li>
+<a href="changes.html">Changes</a>
+</li></ul>
+</li><li>
+<a href="faq.html">FAQ</a>
+</li><li>
+<a href="http://luajit.org/performance.html">Performance <span class="ext">»</span></a>
+</li><li>
+<a href="http://luajit.org/download.html">Download <span class="ext">»</span></a>
+</li></ul>
+</div>
+<div id="main">
+<p>
+LuaJIT adds some extensions to the standard 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>
+— 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 sub-functions of the function with
+<tt>LUAJIT_MODE_ALLFUNC</tt> or only to the sub-functions with
+<tt>LUAJIT_MODE_ALLSUBFUNC</tt>.
+</p>
+
+<h3 id="mode_trace"><tt>luaJIT_setmode(L, trace,<br>
+ LUAJIT_MODE_TRACE|LUAJIT_MODE_FLUSH)</tt></h3>
+<p>
+Flushes the specified root trace and all of its side traces from the cache.
+The code for the trace will be retained as long as there are any other
+traces which link to it.
+</p>
+
+<h3 id="mode_wrapcfunc"><tt>luaJIT_setmode(L, idx, LUAJIT_MODE_WRAPCFUNC|flag)</tt></h3>
+<p>
+This mode defines a wrapper function for calls to C functions. If
+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. From now on all C functions are called through the wrapper
+function. If called with <tt>LUAJIT_MODE_OFF</tt> this mode is turned
+off and all C functions are directly called.
+</p>
+<p>
+The wrapper function can be used for debugging purposes or to catch
+and convert foreign exceptions. But please read the section on
+<a href="extensions.html#exceptions">C++ exception interoperability</a>
+first. Recommended usage can be seen in this C++ code excerpt:
+</p>
+<pre class="code">
+#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 myinit(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);
+ ...
+}
+</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.
+</p>
+<br class="flush">
+</div>
+<div id="foot">
+<hr class="hide">
+Copyright © 2005-2010 Mike Pall
+<span class="noprint">
+·
+<a href="contact.html">Contact</a>
+</span>
+</div>
+</body>
+</html>
diff --git a/doc/ext_jit.html b/doc/ext_jit.html
new file mode 100644
index 00000000..d621476b
--- /dev/null
+++ b/doc/ext_jit.html
@@ -0,0 +1,177 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+<title>jit.* Library</title>
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+<meta name="Author" content="Mike Pall">
+<meta name="Copyright" content="Copyright (C) 2005-2010, Mike Pall">
+<meta name="Language" content="en">
+<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
+<link rel="stylesheet" type="text/css" href="bluequad-print.css" media="print">
+</head>
+<body>
+<div id="site">
+<a href="http://luajit.org"><span>Lua<span id="logo">JIT</span></span></a>
+</div>
+<div id="head">
+<h1><tt>jit.*</tt> Library</h1>
+</div>
+<div id="nav">
+<ul><li>
+<a href="luajit.html">LuaJIT</a>
+<ul><li>
+<a href="install.html">Installation</a>
+</li><li>
+<a href="running.html">Running</a>
+</li></ul>
+</li><li>
+<a href="extensions.html">Extensions</a>
+<ul><li>
+<a class="current" href="ext_jit.html">jit.* Library</a>
+</li><li>
+<a href="ext_c_api.html">Lua/C API</a>
+</li></ul>
+</li><li>
+<a href="status.html">Status</a>
+<ul><li>
+<a href="changes.html">Changes</a>
+</li></ul>
+</li><li>
+<a href="faq.html">FAQ</a>
+</li><li>
+<a href="http://luajit.org/performance.html">Performance <span class="ext">»</span></a>
+</li><li>
+<a href="http://luajit.org/download.html">Download <span class="ext">»</span></a>
+</li></ul>
+</div>
+<div id="main">
+<p>
+The functions in this built-in module control the behavior
+of the JIT compiler engine.
+</p>
+
+<h3 id="jit_onoff"><tt>jit.on()<br>
+jit.off()</tt></h3>
+<p>
+Turns the whole JIT compiler on (default) or off.
+</p>
+<p>
+These functions are typically used with the command line options
+<tt>-j on</tt> or <tt>-j off</tt>.
+</p>
+
+<h3 id="jit_flush"><tt>jit.flush()</tt></h3>
+<p>
+Flushes the whole cache of compiled code.
+</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>
+<p>
+<tt>jit.on</tt> enables JIT compilation for a Lua function (this is
+the default).
+</p>
+<p>
+<tt>jit.off</tt> disables JIT compilation for a Lua function and
+flushes any already compiled code from the code cache.
+</p>
+<p>
+<tt>jit.flush</tt> flushes the code, but doesn't affect the
+enable/disable status.
+</p>
+<p>
+The current function, i.e. the Lua function calling this library
+function, can also be specified by passing <tt>true</tt> as the first
+argument.
+</p>
+<p>
+If the second argument is <tt>true</tt>, JIT compilation is also
+enabled, disabled or flushed recursively for all sub-functions of a
+function. With <tt>false</tt> only the sub-functions are affected.
+</p>
+<p>
+The <tt>jit.on</tt> and <tt>jit.off</tt> functions only set a flag
+which is checked when the function is about to be compiled. They do
+not trigger immediate compilation.
+</p>
+<p>
+Typical usage is <tt>jit.off(true, true)</tt> in the main chunk
+of a module to turn off JIT compilation for the whole module for
+debugging purposes.
+</p>
+
+<h3 id="jit_flush_tr"><tt>jit.flush(tr)</tt></h3>
+<p>
+Flushes the specified root trace and all of its side traces from the cache.
+The code for the trace will be retained as long as there are any other
+traces which link to it.
+</p>
+
+<h3 id="jit_status"><tt>status, ... = jit.status()</tt></h3>
+<p>
+Returns the current status of the JIT compiler. The first result is
+either <tt>true</tt> or <tt>false</tt> if the JIT compiler is turned
+on or off. The remaining results are strings for CPU-specific features
+and enabled optimizations.
+</p>
+
+<h3 id="jit_version"><tt>jit.version</tt></h3>
+<p>
+Contains the LuaJIT version string.
+</p>
+
+<h3 id="jit_version_num"><tt>jit.version_num</tt></h3>
+<p>
+Contains the version number of the LuaJIT core. Version xx.yy.zz
+is represented by the decimal number xxyyzz.
+</p>
+
+<h3 id="jit_arch"><tt>jit.arch</tt></h3>
+<p>
+Contains the target architecture name (CPU and optional ABI).
+</p>
+
+<h2 id="jit_opt"><tt>jit.opt.*</tt> — JIT compiler optimization control</h2>
+<p>
+This sub-module provides the backend for the <tt>-O</tt> command line
+option.
+</p>
+<p>
+You can also use it programmatically, e.g.:
+</p>
+<pre class="code">
+jit.opt.start(2) -- same as -O2
+jit.opt.start("-dce")
+jit.opt.start("hotloop=10", "hotexit=2")
+</pre>
+<p>
+Unlike in LuaJIT 1.x, the module is built-in and
+<b>optimization is turned on by default!</b>
+It's no longer necessary to run <tt>require("jit.opt").start()</tt>,
+which was one of the ways to enable optimization.
+</p>
+
+<h2 id="jit_util"><tt>jit.util.*</tt> — JIT compiler introspection</h2>
+<p>
+This sub-module holds functions to introspect the bytecode, generated
+traces, the IR and the generated machine code. The functionality
+provided by this module is still in flux and therefore undocumented.
+</p>
+<p>
+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>
+<br class="flush">
+</div>
+<div id="foot">
+<hr class="hide">
+Copyright © 2005-2010 Mike Pall
+<span class="noprint">
+·
+<a href="contact.html">Contact</a>
+</span>
+</div>
+</body>
+</html>
diff --git a/doc/extensions.html b/doc/extensions.html
new file mode 100644
index 00000000..e302952d
--- /dev/null
+++ b/doc/extensions.html
@@ -0,0 +1,303 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+<title>Extensions</title>
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+<meta name="Author" content="Mike Pall">
+<meta name="Copyright" content="Copyright (C) 2005-2010, Mike Pall">
+<meta name="Language" content="en">
+<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
+<link rel="stylesheet" type="text/css" href="bluequad-print.css" media="print">
+<style type="text/css">
+table.exc {
+ line-height: 1.2;
+}
+tr.exchead td {
+ font-weight: bold;
+}
+td.excplatform {
+ width: 48%;
+}
+td.exccompiler {
+ width: 29%;
+}
+td.excinterop {
+ width: 23%;
+}
+</style>
+</head>
+<body>
+<div id="site">
+<a href="http://luajit.org"><span>Lua<span id="logo">JIT</span></span></a>
+</div>
+<div id="head">
+<h1>Extensions</h1>
+</div>
+<div id="nav">
+<ul><li>
+<a href="luajit.html">LuaJIT</a>
+<ul><li>
+<a href="install.html">Installation</a>
+</li><li>
+<a href="running.html">Running</a>
+</li></ul>
+</li><li>
+<a class="current" href="extensions.html">Extensions</a>
+<ul><li>
+<a href="ext_jit.html">jit.* Library</a>
+</li><li>
+<a href="ext_c_api.html">Lua/C API</a>
+</li></ul>
+</li><li>
+<a href="status.html">Status</a>
+<ul><li>
+<a href="changes.html">Changes</a>
+</li></ul>
+</li><li>
+<a href="faq.html">FAQ</a>
+</li><li>
+<a href="http://luajit.org/performance.html">Performance <span class="ext">»</span></a>
+</li><li>
+<a href="http://luajit.org/download.html">Download <span class="ext">»</span></a>
+</li></ul>
+</div>
+<div id="main">
+<p>
+LuaJIT is fully upwards-compatible with Lua 5.1. It supports all
+<a href="http://www.lua.org/manual/5.1/manual.html#5"><span class="ext">»</span> standard Lua
+library functions</a> and the full set of
+<a href="http://www.lua.org/manual/5.1/manual.html#3"><span class="ext">»</span> Lua/C API
+functions</a>.
+</p>
+<p>
+LuaJIT is also fully ABI-compatible to Lua 5.1 at the linker/dynamic
+loader level. This means you can compile a C module against the
+standard Lua headers and load the same shared library from either Lua
+or LuaJIT.
+</p>
+<p>
+LuaJIT extends the standard Lua VM with new functionality and adds
+several extension modules. Please note that this page is only about
+<em>functional</em> enhancements and not about performance enhancements,
+such as the optimized VM, the faster interpreter or the JIT compiler.
+</p>
+
+<h2 id="modules">Extensions Modules</h2>
+<p>
+LuaJIT comes with several built-in extension modules:
+</p>
+
+<h3 id="bit"><tt>bit.*</tt> — Bitwise operations</h3>
+<p>
+LuaJIT supports all bitwise operations as defined by
+<a href="http://bitop.luajit.org"><span class="ext">»</span> Lua BitOp</a>:
+</p>
+<pre class="code">
+bit.tobit bit.tohex bit.bnot bit.band bit.bor bit.bxor
+bit.lshift bit.rshift bit.arshift bit.rol bit.ror bit.bswap
+</pre>
+<p>
+This module is a LuaJIT built-in — you don't need to download or
+install Lua BitOp. The Lua BitOp site has full documentation for all
+<a href="http://bitop.luajit.org/api.html"><span class="ext">»</span> Lua BitOp API functions</a>.
+</p>
+<p>
+Please make sure to <tt>require</tt> the module before using any of
+its functions:
+</p>
+<pre class="code">
+local bit = require("bit")
+</pre>
+<p>
+An already installed Lua BitOp module is ignored by LuaJIT.
+This way you can use bit operations from both Lua and LuaJIT on a
+shared installation.
+</p>
+
+<h3 id="jit"><tt>jit.*</tt> — JIT compiler control</h3>
+<p>
+The functions in this module
+<a href="ext_jit.html">control the behavior of the JIT compiler engine</a>.
+</p>
+
+<h3 id="c_api">C API extensions</h3>
+<p>
+LuaJIT adds some
+<a href="ext_c_api.html">extra functions to the Lua/C API</a>.
+</p>
+
+<h2 id="library">Enhanced Standard Library Functions</h2>
+
+<h3 id="xpcall"><tt>xpcall(f, err [,args...])</tt> passes arguments</h3>
+<p>
+Unlike the standard implementation in Lua 5.1, <tt>xpcall()</tt>
+passes any arguments after the error function to the function
+which is called in a protected context.
+</p>
+
+<h3 id="load"><tt>loadfile()</tt> etc. handle UTF-8 source code</h3>
+<p>
+Non-ASCII characters are handled transparently by the Lua source code parser.
+This allows the use of UTF-8 characters in identifiers and strings.
+A UTF-8 BOM is skipped at the start of the source code.
+</p>
+
+<h3 id="tostring"><tt>tostring()</tt> etc. canonicalize NaN and ±Inf</h3>
+<p>
+All number-to-string conversions consistently convert non-finite numbers
+to the same strings on all platforms. NaN results in <tt>"nan"</tt>,
+positive infinity results in <tt>"inf"</tt> and negative infinity results
+in <tt>"-inf"</tt>.
+</p>
+
+<h3 id="math_random">Enhanced PRNG for <tt>math.random()</tt></h3>
+<p>
+LuaJIT uses a Tausworthe PRNG with period 2^223 to implement
+<tt>math.random()</tt> and <tt>math.randomseed()</tt>. The quality of
+the PRNG results is much superior compared to the standard Lua
+implementation which uses the platform-specific ANSI rand().
+</p>
+<p>
+The PRNG generates the same sequences from the same seeds on all
+platforms and makes use of all bits in the seed argument.
+<tt>math.random()</tt> without arguments generates 52 pseudo-random bits
+for every call. The result is uniformly distributed between 0 and 1.
+It's correctly scaled up and rounded for <tt>math.random(n [,m])</tt> to
+preserve uniformity.
+</p>
+
+<h3 id="io"><tt>io.*</tt> functions handle 64 bit file offsets</h3>
+<p>
+The file I/O functions in the standard <tt>io.*</tt> library handle
+64 bit file offsets. In particular this means it's possible
+to open files larger than 2 Gigabytes and to reposition or obtain
+the current file position for offsets beyond 2 GB
+(<tt>fp:seek()</tt> method).
+</p>
+
+<h3 id="debug_meta"><tt>debug.*</tt> functions identify metamethods</h3>
+<p>
+<tt>debug.getinfo()</tt> and <tt>lua_getinfo()</tt> also return information
+about invoked metamethods. The <tt>namewhat</tt> field is set to
+<tt>"metamethod"</tt> and the <tt>name</tt> field has the name of
+the corresponding metamethod (e.g. <tt>"__index"</tt>).
+</p>
+
+<h2 id="resumable">Fully Resumable VM</h2>
+<p>
+The LuaJIT 2.x VM is fully resumable. This means you can yield from a
+coroutine even across contexts, where this would not possible with
+the standard Lua 5.1 VM: e.g. you can yield across <tt>pcall()</tt>
+and <tt>xpcall()</tt>, across iterators and across metamethods.
+</p>
+<p>
+Note however that LuaJIT 2.x doesn't use
+<a href="http://coco.luajit.org/"><span class="ext">»</span> Coco</a> anymore. This means the
+overhead for creating coroutines is much smaller and no extra
+C stacks need to be allocated. OTOH you can no longer yield
+across arbitrary C functions. Keep this in mind when
+upgrading from LuaJIT 1.x.
+</p>
+
+<h2 id="exceptions">C++ Exception Interoperability</h2>
+<p>
+LuaJIT has built-in support for interoperating with C++ exceptions.
+The available range of features depends on the target platform and
+the toolchain used to compile LuaJIT:
+</p>
+<table class="exc">
+<tr class="exchead">
+<td class="excplatform">Platform</td>
+<td class="exccompiler">Compiler</td>
+<td class="excinterop">Interoperability</td>
+</tr>
+<tr class="odd separate">
+<td class="excplatform">POSIX/x64, DWARF2 unwinding</td>
+<td class="exccompiler">GCC 4.3+</td>
+<td class="excinterop"><b style="color: #00a000;">Full</td>
+</tr>
+<tr class="even">
+<td class="excplatform">Other platforms, DWARF2 unwinding</td>
+<td class="exccompiler">GCC</td>
+<td class="excinterop"><b style="color: #c06000;">Limited</b></td>
+</tr>
+<tr class="odd">
+<td class="excplatform">Windows/x64</td>
+<td class="exccompiler">MSVC or WinSDK</td>
+<td class="excinterop"><b style="color: #00a000;">Full</td>
+</tr>
+<tr class="even">
+<td class="excplatform">Windows/x86</td>
+<td class="exccompiler">Any</td>
+<td class="excinterop"><b style="color: #a00000;">No</b></td>
+</tr>
+<tr class="odd">
+<td class="excplatform">Other platforms</td>
+<td class="exccompiler">Other compilers</td>
+<td class="excinterop"><b style="color: #a00000;">No</b></td>
+</tr>
+</table>
+<p>
+<b style="color: #00a000;">Full interoperability</b> means:
+</p>
+<ul>
+<li>C++ exceptions can be caught on the Lua side with <tt>pcall()</tt>,
+<tt>lua_pcall()</tt> etc.</li>
+<li>C++ exceptions will be converted to the generic Lua error
+<tt>"C++ exception"</tt>, unless you use the
+<a href="ext_c_api.html#mode_wrapcfunc">C call wrapper</a> feature.</li>
+<li>It's safe to throw C++ exceptions across non-protected Lua frames
+on the C stack. The contents of the C++ exception object
+pass through unmodified.</li>
+<li>Lua errors can be caught on the C++ side with <tt>catch(...)</tt>.
+The corresponding Lua error message can be retrieved from the Lua stack.</li>
+<li>Throwing Lua errors across C++ frames is safe. C++ destructors
+will be called.</li>
+</ul>
+<p>
+<b style="color: #c06000;">Limited interoperability</b> means:
+</p>
+<ul>
+<li>C++ exceptions can be caught on the Lua side with <tt>pcall()</tt>,
+<tt>lua_pcall()</tt> etc.</li>
+<li>C++ exceptions will be converted to the generic Lua error
+<tt>"C++ exception"</tt>, unless you use the
+<a href="ext_c_api.html#mode_wrapcfunc">C call wrapper</a> feature.</li>
+<li>C++ exceptions will be caught by non-protected Lua frames and
+are rethrown as a generic Lua error. The C++ exception object will
+be destroyed.</li>
+<li>Lua errors <b>cannot</b> be caught on the C++ side.</li>
+<li>Throwing Lua errors across C++ frames will <b>not</b> call
+C++ destructors.</li>
+</ul>
+
+<p>
+<b style="color: #a00000;">No interoperability</b> means:
+</p>
+<ul>
+<li>It's <b>not</b> safe to throw C++ exceptions across Lua frames.</li>
+<li>C++ exceptions <b>cannot</b> be caught on the Lua side.</li>
+<li>Lua errors <b>cannot</b> be caught on the C++ side.</li>
+<li>Throwing Lua errors across C++ frames will <b>not</b> call
+C++ destructors.</li>
+<li>Additionally, on Windows/x86 with SEH-based C++ exceptions:
+it's <b>not</b> safe to throw a Lua error across any frames containing
+a C++ function with any try/catch construct or using variables with
+(implicit) destructors. This also applies to any functions which may be
+inlined in such a function. It doesn't matter whether <tt>lua_error()</tt>
+is called inside or outside of a try/catch or whether any object actually
+needs to be destroyed: the SEH chain is corrupted and this will eventually
+lead to the termination of the process.</li>
+</ul>
+<br class="flush">
+</div>
+<div id="foot">
+<hr class="hide">
+Copyright © 2005-2010 Mike Pall
+<span class="noprint">
+·
+<a href="contact.html">Contact</a>
+</span>
+</div>
+</body>
+</html>
diff --git a/doc/faq.html b/doc/faq.html
index 9404f788..c1d86db9 100644
--- a/doc/faq.html
+++ b/doc/faq.html
@@ -26,8 +26,13 @@ dd { margin-left: 1.5em; }
<a href="install.html">Installation</a>
</li><li>
<a href="running.html">Running</a>
+</li></ul>
+</li><li>
+<a href="extensions.html">Extensions</a>
+<ul><li>
+<a href="ext_jit.html">jit.* Library</a>
</li><li>
-<a href="api.html">API Extensions</a>
+<a href="ext_c_api.html">Lua/C API</a>
</li></ul>
</li><li>
<a href="status.html">Status</a>
diff --git a/doc/install.html b/doc/install.html
index 775b3470..9dac37a3 100644
--- a/doc/install.html
+++ b/doc/install.html
@@ -13,19 +13,19 @@ table.compat {
line-height: 1.2;
width: 600px;
}
-tr.compathead td {
+table.compat td {
+ border: 1px solid #bfcfff;
+ font-size: 90%;
+ height: 2.5em;
+}
+table.compat tr.compathead td {
font-weight: bold;
border-bottom: 2px solid #bfcfff;
}
tr.compathead td.compatos {
vertical-align: top;
}
-td {
- border: 1px solid #bfcfff;
- font-size: 90%;
- height: 2.5em;
-}
-td.compatcpu {
+table.compat td.compatcpu {
width: 16%;
border-right: 2px solid #bfcfff;
}
@@ -52,8 +52,13 @@ td.compatno {
<a class="current" href="install.html">Installation</a>
</li><li>
<a href="running.html">Running</a>
+</li></ul>
+</li><li>
+<a href="extensions.html">Extensions</a>
+<ul><li>
+<a href="ext_jit.html">jit.* Library</a>
</li><li>
-<a href="api.html">API Extensions</a>
+<a href="ext_c_api.html">Lua/C API</a>
</li></ul>
</li><li>
<a href="status.html">Status</a>
diff --git a/doc/luajit.html b/doc/luajit.html
index 71e6a19f..990cd630 100644
--- a/doc/luajit.html
+++ b/doc/luajit.html
@@ -24,8 +24,13 @@
<a href="install.html">Installation</a>
</li><li>
<a href="running.html">Running</a>
+</li></ul>
+</li><li>
+<a href="extensions.html">Extensions</a>
+<ul><li>
+<a href="ext_jit.html">jit.* Library</a>
</li><li>
-<a href="api.html">API Extensions</a>
+<a href="ext_c_api.html">Lua/C API</a>
</li></ul>
</li><li>
<a href="status.html">Status</a>
diff --git a/doc/running.html b/doc/running.html
index e337d535..6991ef7a 100644
--- a/doc/running.html
+++ b/doc/running.html
@@ -45,8 +45,13 @@ td.param_default {
<a href="install.html">Installation</a>
</li><li>
<a class="current" href="running.html">Running</a>
+</li></ul>
+</li><li>
+<a href="extensions.html">Extensions</a>
+<ul><li>
+<a href="ext_jit.html">jit.* Library</a>
</li><li>
-<a href="api.html">API Extensions</a>
+<a href="ext_c_api.html">Lua/C API</a>
</li></ul>
</li><li>
<a href="status.html">Status</a>
diff --git a/doc/status.html b/doc/status.html
index a508dca1..15e114c2 100644
--- a/doc/status.html
+++ b/doc/status.html
@@ -26,8 +26,13 @@ ul li { padding-bottom: 0.3em; }
<a href="install.html">Installation</a>
</li><li>
<a href="running.html">Running</a>
+</li></ul>
+</li><li>
+<a href="extensions.html">Extensions</a>
+<ul><li>
+<a href="ext_jit.html">jit.* Library</a>
</li><li>
-<a href="api.html">API Extensions</a>
+<a href="ext_c_api.html">Lua/C API</a>
</li></ul>
</li><li>
<a class="current" href="status.html">Status</a>
--
cgit v1.2.3-55-g6feb