478 lines
13 KiB
C
478 lines
13 KiB
C
=pod
|
|
|
|
LuaJIT
|
|
|
|
=head1 Extensions
|
|
|
|
=over
|
|
|
|
=item * LuaJIT
|
|
|
|
=over
|
|
|
|
=item * Download E<rchevron>
|
|
|
|
=item * Installation
|
|
|
|
=item * Running
|
|
|
|
=back
|
|
|
|
=item * Extensions
|
|
|
|
=over
|
|
|
|
=item * FFI Library
|
|
|
|
=over
|
|
|
|
=item * FFI Tutorial
|
|
|
|
=item * ffi.* API
|
|
|
|
=item * FFI Semantics
|
|
|
|
=back
|
|
|
|
=item * jit.* Library
|
|
|
|
=item * Lua/C API
|
|
|
|
=item * Profiler
|
|
|
|
=back
|
|
|
|
=item * Status
|
|
|
|
=over
|
|
|
|
=item * Changes
|
|
|
|
=back
|
|
|
|
=item * FAQ
|
|
|
|
=item * Performance E<rchevron>
|
|
|
|
=item * Wiki E<rchevron>
|
|
|
|
=item * Mailing List E<rchevron>
|
|
|
|
=back
|
|
|
|
LuaJIT is fully upwards-compatible with Lua 5.1. It supports all
|
|
E<rchevron> standard Lua library functions and the full set of
|
|
E<rchevron> Lua/C API functions.
|
|
|
|
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.
|
|
|
|
LuaJIT extends the standard Lua VM with new functionality and adds
|
|
several extension modules. Please note this page is only about
|
|
I<functional> enhancements and not about performance enhancements, such
|
|
as the optimized VM, the faster interpreter or the JIT compiler.
|
|
|
|
=head2 Extensions Modules
|
|
|
|
LuaJIT comes with several built-in extension modules:
|
|
|
|
=head2 C<bit.*> E<mdash> Bitwise operations
|
|
|
|
LuaJIT supports all bitwise operations as defined by E<rchevron> Lua
|
|
BitOp:
|
|
|
|
bit.tobit bit.tohex bit.bnot bit.band bit.bor bit.bxor
|
|
bit.lshift bit.rshift bit.arshift bit.rol bit.ror bit.bswap
|
|
|
|
This module is a LuaJIT built-in E<mdash> you don't need to download or
|
|
install Lua BitOp. The Lua BitOp site has full documentation for all
|
|
E<rchevron> Lua BitOp API functions. The FFI adds support for 64 bit
|
|
bitwise operations, using the same API functions.
|
|
|
|
Please make sure to C<require> the module before using any of its
|
|
functions:
|
|
|
|
local bit = require("bit")
|
|
|
|
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.
|
|
|
|
=head2 C<ffi.*> E<mdash> FFI library
|
|
|
|
The FFI library allows calling external C functions and the use of C
|
|
data structures from pure Lua code.
|
|
|
|
=head2 C<jit.*> E<mdash> JIT compiler control
|
|
|
|
The functions in this module control the behavior of the JIT compiler
|
|
engine.
|
|
|
|
=head2 C API extensions
|
|
|
|
LuaJIT adds some extra functions to the Lua/C API.
|
|
|
|
=head2 Profiler
|
|
|
|
LuaJIT has an integrated profiler.
|
|
|
|
=head2 Enhanced Standard Library Functions
|
|
|
|
=head2 C<xpcall(f, err [,args...])> passes arguments
|
|
|
|
Unlike the standard implementation in Lua 5.1, C<xpcall()> passes any
|
|
arguments after the error function to the function which is called in a
|
|
protected context.
|
|
|
|
=head2 C<loadfile()> etc. handle UTF-8 source code
|
|
|
|
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.
|
|
|
|
=head2 C<tostring()> etc. canonicalize NaN and E<plusmn>Inf
|
|
|
|
All number-to-string conversions consistently convert non-finite
|
|
numbers to the same strings on all platforms. NaN results in C<"nan">,
|
|
positive infinity results in C<"inf"> and negative infinity results in
|
|
C<"-inf">.
|
|
|
|
=head2 C<tonumber()> etc. use builtin string to number conversion
|
|
|
|
All string-to-number conversions consistently convert integer and
|
|
floating-point inputs in decimal, hexadecimal and binary on all
|
|
platforms. C<strtod()> is I<not> used anymore, which avoids numerous
|
|
problems with poor C library implementations. The builtin conversion
|
|
function provides full precision according to the IEEE-754 standard, it
|
|
works independently of the current locale and it supports hex
|
|
floating-point numbers (e.g. C<0x1.5p-3>).
|
|
|
|
=head2 C<string.dump(f [,strip])> generates portable bytecode
|
|
|
|
An extra argument has been added to C<string.dump()>. If set to
|
|
C<true>, 'stripped' bytecode without debug information is generated.
|
|
This speeds up later bytecode loading and reduces memory usage. See
|
|
also the C<-b> command line option.
|
|
|
|
The generated bytecode is portable and can be loaded on any
|
|
architecture that LuaJIT supports, independent of word size or
|
|
endianess. However the bytecode compatibility versions must match.
|
|
Bytecode stays compatible for dot releases (x.y.0 E<rarr> x.y.1), but
|
|
may change with major or minor releases (2.0 E<rarr> 2.1) or between
|
|
any beta release. Foreign bytecode (e.g. from Lua 5.1) is incompatible
|
|
and cannot be loaded.
|
|
|
|
Note: C<LJ_GC64> mode requires a different frame layout, which implies
|
|
a different, incompatible bytecode format for ports that use this mode
|
|
(e.g. ARM64 or MIPS64) or when explicitly enabled for x64. This may be
|
|
rectified in the future.
|
|
|
|
=head2 C<table.new(narray, nhash)> allocates a pre-sized table
|
|
|
|
An extra library function C<table.new()> can be made available via
|
|
C<require("table.new")>. This creates a pre-sized table, just like the
|
|
C API equivalent C<lua_createtable()>. This is useful for big tables if
|
|
the final table size is known and automatic table resizing is too
|
|
expensive.
|
|
|
|
=head2 C<table.clear(tab)> clears a table
|
|
|
|
An extra library function C<table.clear()> can be made available via
|
|
C<require("table.clear")>. This clears all keys and values from a
|
|
table, but preserves the allocated array/hash sizes. This is useful
|
|
when a table, which is linked from multiple places, needs to be cleared
|
|
and/or when recycling a table for use by the same context. This avoids
|
|
managing backlinks, saves an allocation and the overhead of incremental
|
|
array/hash part growth.
|
|
|
|
Please note this function is meant for very specific situations. In
|
|
most cases it's better to replace the (usually single) link with a new
|
|
table and let the GC do its work.
|
|
|
|
=head2 Enhanced PRNG for C<math.random()>
|
|
|
|
LuaJIT uses a Tausworthe PRNG with period 2^223 to implement
|
|
C<math.random()> and C<math.randomseed()>. The quality of the PRNG
|
|
results is much superior compared to the standard Lua implementation
|
|
which uses the platform-specific ANSI rand().
|
|
|
|
The PRNG generates the same sequences from the same seeds on all
|
|
platforms and makes use of all bits in the seed argument.
|
|
C<math.random()> without arguments generates 52 pseudo-random bits for
|
|
every call. The result is uniformly distributed between 0.0 and 1.0.
|
|
It's correctly scaled up and rounded for C<math.random(n [,m])> to
|
|
preserve uniformity.
|
|
|
|
=head2 C<io.*> functions handle 64 bit file offsets
|
|
|
|
The file I/O functions in the standard C<io.*> 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 (C<fp:seek()> method).
|
|
|
|
=head2 C<debug.*> functions identify metamethods
|
|
|
|
C<debug.getinfo()> and C<lua_getinfo()> also return information about
|
|
invoked metamethods. The C<namewhat> field is set to C<"metamethod">
|
|
and the C<name> field has the name of the corresponding metamethod
|
|
(e.g. C<"__index">).
|
|
|
|
=head2 Fully Resumable VM
|
|
|
|
The LuaJIT 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 C<pcall()> and
|
|
C<xpcall()>, across iterators and across metamethods.
|
|
|
|
=head2 Extensions from Lua 5.2
|
|
|
|
LuaJIT supports some language and library extensions from Lua 5.2.
|
|
Features that are unlikely to break existing code are unconditionally
|
|
enabled:
|
|
|
|
=over
|
|
|
|
=item * C<goto> and C<::labels::>.
|
|
|
|
=item * Hex escapes C<'\x3F'> and C<'\*'> escape in strings.
|
|
|
|
=item * C<load(string|reader [, chunkname [,mode [,env]]])>.
|
|
|
|
=item * C<loadstring()> is an alias for C<load()>.
|
|
|
|
=item * C<loadfile(filename [,mode [,env]])>.
|
|
|
|
=item * C<math.log(x [,base])>.
|
|
|
|
=item * C<string.rep(s, n [,sep])>.
|
|
|
|
=item * C<string.format()>: C<%q> reversible. C<%s> checks
|
|
C<__tostring>. C<%a> and C<"%A> added.
|
|
|
|
=item * String matching pattern C<%g> added.
|
|
|
|
=item * C<io.read("*L")>.
|
|
|
|
=item * C<io.lines()> and C<file:lines()> process C<io.read()> options.
|
|
|
|
=item * C<os.exit(status|true|false [,close])>.
|
|
|
|
=item * C<package.searchpath(name, path [, sep [, rep]])>.
|
|
|
|
=item * C<package.loadlib(name, "*")>.
|
|
|
|
=item * C<debug.getinfo()> returns C<nparams> and C<isvararg> for
|
|
option C<"u">.
|
|
|
|
=item * C<debug.getlocal()> accepts function instead of level.
|
|
|
|
=item * C<debug.getlocal()> and C<debug.setlocal()> accept negative
|
|
indexes for varargs.
|
|
|
|
=item * C<debug.getupvalue()> and C<debug.setupvalue()> handle C
|
|
functions.
|
|
|
|
=item * C<debug.upvalueid()> and C<debug.upvaluejoin()>.
|
|
|
|
=item * Lua/C API extensions: C<lua_version()> C<lua_upvalueid()>
|
|
C<lua_upvaluejoin()> C<lua_loadx()> C<lua_copy()> C<lua_tonumberx()>
|
|
C<lua_tointegerx()> C<luaL_fileresult()> C<luaL_execresult()>
|
|
C<luaL_loadfilex()> C<luaL_loadbufferx()> C<luaL_traceback()>
|
|
C<luaL_setfuncs()> C<luaL_pushmodule()> C<luaL_newlibtable()>
|
|
C<luaL_newlib()> C<luaL_testudata()> C<luaL_setmetatable()>
|
|
|
|
=item * Command line option C<-E>.
|
|
|
|
=item * Command line checks C<__tostring> for errors.
|
|
|
|
=back
|
|
|
|
Other features are only enabled, if LuaJIT is built with
|
|
C<-DLUAJIT_ENABLE_LUA52COMPAT>:
|
|
|
|
=over
|
|
|
|
=item * C<goto> is a keyword and not a valid variable name anymore.
|
|
|
|
=item * C<break> can be placed anywhere. Empty statements (C<;;>) are
|
|
allowed.
|
|
|
|
=item * C<__lt>, C<__le> are invoked for mixed types.
|
|
|
|
=item * C<__len> for tables. C<rawlen()> library function.
|
|
|
|
=item * C<pairs()> and C<ipairs()> check for C<__pairs> and
|
|
C<__ipairs>.
|
|
|
|
=item * C<coroutine.running()> returns two results.
|
|
|
|
=item * C<table.pack()> and C<table.unpack()> (same as C<unpack()>).
|
|
|
|
=item * C<io.write()> and C<file:write()> return file handle instead of
|
|
C<true>.
|
|
|
|
=item * C<os.execute()> and C<pipe:close()> return detailed exit
|
|
status.
|
|
|
|
=item * C<debug.setmetatable()> returns object.
|
|
|
|
=item * C<debug.getuservalue()> and C<debug.setuservalue()>.
|
|
|
|
=item * Remove C<math.mod()>, C<string.gfind()>.
|
|
|
|
=item * C<package.searchers>.
|
|
|
|
=item * C<module()> returns the module table.
|
|
|
|
=back
|
|
|
|
Note: this provides only partial compatibility with Lua 5.2 at the
|
|
language and Lua library level. LuaJIT is API+ABI-compatible with Lua
|
|
5.1, which prevents implementing features that would otherwise break
|
|
the Lua/C API and ABI (e.g. C<_ENV>).
|
|
|
|
=head2 Extensions from Lua 5.3
|
|
|
|
LuaJIT supports some extensions from Lua 5.3:
|
|
|
|
=over
|
|
|
|
=item * Unicode escape C<'\u{XX...}'> embeds the UTF-8 encoding in
|
|
string literals.
|
|
|
|
=item * The argument table C<arg> can be read (and modified) by
|
|
C<LUA_INIT> and C<-e> chunks.
|
|
|
|
=item * C<io.read()> and C<file:read()> accept formats with or without
|
|
a leading C<*>.
|
|
|
|
=item * C<table.move(a1, f, e, t [,a2])>.
|
|
|
|
=item * C<coroutine.isyieldable()>.
|
|
|
|
=item * Lua/C API extensions: C<lua_isyieldable()>
|
|
|
|
=back
|
|
|
|
=head2 C++ Exception Interoperability
|
|
|
|
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:
|
|
|
|
Platform
|
|
|
|
Compiler
|
|
|
|
Interoperability
|
|
|
|
POSIX/x64, DWARF2 unwinding
|
|
|
|
GCC 4.3+, Clang
|
|
|
|
B<Full>
|
|
|
|
ARM C<-DLUAJIT_UNWIND_EXTERNAL>
|
|
|
|
GCC, Clang
|
|
|
|
B<Full>
|
|
|
|
Other platforms, DWARF2 unwinding
|
|
|
|
GCC, Clang
|
|
|
|
B<Limited>
|
|
|
|
Windows/x64
|
|
|
|
MSVC or WinSDK
|
|
|
|
B<Full>
|
|
|
|
Windows/x86
|
|
|
|
Any
|
|
|
|
B<Full>
|
|
|
|
Other platforms
|
|
|
|
Other compilers
|
|
|
|
B<No>
|
|
|
|
B<Full interoperability> means:
|
|
|
|
=over
|
|
|
|
=item * C++ exceptions can be caught on the Lua side with C<pcall()>,
|
|
C<lua_pcall()> etc.
|
|
|
|
=item * C++ exceptions will be converted to the generic Lua error
|
|
C<"C++ exception">, unless you use the C call wrapper feature.
|
|
|
|
=item * 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.
|
|
|
|
=item * Lua errors can be caught on the C++ side with C<catch(...)>.
|
|
The corresponding Lua error message can be retrieved from the Lua
|
|
stack.
|
|
|
|
=item * Throwing Lua errors across C++ frames is safe. C++ destructors
|
|
will be called.
|
|
|
|
=back
|
|
|
|
B<Limited interoperability> means:
|
|
|
|
=over
|
|
|
|
=item * C++ exceptions can be caught on the Lua side with C<pcall()>,
|
|
C<lua_pcall()> etc.
|
|
|
|
=item * C++ exceptions will be converted to the generic Lua error
|
|
C<"C++ exception">, unless you use the C call wrapper feature.
|
|
|
|
=item * 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.
|
|
|
|
=item * Lua errors B<cannot> be caught on the C++ side.
|
|
|
|
=item * Throwing Lua errors across C++ frames will B<not> call C++
|
|
destructors.
|
|
|
|
=back
|
|
|
|
B<No interoperability> means:
|
|
|
|
=over
|
|
|
|
=item * It's B<not> safe to throw C++ exceptions across Lua frames.
|
|
|
|
=item * C++ exceptions B<cannot> be caught on the Lua side.
|
|
|
|
=item * Lua errors B<cannot> be caught on the C++ side.
|
|
|
|
=item * Throwing Lua errors across C++ frames will B<not> call C++
|
|
destructors.
|
|
|
|
=back
|
|
|
|
----
|
|
|
|
Copyright E<copy> 2005-2017 Mike Pall E<middot> Contact
|
|
|
|
=cut
|
|
|
|
#Pod::HTML2Pod conversion notes:
|
|
#From file extensions.html
|
|
# 17733 bytes of input
|
|
#Sat May 13 16:35:32 2017 agentzh
|
|
# No a_name switch not specified, so will not try to render <a name='...'>
|
|
# No a_href switch not specified, so will not try to render <a href='...'>
|