1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
4
<title>Extensions</title>
5
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
6
<meta name="Author" content="Mike Pall">
7
<meta name="Copyright" content="Copyright (C) 2005-2013, Mike Pall">
8
<meta name="Language" content="en">
9
<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
10
<link rel="stylesheet" type="text/css" href="bluequad-print.css" media="print">
11
<style type="text/css">
31
<a href="http://luajit.org"><span>Lua<span id="logo">JIT</span></span></a>
38
<a href="luajit.html">LuaJIT</a>
40
<a href="http://luajit.org/download.html">Download <span class="ext">»</span></a>
42
<a href="install.html">Installation</a>
44
<a href="running.html">Running</a>
47
<a class="current" href="extensions.html">Extensions</a>
49
<a href="ext_ffi.html">FFI Library</a>
51
<a href="ext_ffi_tutorial.html">FFI Tutorial</a>
53
<a href="ext_ffi_api.html">ffi.* API</a>
55
<a href="ext_ffi_semantics.html">FFI Semantics</a>
58
<a href="ext_jit.html">jit.* Library</a>
60
<a href="ext_c_api.html">Lua/C API</a>
63
<a href="status.html">Status</a>
65
<a href="changes.html">Changes</a>
68
<a href="faq.html">FAQ</a>
70
<a href="http://luajit.org/performance.html">Performance <span class="ext">»</span></a>
72
<a href="http://wiki.luajit.org/">Wiki <span class="ext">»</span></a>
74
<a href="http://luajit.org/list.html">Mailing List <span class="ext">»</span></a>
79
LuaJIT is fully upwards-compatible with Lua 5.1. It supports all
80
<a href="http://www.lua.org/manual/5.1/manual.html#5"><span class="ext">»</span> standard Lua
81
library functions</a> and the full set of
82
<a href="http://www.lua.org/manual/5.1/manual.html#3"><span class="ext">»</span> Lua/C API
86
LuaJIT is also fully ABI-compatible to Lua 5.1 at the linker/dynamic
87
loader level. This means you can compile a C module against the
88
standard Lua headers and load the same shared library from either Lua
92
LuaJIT extends the standard Lua VM with new functionality and adds
93
several extension modules. Please note this page is only about
94
<em>functional</em> enhancements and not about performance enhancements,
95
such as the optimized VM, the faster interpreter or the JIT compiler.
98
<h2 id="modules">Extensions Modules</h2>
100
LuaJIT comes with several built-in extension modules:
103
<h3 id="bit"><tt>bit.*</tt> — Bitwise operations</h3>
105
LuaJIT supports all bitwise operations as defined by
106
<a href="http://bitop.luajit.org"><span class="ext">»</span> Lua BitOp</a>:
109
bit.tobit bit.tohex bit.bnot bit.band bit.bor bit.bxor
110
bit.lshift bit.rshift bit.arshift bit.rol bit.ror bit.bswap
113
This module is a LuaJIT built-in — you don't need to download or
114
install Lua BitOp. The Lua BitOp site has full documentation for all
115
<a href="http://bitop.luajit.org/api.html"><span class="ext">»</span> Lua BitOp API functions</a>.
118
Please make sure to <tt>require</tt> the module before using any of
122
local bit = require("bit")
125
An already installed Lua BitOp module is ignored by LuaJIT.
126
This way you can use bit operations from both Lua and LuaJIT on a
130
<h3 id="ffi"><tt>ffi.*</tt> — FFI library</h3>
132
The <a href="ext_ffi.html">FFI library</a> allows calling external
133
C functions and the use of C data structures from pure Lua
137
<h3 id="jit"><tt>jit.*</tt> — JIT compiler control</h3>
139
The functions in this module
140
<a href="ext_jit.html">control the behavior of the JIT compiler engine</a>.
143
<h3 id="c_api">C API extensions</h3>
146
<a href="ext_c_api.html">extra functions to the Lua/C API</a>.
149
<h2 id="library">Enhanced Standard Library Functions</h2>
151
<h3 id="xpcall"><tt>xpcall(f, err [,args...])</tt> passes arguments</h3>
153
Unlike the standard implementation in Lua 5.1, <tt>xpcall()</tt>
154
passes any arguments after the error function to the function
155
which is called in a protected context.
158
<h3 id="load"><tt>loadfile()</tt> etc. handle UTF-8 source code</h3>
160
Non-ASCII characters are handled transparently by the Lua source code parser.
161
This allows the use of UTF-8 characters in identifiers and strings.
162
A UTF-8 BOM is skipped at the start of the source code.
165
<h3 id="tostring"><tt>tostring()</tt> etc. canonicalize NaN and ±Inf</h3>
167
All number-to-string conversions consistently convert non-finite numbers
168
to the same strings on all platforms. NaN results in <tt>"nan"</tt>,
169
positive infinity results in <tt>"inf"</tt> and negative infinity results
173
<h3 id="tonumber"><tt>tonumber()</tt> etc. use builtin string to number conversion</h3>
175
All string-to-number conversions consistently convert integer and
176
floating-point inputs in decimal and hexadecimal on all platforms.
177
<tt>strtod()</tt> is <em>not</em> used anymore, which avoids numerous
178
problems with poor C library implementations. The builtin conversion
179
function provides full precision according to the IEEE-754 standard, it
180
works independently of the current locale and it supports hex floating-point
181
numbers (e.g. <tt>0x1.5p-3</tt>).
184
<h3 id="string_dump"><tt>string.dump(f [,strip])</tt> generates portable bytecode</h3>
186
An extra argument has been added to <tt>string.dump()</tt>. If set to
187
<tt>true</tt>, 'stripped' bytecode without debug information is
188
generated. This speeds up later bytecode loading and reduces memory
190
<a href="running.html#opt_b"><tt>-b</tt> command line option</a>.
193
The generated bytecode is portable and can be loaded on any architecture
194
that LuaJIT supports, independent of word size or endianess. However the
195
bytecode compatibility versions must match. Bytecode stays compatible
196
for dot releases (x.y.0 → x.y.1), but may change with major or
197
minor releases (2.0 → 2.1) or between any beta release. Foreign
198
bytecode (e.g. from Lua 5.1) is incompatible and cannot be loaded.
201
<h3 id="math_random">Enhanced PRNG for <tt>math.random()</tt></h3>
203
LuaJIT uses a Tausworthe PRNG with period 2^223 to implement
204
<tt>math.random()</tt> and <tt>math.randomseed()</tt>. The quality of
205
the PRNG results is much superior compared to the standard Lua
206
implementation which uses the platform-specific ANSI rand().
209
The PRNG generates the same sequences from the same seeds on all
210
platforms and makes use of all bits in the seed argument.
211
<tt>math.random()</tt> without arguments generates 52 pseudo-random bits
212
for every call. The result is uniformly distributed between 0.0 and 1.0.
213
It's correctly scaled up and rounded for <tt>math.random(n [,m])</tt> to
217
<h3 id="io"><tt>io.*</tt> functions handle 64 bit file offsets</h3>
219
The file I/O functions in the standard <tt>io.*</tt> library handle
220
64 bit file offsets. In particular this means it's possible
221
to open files larger than 2 Gigabytes and to reposition or obtain
222
the current file position for offsets beyond 2 GB
223
(<tt>fp:seek()</tt> method).
226
<h3 id="debug_meta"><tt>debug.*</tt> functions identify metamethods</h3>
228
<tt>debug.getinfo()</tt> and <tt>lua_getinfo()</tt> also return information
229
about invoked metamethods. The <tt>namewhat</tt> field is set to
230
<tt>"metamethod"</tt> and the <tt>name</tt> field has the name of
231
the corresponding metamethod (e.g. <tt>"__index"</tt>).
234
<h2 id="resumable">Fully Resumable VM</h2>
236
The LuaJIT VM is fully resumable. This means you can yield from a
237
coroutine even across contexts, where this would not possible with
238
the standard Lua 5.1 VM: e.g. you can yield across <tt>pcall()</tt>
239
and <tt>xpcall()</tt>, across iterators and across metamethods.
242
<h2 id="lua52">Extensions from Lua 5.2</h2>
244
LuaJIT supports some language and library extensions from Lua 5.2.
245
Features that are unlikely to break existing code are unconditionally
249
<li><tt>goto</tt> and <tt>::labels::</tt>.</li>
250
<li>Hex escapes <tt>'\x3F'</tt> and <tt>'\*'</tt> escape in strings.</li>
251
<li><tt>load(string|reader [, chunkname [,mode [,env]]])</tt>.</li>
252
<li><tt>loadstring()</tt> is an alias for <tt>load()</tt>.</li>
253
<li><tt>loadfile(filename [,mode [,env]])</tt>.</li>
254
<li><tt>math.log(x [,base])</tt>.
255
<li><tt>string.rep(s, n [,sep])</tt>.
256
<li><tt>string.format()</tt>: <tt>%q</tt> reversible.
257
<tt>%s</tt> checks <tt>__tostring</tt>.
258
<tt>%a</tt> and <tt>"%A</tt> added.</li>
259
<li>String matching pattern <tt>%g</tt> added.</li>
260
<li><tt>io.read("*L")</tt>.</li>
261
<li><tt>io.lines()</tt> and <tt>file:lines()</tt> process
262
<tt>io.read()</tt> options.</li>
263
<li><tt>os.exit(status|true|false [,close])</tt>.</li>
264
<li><tt>package.searchpath(name, path [, sep [, rep]])</tt>.</li>
265
<li><tt>package.loadlib(name, "*")</tt>.</li>
266
<li><tt>debug.getinfo()</tt> returns <tt>nparams</tt> and <tt>isvararg</tt>
267
for option <tt>"u"</tt>.</li>
268
<li><tt>debug.getlocal()</tt> accepts function instead of level.</li>
269
<li><tt>debug.getlocal()</tt> and <tt>debug.setlocal()</tt> accept negative
270
indexes for varargs.</li>
271
<li><tt>debug.getupvalue()</tt> and <tt>debug.setupvalue()</tt> handle
272
C functions.</li>
273
<li><tt>debug.upvalueid()</tt> and <tt>debug.upvaluejoin()</tt>.</li>
274
<li>Command line option <tt>-E</tt>.</li>
275
<li>Command line checks <tt>__tostring</tt> for errors.</li>
278
Other features are only enabled, if LuaJIT is built with
279
<tt>-DLUAJIT_ENABLE_LUA52COMPAT</tt>:
282
<li><tt>goto</tt> is a keyword and not a valid variable name anymore.</li>
283
<li><tt>break</tt> can be placed anywhere. Empty statements (<tt>;;</tt>)
285
<li><tt>__lt</tt>, <tt>__le</tt> are invoked for mixed types.</li>
286
<li><tt>__len</tt> for tables. <tt>rawlen()</tt> library function.</li>
287
<li><tt>pairs()</tt> and <tt>ipairs()</tt> check for <tt>__pairs</tt> and
288
<tt>__ipairs</tt>.</li>
289
<li><tt>coroutine.running()</tt> returns two results.</li>
290
<li><tt>table.pack()</tt> and <tt>table.unpack()</tt>
291
(same as <tt>unpack()</tt>).</li>
292
<li><tt>io.write()</tt> and <tt>file:write()</tt> return file handle
293
instead of <tt>true</tt>.</li>
294
<li><tt>os.execute()</tt> and <tt>pipe:close()</tt> return detailed
296
<li><tt>debug.setmetatable()</tt> returns object.</li>
297
<li><tt>debug.getuservalue()</tt> and <tt>debug.setuservalue()</tt>.</li>
298
<li>Remove <tt>math.mod()</tt>, <tt>string.gfind()</tt>.
301
Note: this provides only partial compatibility with Lua 5.2 at the
302
language and Lua library level. LuaJIT is API+ABI-compatible with
303
Lua 5.1, which prevents implementing features that would otherwise
304
break the Lua/C API and ABI (e.g. <tt>_ENV</tt>).
307
<h2 id="exceptions">C++ Exception Interoperability</h2>
309
LuaJIT has built-in support for interoperating with C++ exceptions.
310
The available range of features depends on the target platform and
311
the toolchain used to compile LuaJIT:
315
<td class="excplatform">Platform</td>
316
<td class="exccompiler">Compiler</td>
317
<td class="excinterop">Interoperability</td>
319
<tr class="odd separate">
320
<td class="excplatform">POSIX/x64, DWARF2 unwinding</td>
321
<td class="exccompiler">GCC 4.3+</td>
322
<td class="excinterop"><b style="color: #00a000;">Full</b></td>
325
<td class="excplatform">Other platforms, DWARF2 unwinding</td>
326
<td class="exccompiler">GCC</td>
327
<td class="excinterop"><b style="color: #c06000;">Limited</b></td>
330
<td class="excplatform">Windows/x64</td>
331
<td class="exccompiler">MSVC or WinSDK</td>
332
<td class="excinterop"><b style="color: #00a000;">Full</b></td>
335
<td class="excplatform">Windows/x86</td>
336
<td class="exccompiler">Any</td>
337
<td class="excinterop"><b style="color: #a00000;">No</b></td>
340
<td class="excplatform">Other platforms</td>
341
<td class="exccompiler">Other compilers</td>
342
<td class="excinterop"><b style="color: #a00000;">No</b></td>
346
<b style="color: #00a000;">Full interoperability</b> means:
349
<li>C++ exceptions can be caught on the Lua side with <tt>pcall()</tt>,
350
<tt>lua_pcall()</tt> etc.</li>
351
<li>C++ exceptions will be converted to the generic Lua error
352
<tt>"C++ exception"</tt>, unless you use the
353
<a href="ext_c_api.html#mode_wrapcfunc">C call wrapper</a> feature.</li>
354
<li>It's safe to throw C++ exceptions across non-protected Lua frames
355
on the C stack. The contents of the C++ exception object
356
pass through unmodified.</li>
357
<li>Lua errors can be caught on the C++ side with <tt>catch(...)</tt>.
358
The corresponding Lua error message can be retrieved from the Lua stack.</li>
359
<li>Throwing Lua errors across C++ frames is safe. C++ destructors
363
<b style="color: #c06000;">Limited interoperability</b> means:
366
<li>C++ exceptions can be caught on the Lua side with <tt>pcall()</tt>,
367
<tt>lua_pcall()</tt> etc.</li>
368
<li>C++ exceptions will be converted to the generic Lua error
369
<tt>"C++ exception"</tt>, unless you use the
370
<a href="ext_c_api.html#mode_wrapcfunc">C call wrapper</a> feature.</li>
371
<li>C++ exceptions will be caught by non-protected Lua frames and
372
are rethrown as a generic Lua error. The C++ exception object will
374
<li>Lua errors <b>cannot</b> be caught on the C++ side.</li>
375
<li>Throwing Lua errors across C++ frames will <b>not</b> call
376
C++ destructors.</li>
380
<b style="color: #a00000;">No interoperability</b> means:
383
<li>It's <b>not</b> safe to throw C++ exceptions across Lua frames.</li>
384
<li>C++ exceptions <b>cannot</b> be caught on the Lua side.</li>
385
<li>Lua errors <b>cannot</b> be caught on the C++ side.</li>
386
<li>Throwing Lua errors across C++ frames will <b>not</b> call
387
C++ destructors.</li>
388
<li>Additionally, on Windows/x86 with SEH-based C++ exceptions:
389
it's <b>not</b> safe to throw a Lua error across any frames containing
390
a C++ function with any try/catch construct or using variables with
391
(implicit) destructors. This also applies to any functions which may be
392
inlined in such a function. It doesn't matter whether <tt>lua_error()</tt>
393
is called inside or outside of a try/catch or whether any object actually
394
needs to be destroyed: the SEH chain is corrupted and this will eventually
395
lead to the termination of the process.</li>
401
Copyright © 2005-2013 Mike Pall
402
<span class="noprint">
404
<a href="contact.html">Contact</a>
added
removed
third-party/LuaJIT-2.0.2/doc/extensions.html
