mirror of
https://github.com/LuaJIT/LuaJIT.git
synced 2025-02-07 15:14:08 +00:00
322 lines
11 KiB
HTML
322 lines
11 KiB
HTML
<!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-2011, 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_ffi.html">FFI Library</a>
|
|
<ul><li>
|
|
<a href="ext_ffi_tutorial.html">FFI Tutorial</a>
|
|
</li><li>
|
|
<a href="ext_ffi_api.html">ffi.* API</a>
|
|
</li><li>
|
|
<a href="ext_ffi_int64.html">64 bit Integers</a>
|
|
</li><li>
|
|
<a href="ext_ffi_semantics.html">FFI Semantics</a>
|
|
</li></ul>
|
|
</li><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="ffi"><tt>ffi.*</tt> — FFI library</h3>
|
|
<p>
|
|
The <a href="ext_ffi.html">FFI library</a> allows calling external
|
|
C functions and the use of C data structures from pure Lua
|
|
code.
|
|
</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</b></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</b></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-2011 Mike Pall
|
|
<span class="noprint">
|
|
·
|
|
<a href="contact.html">Contact</a>
|
|
</span>
|
|
</div>
|
|
</body>
|
|
</html>
|