|
|
@@ -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>
|
Mike Pall