diff options
Diffstat (limited to 'Build/source/libs/luajit/LuaJIT-2.0.3/doc')
17 files changed, 6531 insertions, 0 deletions
diff --git a/Build/source/libs/luajit/LuaJIT-2.0.3/doc/bluequad-print.css b/Build/source/libs/luajit/LuaJIT-2.0.3/doc/bluequad-print.css new file mode 100644 index 00000000000..21da8688af0 --- /dev/null +++ b/Build/source/libs/luajit/LuaJIT-2.0.3/doc/bluequad-print.css @@ -0,0 +1,166 @@ +/* Copyright (C) 2004-2014 Mike Pall. + * + * You are welcome to use the general ideas of this design for your own sites. + * But please do not steal the stylesheet, the layout or the color scheme. + */ +body { + font-family: serif; + font-size: 11pt; + margin: 0 3em; + padding: 0; + border: none; +} +a:link, a:visited, a:hover, a:active { + text-decoration: none; + background: transparent; + color: #0000ff; +} +h1, h2, h3 { + font-family: sans-serif; + font-weight: bold; + text-align: left; + margin: 0.5em 0; + padding: 0; +} +h1 { + font-size: 200%; +} +h2 { + font-size: 150%; +} +h3 { + font-size: 125%; +} +p { + margin: 0 0 0.5em 0; + padding: 0; +} +ul, ol { + margin: 0.5em 0; + padding: 0 0 0 2em; +} +ul { + list-style: outside square; +} +ol { + list-style: outside decimal; +} +li { + margin: 0; + padding: 0; +} +dl { + margin: 1em 0; + padding: 1em; + border: 1px solid black; +} +dt { + font-weight: bold; + margin: 0; + padding: 0; +} +dt sup { + float: right; + margin-left: 1em; +} +dd { + margin: 0.5em 0 0 2em; + padding: 0; +} +table { + table-layout: fixed; + width: 100%; + margin: 1em 0; + padding: 0; + border: 1px solid black; + border-spacing: 0; + border-collapse: collapse; +} +tr { + margin: 0; + padding: 0; + border: none; +} +td { + text-align: left; + margin: 0; + padding: 0.2em 0.5em; + border-top: 1px solid black; + border-bottom: 1px solid black; +} +tr.separate td { + border-top: double; +} +tt, pre, code, kbd, samp { + font-family: monospace; + font-size: 75%; +} +kbd { + font-weight: bolder; +} +blockquote, pre { + margin: 1em 2em; + padding: 0; +} +img { + border: none; + vertical-align: baseline; + margin: 0; + padding: 0; +} +img.left { + float: left; + margin: 0.5em 1em 0.5em 0; +} +img.right { + float: right; + margin: 0.5em 0 0.5em 1em; +} +.flush { + clear: both; + visibility: hidden; +} +.hide, .noprint, #nav { + display: none !important; +} +.pagebreak { + page-break-before: always; +} +#site { + text-align: right; + font-family: sans-serif; + font-weight: bold; + margin: 0 1em; + border-bottom: 1pt solid black; +} +#site a { + font-size: 1.2em; +} +#site a:link, #site a:visited { + text-decoration: none; + font-weight: bold; + background: transparent; + color: #ffffff; +} +#logo { + color: #ff8000; +} +#head { + clear: both; + margin: 0 1em; +} +#main { + line-height: 1.3; + text-align: justify; + margin: 1em; +} +#foot { + clear: both; + font-size: 80%; + text-align: center; + margin: 0 1.25em; + padding: 0.5em 0 0 0; + border-top: 1pt solid black; + page-break-before: avoid; + page-break-after: avoid; +} diff --git a/Build/source/libs/luajit/LuaJIT-2.0.3/doc/bluequad.css b/Build/source/libs/luajit/LuaJIT-2.0.3/doc/bluequad.css new file mode 100644 index 00000000000..05b092e4df6 --- /dev/null +++ b/Build/source/libs/luajit/LuaJIT-2.0.3/doc/bluequad.css @@ -0,0 +1,325 @@ +/* Copyright (C) 2004-2014 Mike Pall. + * + * You are welcome to use the general ideas of this design for your own sites. + * But please do not steal the stylesheet, the layout or the color scheme. + */ +/* colorscheme: + * + * site | head #4162bf/white | #6078bf/#e6ecff + * ------+------ ----------------+------------------- + * nav | main #bfcfff | #e6ecff/black + * + * nav: hiback loback #c5d5ff #b9c9f9 + * hiborder loborder #e6ecff #97a7d7 + * link hover #2142bf #ff0000 + * + * link: link visited hover #2142bf #8122bf #ff0000 + * + * main: boxback boxborder #f0f4ff #bfcfff + */ +body { + font-family: Verdana, Arial, Helvetica, sans-serif; + font-size: 10pt; + margin: 0; + padding: 0; + border: none; + background: #e0e0e0; + color: #000000; +} +a:link { + text-decoration: none; + background: transparent; + color: #2142bf; +} +a:visited { + text-decoration: none; + background: transparent; + color: #8122bf; +} +a:hover, a:active { + text-decoration: underline; + background: transparent; + color: #ff0000; +} +h1, h2, h3 { + font-weight: bold; + text-align: left; + margin: 0.5em 0; + padding: 0; + background: transparent; +} +h1 { + font-size: 200%; + line-height: 3em; /* really 6em relative to body, match #site span */ + margin: 0; +} +h2 { + font-size: 150%; + color: #606060; +} +h3 { + font-size: 125%; + color: #404040; +} +p { + max-width: 600px; + margin: 0 0 0.5em 0; + padding: 0; +} +b { + color: #404040; +} +ul, ol { + max-width: 600px; + margin: 0.5em 0; + padding: 0 0 0 2em; +} +ul { + list-style: outside square; +} +ol { + list-style: outside decimal; +} +li { + margin: 0; + padding: 0; +} +dl { + max-width: 600px; + margin: 1em 0; + padding: 1em; + border: 1px solid #bfcfff; + background: #f0f4ff; +} +dt { + font-weight: bold; + margin: 0; + padding: 0; +} +dt sup { + float: right; + margin-left: 1em; + color: #808080; +} +dt a:visited { + text-decoration: none; + color: #2142bf; +} +dt a:hover, dt a:active { + text-decoration: none; + color: #ff0000; +} +dd { + margin: 0.5em 0 0 2em; + padding: 0; +} +div.tablewrap { /* for IE *sigh* */ + max-width: 600px; +} +table { + table-layout: fixed; + border-spacing: 0; + border-collapse: collapse; + max-width: 600px; + width: 100%; + margin: 1em 0; + padding: 0; + border: 1px solid #bfcfff; +} +tr { + margin: 0; + padding: 0; + border: none; +} +tr.odd { + background: #f0f4ff; +} +tr.separate td { + border-top: 1px solid #bfcfff; +} +td { + text-align: left; + margin: 0; + padding: 0.2em 0.5em; + border: none; +} +tt, code, kbd, samp { + font-family: Courier New, Courier, monospace; + line-height: 1.2; + font-size: 110%; +} +kbd { + font-weight: bolder; +} +blockquote, pre { + max-width: 600px; + margin: 1em 2em; + padding: 0; +} +pre { + line-height: 1.1; +} +pre.code { + line-height: 1.4; + margin: 0.5em 0 1em 0.5em; + padding: 0.5em 1em; + border: 1px solid #bfcfff; + background: #f0f4ff; +} +pre.mark { + padding-left: 2em; +} +span.codemark { + position:absolute; + left: 16em; + color: #4040c0; +} +span.mark { + color: #4040c0; + font-family: Courier New, Courier, monospace; + line-height: 1.1; +} +img { + border: none; + vertical-align: baseline; + margin: 0; + padding: 0; +} +img.left { + float: left; + margin: 0.5em 1em 0.5em 0; +} +img.right { + float: right; + margin: 0.5em 0 0.5em 1em; +} +.indent { + padding-left: 1em; +} +.flush { + clear: both; + visibility: hidden; +} +.hide, .noscreen { + display: none !important; +} +.ext { + color: #ff8000; +} +.new { + font-size: 6pt; + vertical-align: middle; + background: #ff8000; + color: #ffffff; +} +#site { + clear: both; + float: left; + width: 13em; + text-align: center; + font-weight: bold; + margin: 0; + padding: 0; + background: transparent; + color: #ffffff; +} +#site a { + font-size: 200%; +} +#site a:link, #site a:visited { + text-decoration: none; + font-weight: bold; + background: transparent; + color: #ffffff; +} +#site span { + line-height: 3em; /* really 6em relative to body, match h1 */ +} +#logo { + color: #ffb380; +} +#head { + margin: 0; + padding: 0 0 0 2em; + border-left: solid 13em #4162bf; + border-right: solid 3em #6078bf; + background: #6078bf; + color: #e6ecff; +} +#nav { + clear: both; + float: left; + overflow: hidden; + text-align: left; + line-height: 1.5; + width: 13em; + padding-top: 1em; + background: transparent; +} +#nav ul { + list-style: none outside; + margin: 0; + padding: 0; +} +#nav li { + margin: 0; + padding: 0; +} +#nav a { + display: block; + text-decoration: none; + font-weight: bold; + margin: 0; + padding: 2px 1em; + border-top: 1px solid transparent; + border-bottom: 1px solid transparent; + background: transparent; + color: #2142bf; +} +#nav a:hover, #nav a:active { + text-decoration: none; + border-top: 1px solid #97a7d7; + border-bottom: 1px solid #e6ecff; + background: #b9c9f9; + color: #ff0000; +} +#nav a.current, #nav a.current:hover, #nav a.current:active { + border-top: 1px solid #e6ecff; + border-bottom: 1px solid #97a7d7; + background: #c5d5ff; + color: #2142bf; +} +#nav ul ul a { + padding: 0 1em 0 1.7em; +} +#nav ul ul ul a { + padding: 0 0.5em 0 2.4em; +} +#main { + line-height: 1.5; + text-align: left; + margin: 0; + padding: 1em 2em; + border-left: solid 13em #bfcfff; + border-right: solid 3em #e6ecff; + background: #e6ecff; +} +#foot { + clear: both; + font-size: 80%; + text-align: center; + margin: 0; + padding: 0.5em; + background: #6078bf; + color: #ffffff; +} +#foot a:link, #foot a:visited { + text-decoration: underline; + background: transparent; + color: #ffffff; +} +#foot a:hover, #foot a:active { + text-decoration: underline; + background: transparent; + color: #bfcfff; +} diff --git a/Build/source/libs/luajit/LuaJIT-2.0.3/doc/changes.html b/Build/source/libs/luajit/LuaJIT-2.0.3/doc/changes.html new file mode 100644 index 00000000000..98412293973 --- /dev/null +++ b/Build/source/libs/luajit/LuaJIT-2.0.3/doc/changes.html @@ -0,0 +1,928 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> +<html> +<head> +<title>LuaJIT Change History</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-2014, 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"> +div.major { max-width: 600px; padding: 1em; margin: 1em 0 1em 0; } +</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>LuaJIT Change History</h1> +</div> +<div id="nav"> +<ul><li> +<a href="luajit.html">LuaJIT</a> +<ul><li> +<a href="http://luajit.org/download.html">Download <span class="ext">»</span></a> +</li><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_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_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 class="current" 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://wiki.luajit.org/">Wiki <span class="ext">»</span></a> +</li><li> +<a href="http://luajit.org/list.html">Mailing List <span class="ext">»</span></a> +</li></ul> +</div> +<div id="main"> +<p> +This is a list of changes between the released versions of LuaJIT.<br> +The current <span style="color: #0000c0;">stable version</span> is <strong>LuaJIT 2.0.3</strong>.<br> +</p> +<p> +Please check the +<a href="http://luajit.org/changes.html"><span class="ext">»</span> Online Change History</a> +to see whether newer versions are available. +</p> + +<div class="major" style="background: #d0d0ff;"> +<h2 id="LuaJIT-2.0.3">LuaJIT 2.0.3 — 2014-03-12</h2> +<ul> +<li>Add PS4 port.</li> +<li>Add support for multilib distro builds.</li> +<li>Fix OSX build.</li> +<li>Fix MinGW build.</li> +<li>Fix Xbox 360 build.</li> +<li>Improve ULOAD forwarding for open upvalues.</li> +<li>Fix GC steps threshold handling when called by JIT-compiled code.</li> +<li>Fix argument checks for <tt>math.deg()</tt> and <tt>math.rad()</tt>.</li> +<li>Fix <tt>jit.flush(func|true)</tt>.</li> +<li>Respect <tt>jit.off(func)</tt> when returning to a function, too.</li> +<li>Fix compilation of <tt>string.byte(s, nil, n)</tt>.</li> +<li>Fix line number for relocated bytecode after closure fixup</li> +<li>Fix frame traversal for backtraces.</li> +<li>Fix ABC elimination.</li> +<li>Fix handling of redundant PHIs.</li> +<li>Fix snapshot restore for exit to function header.</li> +<li>Fix type punning alias analysis for constified pointers</li> +<li>Fix call unroll checks in the presence of metamethod frames.</li> +<li>Fix initial maxslot for down-recursive traces.</li> +<li>Prevent BASE register coalescing if parent uses <tt>IR_RETF</tt>.</li> +<li>Don't purge modified function from stack slots in <tt>BC_RET</tt>.</li> +<li>Fix recording of <tt>BC_VARG</tt>.</li> +<li>Don't access dangling reference to reallocated IR.</li> +<li>Fix frame depth display for bytecode dump in <tt>-jdump</tt>.</li> +<li>ARM: Fix register allocation when rematerializing FPRs.</li> +<li>x64: Fix store to upvalue for lightuserdata values.</li> +<li>FFI: Add missing GC steps for callback argument conversions.</li> +<li>FFI: Properly unload loaded DLLs.</li> +<li>FFI: Fix argument checks for <tt>ffi.string()</tt>.</li> +<li>FFI/x64: Fix passing of vector arguments to calls.</li> +<li>FFI: Rehash finalizer table after GC cycle, if needed.</li> +<li>FFI: Fix <tt>cts->L</tt> for cdata unsinking in snapshot restore.</li> +</ul> + +<h2 id="LuaJIT-2.0.2">LuaJIT 2.0.2 — 2013-06-03</h2> +<ul> +<li>Fix memory access check for fast string interning.</li> +<li>Fix MSVC intrinsics for older versions.</li> +<li>Add missing GC steps for <tt>io.*</tt> functions.</li> +<li>Fix spurious red zone overflows in machine code generation.</li> +<li>Fix jump-range constrained mcode allocation.</li> +<li>Inhibit DSE for implicit loads via calls.</li> +<li>Fix builtin string to number conversion for overflow digits.</li> +<li>Fix optional argument handling while recording builtins.</li> +<li>Fix optional argument handling in <tt>table.concat()</tt>.</li> +<li>Add partial support for building with MingW64 GCC 4.8-SEH.</li> +<li>Add missing PHI barrier to <tt>string.sub(str, a, b) == kstr</tt> FOLD rule.</li> +<li>Fix compatibility issues with Illumos.</li> +<li>ARM: Fix cache flush/sync for exit stubs of JIT-compiled code.</li> +<li>MIPS: Fix cache flush/sync for JIT-compiled code jump area.</li> +<li>PPC: Add <tt>plt</tt> suffix for external calls from assembler code.</li> +<li>FFI: Fix snapshot substitution in SPLIT pass.</li> +<li>FFI/x86: Fix register allocation for 64 bit comparisons.</li> +<li>FFI: Fix tailcall in lowest frame to C function with bool result.</li> +<li>FFI: Ignore <tt>long</tt> type specifier in <tt>ffi.istype()</tt>.</li> +<li>FFI: Fix calling conventions for 32 bit OSX and iOS simulator (struct returns).</li> +<li>FFI: Fix calling conventions for ARM hard-float EABI (nested structs).</li> +<li>FFI: Improve error messages for arithmetic and comparison operators.</li> +<li>FFI: Insert no-op type conversion for pointer to integer cast.</li> +<li>FFI: Fix unroll limit for <tt>ffi.fill()</tt>.</li> +<li>FFI: Must sink <tt>XBAR</tt> together with <tt>XSTORE</tt>s.</li> +<li>FFI: Preserve intermediate string for <tt>const char *</tt> conversion.</li> +</ul> + +<h2 id="LuaJIT-2.0.1">LuaJIT 2.0.1 — 2013-02-19</h2> +<ul> +<li>Don't clear frame for out-of-memory error.</li> +<li>Leave hook when resume catches error thrown from hook.</li> +<li>Add missing GC steps for template table creation.</li> +<li>Fix discharge order of comparisons in Lua parser.</li> +<li>Improve buffer handling for <tt>io.read()</tt>.</li> +<li>OSX: Add support for Mach-O object files to <tt>-b</tt> option.</li> +<li>Fix PS3 port.</li> +<li>Fix/enable Xbox 360 port.</li> +<li>x86/x64: Always mark ref for shift count as non-weak.</li> +<li>x64: Don't fuse implicitly 32-to-64 extended operands.</li> +<li>ARM: Fix armhf call argument handling.</li> +<li>ARM: Fix code generation for integer math.min/math.max.</li> +<li>PPC/e500: Fix <tt>lj_vm_floor()</tt> for Inf/NaN.</li> +<li>FFI: Change priority of table initializer variants for structs.</li> +<li>FFI: Fix code generation for bool call result check on x86/x64.</li> +<li>FFI: Load FFI library on-demand for bytecode with cdata literals.</li> +<li>FFI: Fix handling of qualified transparent structs/unions.</li> +</ul> + +<h2 id="LuaJIT-2.0.0">LuaJIT 2.0.0 — 2012-11-08</h2> +<ul> +<li>Correctness and completeness: +<ul> + <li>Fix Android/x86 build.</li> + <li>Fix recording of equality comparisons with <tt>__eq</tt> metamethods.</li> + <li>Fix detection of immutable upvalues.</li> + <li>Replace error with PANIC for callbacks from JIT-compiled code.</li> + <li>Fix builtin string to number conversion for <tt>INT_MIN</tt>.</li> + <li>Don't create unneeded array part for template tables.</li> + <li>Fix <tt>CONV.num.int</tt> sinking.</li> + <li>Don't propagate implicitly widened number to index metamethods.</li> + <li>ARM: Fix ordered comparisons of number vs. non-number.</li> + <li>FFI: Fix code generation for replay of sunk float fields.</li> + <li>FFI: Fix signedness of bool.</li> + <li>FFI: Fix recording of bool call result check on x86/x64.</li> + <li>FFI: Fix stack-adjustment for <tt>__thiscall</tt> callbacks.</li> +</ul></li> +</ul> + +<h2 id="LuaJIT-2.0.0-beta11">LuaJIT 2.0.0-beta11 — 2012-10-16</h2> +<ul> +<li>New features: +<ul> + <li>Use ARM VFP instructions, if available (build-time detection).</li> + <li>Add support for ARM hard-float EABI (<tt>armhf</tt>).</li> + <li>Add PS3 port.</li> + <li>Add many features from Lua 5.2, e.g. <tt>goto</tt>/labels. + Refer to <a href="extensions.html#lua52">this list</a>.</li> + <li>FFI: Add parameterized C types.</li> + <li>FFI: Add support for copy constructors.</li> + <li>FFI: Equality comparisons never raise an error (treat as unequal instead).</li> + <li>FFI: Box all accessed or returned enums.</li> + <li>FFI: Check for <tt>__new</tt> metamethod when calling a constructor.</li> + <li>FFI: Handle <tt>__pairs</tt>/<tt>__ipairs</tt> metamethods for cdata objects.</li> + <li>FFI: Convert <tt>io.*</tt> file handle to <tt>FILE *</tt> pointer (but as a <tt>void *</tt>).</li> + <li>FFI: Detect and support type punning through unions.</li> + <li>FFI: Improve various error messages.</li> +</ul></li> +<li>Build-system reorganization: +<ul> + <li>Reorganize directory layout:<br> + <tt>lib/*</tt> → <tt>src/jit/*</tt><br> + <tt>src/buildvm_*.dasc</tt> → <tt>src/vm_*.dasc</tt><br> + <tt>src/buildvm_*.h</tt> → removed<br> + <tt>src/buildvm*</tt> → <tt>src/host/*</tt></li> + <li>Add minified Lua interpreter plus Lua BitOp (<tt>minilua</tt>) to run DynASM.</li> + <li>Change DynASM bit operations to use Lua BitOp</li> + <li>Translate only <tt>vm_*.dasc</tt> for detected target architecture.</li> + <li>Improve target detection for <tt>msvcbuild.bat</tt>.</li> + <li>Fix build issues on Cygwin and MinGW with optional MSys.</li> + <li>Handle cross-compiles with FPU/no-FPU or hard-fp/soft-fp ABI mismatch.</li> + <li>Remove some library functions for no-JIT/no-FFI builds.</li> + <li>Add uninstall target to top-level Makefile.</li> +</ul></li> +<li>Correctness and completeness: +<ul> + <li>Preserve snapshot #0 PC for all traces.</li> + <li>Fix argument checks for <tt>coroutine.create()</tt>.</li> + <li>Command line prints version and JIT status to <tt>stdout</tt>, not <tt>stderr</tt>.</li> + <li>Fix userdata <tt>__gc</tt> separations at Lua state close.</li> + <li>Fix <tt>TDUP</tt> to <tt>HLOAD</tt> forwarding for <tt>LJ_DUALNUM</tt> builds.</li> + <li>Fix buffer check in bytecode writer.</li> + <li>Make <tt>os.date()</tt> thread-safe.</li> + <li>Add missing declarations for MSVC intrinsics.</li> + <li>Fix dispatch table modifications for return hooks.</li> + <li>Workaround for MSVC conversion bug (<tt>double</tt> → <tt>uint32_t</tt> → <tt>int32_t</tt>).</li> + <li>Fix FOLD rule <tt>(i-j)-i => 0-j</tt>.</li> + <li>Never use DWARF unwinder on Windows.</li> + <li>Fix shrinking of direct mapped blocks in builtin allocator.</li> + <li>Limit recursion depth in <tt>string.match()</tt> et al.</li> + <li>Fix late despecialization of <tt>ITERN</tt> after loop has been entered.</li> + <li>Fix <tt>'f'</tt> and <tt>'L'</tt> options for <tt>debug.getinfo()</tt> and <tt>lua_getinfo()</tt>.</li> + <li>Fix <tt>package.searchpath()</tt>.</li> + <li>OSX: Change dylib names to be consistent with other platforms.</li> + <li>Android: Workaround for broken <tt>sprintf("%g", -0.0)</tt>.</li> + <li>x86: Remove support for ancient CPUs without <tt>CMOV</tt> (before Pentium Pro).</li> + <li>x86: Fix register allocation for calls returning register pair.</li> + <li>x86/x64: Fix fusion of unsigned byte comparisons with swapped operands.</li> + <li>ARM: Fix <tt>tonumber()</tt> argument check.</li> + <li>ARM: Fix modulo operator and <tt>math.floor()</tt>/<tt>math.ceil()</tt> for <tt>inf</tt>/<tt>nan</tt>.</li> + <li>ARM: Invoke SPLIT pass for leftover <tt>IR_TOBIT</tt>.</li> + <li>ARM: Fix BASE register coalescing.</li> + <li>PPC: Fix interpreter state setup in callbacks.</li> + <li>PPC: Fix <tt>string.sub()</tt> range check.</li> + <li>MIPS: Support generation of MIPS/MIPSEL bytecode object files.</li> + <li>MIPS: Fix calls to <tt>floor()</tt>/<tt>ceil()</tt><tt>/trunc()</tt>.</li> + <li>ARM/PPC: Detect more target architecture variants.</li> + <li>ARM/PPC/e500/MIPS: Fix tailcalls from fast functions, esp. <tt>tostring()</tt>.</li> + <li>ARM/PPC/MIPS: Fix rematerialization of FP constants.</li> + <li>FFI: Don't call <tt>FreeLibrary()</tt> on our own EXE/DLL.</li> + <li>FFI: Resolve metamethods for constructors, too.</li> + <li>FFI: Properly disable callbacks on iOS (would require executable memory).</li> + <li>FFI: Fix cdecl string parsing during recording.</li> + <li>FFI: Show address pointed to for <tt>tostring(ref)</tt>, too.</li> + <li>FFI: Fix alignment of C call argument/return structure.</li> + <li>FFI: Initialize all fields of standard types.</li> + <li>FFI: Fix callback handling when new C types are declared in callback.</li> + <li>FFI: Fix recording of constructors for pointers.</li> + <li>FFI: Always resolve metamethods for pointers to structs.</li> + <li>FFI: Correctly propagate alignment when interning nested types.</li> +</ul></li> +<li>Structural and performance enhancements: +<ul> + <li>Add allocation sinking and store sinking optimization.</li> + <li>Constify immutable upvalues.</li> + <li>Add builtin string to integer or FP number conversion. Improves cross-platform consistency and correctness.</li> + <li>Create string hash slots in template tables for non-const values, too. Avoids later table resizes.</li> + <li>Eliminate <tt>HREFK</tt> guard for template table references.</li> + <li>Add various new FOLD rules.</li> + <li>Don't use stack unwinding for <tt>lua_yield()</tt> (slow on x64).</li> + <li>ARM, PPC, MIPS: Improve <tt>XLOAD</tt> operand fusion and register hinting.</li> + <li>PPC, MIPS: Compile <tt>math.sqrt()</tt> to sqrt instruction, if available.</li> + <li>FFI: Fold <tt>KPTR</tt> + constant offset in SPLIT pass.</li> + <li>FFI: Optimize/inline <tt>ffi.copy()</tt> and <tt>ffi.fill()</tt>.</li> + <li>FFI: Compile and optimize array/struct copies.</li> + <li>FFI: Compile <tt>ffi.typeof(cdata|ctype)</tt>, <tt>ffi.sizeof()</tt>, <tt>ffi.alignof()</tt>, <tt>ffi.offsetof()</tt> and <tt>ffi.gc()</tt>.</li> +</ul></li> +</ul> + +<h2 id="LuaJIT-2.0.0-beta10">LuaJIT 2.0.0-beta10 — 2012-05-09</h2> +<ul> +<li>New features: +<ul> +<li>The MIPS of LuaJIT is complete. It requires a CPU conforming to the +MIPS32 R1 architecture with hardware FPU. O32 hard-fp ABI, +little-endian or big-endian.</li> +<li>Auto-detect target arch via cross-compiler. No need for +<tt>TARGET=arch</tt> anymore.</li> +<li>Make DynASM compatible with Lua 5.2.</li> +<li>From Lua 5.2: Try <tt>__tostring</tt> metamethod on non-string error +messages..</li> +</ul></li> +<li>Correctness and completeness: +<ul> +<li>Fix parsing of hex literals with exponents.</li> +<li>Fix bytecode dump for certain number constants.</li> +<li>Fix argument type in error message for relative arguments.</li> +<li>Fix argument error handling on Lua stacks without a frame.</li> +<li>Add missing mcode limit check in assembler backend.</li> +<li>Fix compilation on OpenBSD.</li> +<li>Avoid recursive GC steps after GC-triggered trace exit.</li> +<li>Replace <tt><unwind.h></tt> definitions with our own.</li> +<li>Fix OSX build issues. Bump minimum required OSX version to 10.4.</li> +<li>Fix discharge order of comparisons in Lua parser.</li> +<li>Ensure running <tt>__gc</tt> of userdata created in <tt>__gc</tt> +at state close.</li> +<li>Limit number of userdata <tt>__gc</tt> separations at state close.</li> +<li>Fix bytecode <tt>JMP</tt> slot range when optimizing +<tt>and</tt>/<tt>or</tt> with constant LHS.</li> +<li>Fix DSE of <tt>USTORE</tt>.</li> +<li>Make <tt>lua_concat()</tt> work from C hook with partial frame.</li> +<li>Add required PHIs for implicit conversions, e.g. via <tt>XREF</tt> +forwarding.</li> +<li>Add more comparison variants to Valgrind suppressions file.</li> +<li>Disable loading bytecode with an extra header (BOM or <tt>#!</tt>).</li> +<li>Fix PHI stack slot syncing.</li> +<li>ARM: Reorder type/value tests to silence Valgrind.</li> +<li>ARM: Fix register allocation for <tt>ldrd</tt>-optimized +<tt>HREFK</tt>.</li> +<li>ARM: Fix conditional branch fixup for <tt>OBAR</tt>.</li> +<li>ARM: Invoke SPLIT pass for <tt>double</tt> args in FFI call.</li> +<li>ARM: Handle all <tt>CALL*</tt> ops with <tt>double</tt> results in +SPLIT pass.</li> +<li>ARM: Fix rejoin of <tt>POW</tt> in SPLIT pass.</li> +<li>ARM: Fix compilation of <tt>math.sinh</tt>, <tt>math.cosh</tt>, +<tt>math.tanh</tt>.</li> +<li>ARM, PPC: Avoid pointless arg clearing in <tt>BC_IFUNCF</tt>.</li> +<li>PPC: Fix resume after yield from hook.</li> +<li>PPC: Fix argument checking for <tt>rawget()</tt>.</li> +<li>PPC: Fix fusion of floating-point <tt>XLOAD</tt>/<tt>XSTORE</tt>.</li> +<li>PPC: Fix <tt>HREFK</tt> code generation for huge tables.</li> +<li>PPC: Use builtin D-Cache/I-Cache sync code.</li> +</ul></li> +<li>FFI library: +<ul> +<li>Ignore empty statements in <tt>ffi.cdef()</tt>.</li> +<li>Ignore number parsing errors while skipping definitions.</li> +<li>Don't touch frame in callbacks with tailcalls to fast functions.</li> +<li>Fix library unloading on POSIX systems.</li> +<li>Finalize cdata before userdata when closing the state.</li> +<li>Change <tt>ffi.load()</tt> library name resolution for Cygwin.</li> +<li>Fix resolving of function name redirects on Windows/x86.</li> +<li>Fix symbol resolving error messages on Windows.</li> +<li>Fix blacklisting of C functions calling callbacks.</li> +<li>Fix result type of pointer difference.</li> +<li>Use correct PC in FFI metamethod error message.</li> +<li>Allow <tt>'typedef _Bool int BOOL;'</tt> for the Windows API.</li> +<li>Don't record test for bool result of call, if ignored.</li> +</ul></li> +</ul> + +<h2 id="LuaJIT-2.0.0-beta9">LuaJIT 2.0.0-beta9 — 2011-12-14</h2> +<ul> +<li>New features: +<ul> +<li>PPC port of LuaJIT is complete. Default is the dual-number port +(usually faster). Single-number port selectable via <tt>src/Makefile</tt> +at build time.</li> +<li>Add FFI callback support.</li> +<li>Extend <tt>-b</tt> to generate <tt>.c</tt>, <tt>.h</tt> or <tt>.obj/.o</tt> +files with embedded bytecode.</li> +<li>Allow loading embedded bytecode with <tt>require()</tt>.</li> +<li>From Lua 5.2: Change to <tt>'\z'</tt> escape. Reject undefined escape +sequences.</li> +</ul></li> +<li>Correctness and completeness: +<ul> +<li>Fix OSX 10.7 build. Fix <tt>install_name</tt> and versioning on OSX.</li> +<li>Fix iOS build.</li> +<li>Install <tt>dis_arm.lua</tt>, too.</li> +<li>Mark installed shared library as executable.</li> +<li>Add debug option to <tt>msvcbuild.bat</tt> and improve error handling.</li> +<li>Fix data-flow analysis for iterators.</li> +<li>Fix forced unwinding triggered by external unwinder.</li> +<li>Record missing <tt>for</tt> loop slot loads (return to lower frame).</li> +<li>Always use ANSI variants of Windows system functions.</li> +<li>Fix GC barrier for multi-result table constructor (<tt>TSETM</tt>).</li> +<li>Fix/add various FOLD rules.</li> +<li>Add potential PHI for number conversions due to type instability.</li> +<li>Do not eliminate PHIs only referenced from other PHIs.</li> +<li>Correctly anchor implicit number to string conversions in Lua/C API.</li> +<li>Fix various stack limit checks.</li> +<li>x64: Use thread-safe exceptions for external unwinding (GCC platforms).</li> +<li>x64: Fix result type of cdata index conversions.</li> +<li>x64: Fix <tt>math.random()</tt> and <tt>bit.bswap()</tt> code generation.</li> +<li>x64: Fix <tt>lightuserdata</tt> comparisons.</li> +<li>x64: Always extend stack-passed arguments to pointer size.</li> +<li>ARM: Many fixes to code generation backend.</li> +<li>PPC/e500: Fix dispatch for binop metamethods.</li> +<li>PPC/e500: Save/restore condition registers when entering/leaving the VM.</li> +<li>PPC/e500: Fix write barrier in stores of strings to upvalues.</li> +</ul></li> +<li>FFI library: +<ul> +<li>Fix C comment parsing.</li> +<li>Fix snapshot optimization for cdata comparisons.</li> +<li>Fix recording of const/enum lookups in namespaces.</li> +<li>Fix call argument and return handling for <tt>I8/U8/I16/U16</tt> types.</li> +<li>Fix unfused loads of float fields.</li> +<li>Fix <tt>ffi.string()</tt> recording.</li> +<li>Save <tt>GetLastError()</tt> around <tt>ffi.load()</tt> and symbol +resolving, too.</li> +<li>Improve ld script detection in <tt>ffi.load()</tt>.</li> +<li>Record loads/stores to external variables in namespaces.</li> +<li>Compile calls to stdcall, fastcall and vararg functions.</li> +<li>Treat function ctypes like pointers in comparisons.</li> +<li>Resolve <tt>__call</tt> metamethod for pointers, too.</li> +<li>Record C function calls with bool return values.</li> +<li>Record <tt>ffi.errno()</tt>.</li> +<li>x86: Fix number to <tt>uint32_t</tt> conversion rounding.</li> +<li>x86: Fix 64 bit arithmetic in assembler backend.</li> +<li>x64: Fix struct-by-value calling conventions.</li> +<li>ARM: Ensure invocation of SPLIT pass for float conversions.</li> +</ul></li> +<li>Structural and performance enhancements: +<ul> +<li>Display trace types with <tt>-jv</tt> and <tt>-jdump</tt>.</li> +<li>Record isolated calls. But prefer recording loops over calls.</li> +<li>Specialize to prototype for non-monomorphic functions. Solves the +trace-explosion problem for closure-heavy programming styles.</li> +<li>Always generate a portable <tt>vmdef.lua</tt>. Easier for distros.</li> +</ul></li> +</ul> + +<h2 id="LuaJIT-2.0.0-beta8">LuaJIT 2.0.0-beta8 — 2011-06-23</h2> +<ul> +<li>New features: +<ul> +<li>Soft-float ARM port of LuaJIT is complete.</li> +<li>Add support for bytecode loading/saving and <tt>-b</tt> command line +option.</li> +<li>From Lua 5.2: <tt>__len</tt> metamethod for tables +(disabled by default).</li> +</ul></li> +<li>Correctness and completeness: +<ul> +<li>ARM: Misc. fixes for interpreter.</li> +<li>x86/x64: Fix <tt>bit.*</tt> argument checking in interpreter.</li> +<li>Catch early out-of-memory in memory allocator initialization.</li> +<li>Fix data-flow analysis for paths leading to an upvalue close.</li> +<li>Fix check for missing arguments in <tt>string.format()</tt>.</li> +<li>Fix Solaris/x86 build (note: not a supported target).</li> +<li>Fix recording of loops with instable directions in side traces.</li> +<li>x86/x64: Fix fusion of comparisons with <tt>u8</tt>/<tt>u16</tt> +<tt>XLOAD</tt>.</li> +<li>x86/x64: Fix register allocation for variable shifts.</li> +</ul></li> +<li>FFI library: +<ul> +<li>Add <tt>ffi.errno()</tt>. Save <tt>errno</tt>/<tt>GetLastError()</tt> +around allocations etc.</li> +<li>Fix <tt>__gc</tt> for VLA/VLS cdata objects.</li> +<li>Fix recording of casts from 32 bit cdata pointers to integers.</li> +<li><tt>tonumber(cdata)</tt> returns <tt>nil</tt> for non-numbers.</li> +<li>Show address pointed to for <tt>tostring(pointer)</tt>.</li> +<li>Print <tt>NULL</tt> pointers as <tt>"cdata<... *>: NULL"</tt>.</li> +<li>Support <tt>__tostring</tt> metamethod for pointers to structs, too.</li> +</ul></li> +<li>Structural and performance enhancements: +<ul> +<li>More tuning for loop unrolling heuristics.</li> +<li>Flatten and compress in-memory debug info (saves ~70%).</li> +</ul></li> +</ul> + +<h2 id="LuaJIT-2.0.0-beta7">LuaJIT 2.0.0-beta7 — 2011-05-05</h2> +<ul> +<li>New features: +<ul> +<li>ARM port of the LuaJIT interpreter is complete.</li> +<li>FFI library: Add <tt>ffi.gc()</tt>, <tt>ffi.metatype()</tt>, +<tt>ffi.istype()</tt>.</li> +<li>FFI library: Resolve ld script redirection in <tt>ffi.load()</tt>.</li> +<li>From Lua 5.2: <tt>package.searchpath()</tt>, <tt>fp:read("*L")</tt>, +<tt>load(string)</tt>.</li> +<li>From Lua 5.2, disabled by default: empty statement, +<tt>table.unpack()</tt>, modified <tt>coroutine.running()</tt>.</li> +</ul></li> +<li>Correctness and completeness: +<ul> +<li>FFI library: numerous fixes.</li> +<li>Fix type mismatches in store-to-load forwarding.</li> +<li>Fix error handling within metamethods.</li> +<li>Fix <tt>table.maxn()</tt>.</li> +<li>Improve accuracy of <tt>x^-k</tt> on x64.</li> +<li>Fix code generation for Intel Atom in x64 mode.</li> +<li>Fix narrowing of POW.</li> +<li>Fix recording of retried fast functions.</li> +<li>Fix code generation for <tt>bit.bnot()</tt> and multiplies.</li> +<li>Fix error location within cpcall frames.</li> +<li>Add workaround for old libgcc unwind bug.</li> +<li>Fix <tt>lua_yield()</tt> and <tt>getmetatable(lightuserdata)</tt> on x64.</li> +<li>Misc. fixes for PPC/e500 interpreter.</li> +<li>Fix stack slot updates for down-recursion.</li> +</ul></li> +<li>Structural and performance enhancements: +<ul> +<li>Add dual-number mode (int/double) for the VM. Enabled for ARM.</li> +<li>Improve narrowing of arithmetic operators and <tt>for</tt> loops.</li> +<li>Tune loop unrolling heuristics and increase trace recorder limits.</li> +<li>Eliminate dead slots in snapshots using bytecode data-flow analysis.</li> +<li>Avoid phantom stores to proxy tables.</li> +<li>Optimize lookups in empty proxy tables.</li> +<li>Improve bytecode optimization of <tt>and</tt>/<tt>or</tt> operators.</li> +</ul></li> +</ul> + +<h2 id="LuaJIT-2.0.0-beta6">LuaJIT 2.0.0-beta6 — 2011-02-11</h2> +<ul> +<li>New features: +<ul> +<li>PowerPC/e500v2 port of the LuaJIT interpreter is complete.</li> +<li>Various minor features from Lua 5.2: Hex escapes in literals, +<tt>'\*'</tt> escape, reversible <tt>string.format("%q",s)</tt>, +<tt>"%g"</tt> pattern, <tt>table.sort</tt> checks callbacks, +<tt>os.exit(status|true|false[,close])</tt>.</li> +<li>Lua 5.2 <tt>__pairs</tt> and <tt>__ipairs</tt> metamethods +(disabled by default).</li> +<li>Initial release of the FFI library.</li> +</ul></li> +<li>Correctness and completeness: +<ul> +<li>Fix <tt>string.format()</tt> for non-finite numbers.</li> +<li>Fix memory leak when compiled to use the built-in allocator.</li> +<li>x86/x64: Fix unnecessary resize in <tt>TSETM</tt> bytecode.</li> +<li>Fix various GC issues with traces and <tt>jit.flush()</tt>.</li> +<li>x64: Fix fusion of indexes for array references.</li> +<li>x86/x64: Fix stack overflow handling for coroutine results.</li> +<li>Enable low-2GB memory allocation on FreeBSD/x64.</li> +<li>Fix <tt>collectgarbage("count")</tt> result if more than 2GB is in use.</li> +<li>Fix parsing of hex floats.</li> +<li>x86/x64: Fix loop branch inversion with trailing +<tt>HREF+NE/EQ</tt>.</li> +<li>Add <tt>jit.os</tt> string.</li> +<li><tt>coroutine.create()</tt> permits running C functions, too.</li> +<li>Fix OSX build to work with newer ld64 versions.</li> +<li>Fix bytecode optimization of <tt>and</tt>/<tt>or</tt> operators.</li> +</ul></li> +<li>Structural and performance enhancements: +<ul> +<li>Emit specialized bytecode for <tt>pairs()</tt>/<tt>next()</tt>.</li> +<li>Improve bytecode coalescing of <tt>nil</tt> constants.</li> +<li>Compile calls to vararg functions.</li> +<li>Compile <tt>select()</tt>.</li> +<li>Improve alias analysis, esp. for loads from allocations.</li> +<li>Tuning of various compiler heuristics.</li> +<li>Refactor and extend IR conversion instructions.</li> +<li>x86/x64: Various backend enhancements related to the FFI.</li> +<li>Add SPLIT pass to split 64 bit IR instructions for 32 bit CPUs.</li> +</ul></li> +</ul> + +<h2 id="LuaJIT-2.0.0-beta5">LuaJIT 2.0.0-beta5 — 2010-08-24</h2> +<ul> +<li>Correctness and completeness: +<ul> +<li>Fix trace exit dispatch to function headers.</li> +<li>Fix Windows and OSX builds with LUAJIT_DISABLE_JIT.</li> +<li>Reorganize and fix placement of generated machine code on x64.</li> +<li>Fix TNEW in x64 interpreter.</li> +<li>Do not eliminate PHIs for values only referenced from side exits.</li> +<li>OS-independent canonicalization of strings for non-finite numbers.</li> +<li>Fix <tt>string.char()</tt> range check on x64.</li> +<li>Fix <tt>tostring()</tt> resolving within <tt>print()</tt>.</li> +<li>Fix error handling for <tt>next()</tt>.</li> +<li>Fix passing of constant arguments to external calls on x64.</li> +<li>Fix interpreter argument check for two-argument SSE math functions.</li> +<li>Fix C frame chain corruption caused by <tt>lua_cpcall()</tt>.</li> +<li>Fix return from <tt>pcall()</tt> within active hook.</li> +</ul></li> +<li>Structural and performance enhancements: +<ul> +<li>Replace on-trace GC frame syncing with interpreter exit.</li> +<li>Improve hash lookup specialization by not removing dead keys during GC.</li> +<li>Turn traces into true GC objects.</li> +<li>Avoid starting a GC cycle immediately after library init.</li> +<li>Add weak guards to improve dead-code elimination.</li> +<li>Speed up string interning.</li> +</ul></li> +</ul> + +<h2 id="LuaJIT-2.0.0-beta4">LuaJIT 2.0.0-beta4 — 2010-03-28</h2> +<ul> +<li>Correctness and completeness: +<ul> +<li>Fix precondition for on-trace creation of table keys.</li> +<li>Fix <tt>{f()}</tt> on x64 when table is resized.</li> +<li>Fix folding of ordered comparisons with same references.</li> +<li>Fix snapshot restores for multi-result bytecodes.</li> +<li>Fix potential hang when recording bytecode with nested closures.</li> +<li>Fix recording of <tt>getmetatable()</tt>, <tt>tonumber()</tt> and bad argument types.</li> +<li>Fix SLOAD fusion across returns to lower frames.</li> +</ul></li> +<li>Structural and performance enhancements: +<ul> +<li>Add array bounds check elimination. <tt>-Oabc</tt> is enabled by default.</li> +<li>More tuning for x64, e.g. smaller table objects.</li> +</ul></li> +</ul> + +<h2 id="LuaJIT-2.0.0-beta3">LuaJIT 2.0.0-beta3 — 2010-03-07</h2> +<ul> +<li>LuaJIT x64 port: +<ul> +<li>Port integrated memory allocator to Linux/x64, Windows/x64 and OSX/x64.</li> +<li>Port interpreter and JIT compiler to x64.</li> +<li>Port DynASM to x64.</li> +<li>Many 32/64 bit cleanups in the VM.</li> +<li>Allow building the interpreter with either x87 or SSE2 arithmetics.</li> +<li>Add external unwinding and C++ exception interop (default on x64).</li> +</ul></li> +<li>Correctness and completeness: +<ul> +<li>Fix constructor bytecode generation for certain conditional values.</li> +<li>Fix some cases of ordered string comparisons.</li> +<li>Fix <tt>lua_tocfunction()</tt>.</li> +<li>Fix cutoff register in JMP bytecode for some conditional expressions.</li> +<li>Fix PHI marking algorithm for references from variant slots.</li> +<li>Fix <tt>package.cpath</tt> for non-default PREFIX.</li> +<li>Fix DWARF2 frame unwind information for interpreter on OSX.</li> +<li>Drive the GC forward on string allocations in the parser.</li> +<li>Implement call/return hooks (zero-cost if disabled).</li> +<li>Implement yield from C hooks.</li> +<li>Disable JIT compiler on older non-SSE2 CPUs instead of aborting.</li> +</ul></li> +<li>Structural and performance enhancements: +<ul> +<li>Compile recursive code (tail-, up- and down-recursion).</li> +<li>Improve heuristics for bytecode penalties and blacklisting.</li> +<li>Split CALL/FUNC recording and clean up fast function call semantics.</li> +<li>Major redesign of internal function call handling.</li> +<li>Improve FOR loop const specialization and integerness checks.</li> +<li>Switch to pre-initialized stacks. Avoid frame-clearing.</li> +<li>Colocation of prototypes and related data: bytecode, constants, debug info.</li> +<li>Cleanup parser and streamline bytecode generation.</li> +<li>Add support for weak IR references to register allocator.</li> +<li>Switch to compressed, extensible snapshots.</li> +<li>Compile returns to frames below the start frame.</li> +<li>Improve alias analysis of upvalues using a disambiguation hash value.</li> +<li>Compile floor/ceil/trunc to SSE2 helper calls or SSE4.1 instructions.</li> +<li>Add generic C call handling to IR and backend.</li> +<li>Improve KNUM fuse vs. load heuristics.</li> +<li>Compile various <tt>io.*()</tt> functions.</li> +<li>Compile <tt>math.sinh()</tt>, <tt>math.cosh()</tt>, <tt>math.tanh()</tt> +and <tt>math.random()</tt>.</li> +</ul></li> +</ul> + +<h2 id="LuaJIT-2.0.0-beta2">LuaJIT 2.0.0-beta2 — 2009-11-09</h2> +<ul> +<li>Reorganize build system. Build static+shared library on POSIX.</li> +<li>Allow C++ exception conversion on all platforms +using a wrapper function.</li> +<li>Automatically catch C++ exceptions and rethrow Lua error +(DWARF2 only).</li> +<li>Check for the correct x87 FPU precision at strategic points.</li> +<li>Always use wrappers for libm functions.</li> +<li>Resurrect metamethod name strings before copying them.</li> +<li>Mark current trace, even if compiler is idle.</li> +<li>Ensure FILE metatable is created only once.</li> +<li>Fix type comparisons when different integer types are involved.</li> +<li>Fix <tt>getmetatable()</tt> recording.</li> +<li>Fix TDUP with dead keys in template table.</li> +<li><tt>jit.flush(tr)</tt> returns status. +Prevent manual flush of a trace that's still linked.</li> +<li>Improve register allocation heuristics for invariant references.</li> +<li>Compile the push/pop variants of <tt>table.insert()</tt> and +<tt>table.remove()</tt>.</li> +<li>Compatibility with MSVC <tt>link /debug</tt>.</li> +<li>Fix <tt>lua_iscfunction()</tt>.</li> +<li>Fix <tt>math.random()</tt> when compiled with <tt>-fpic</tt> (OSX).</li> +<li>Fix <tt>table.maxn()</tt>.</li> +<li>Bump <tt>MACOSX_DEPLOYMENT_TARGET</tt> to <tt>10.4</tt></li> +<li><tt>luaL_check*()</tt> and <tt>luaL_opt*()</tt> now support +negative arguments, too.<br> +This matches the behavior of Lua 5.1, but not the specification.</li> +</ul> + +<h2 id="LuaJIT-2.0.0-beta1">LuaJIT 2.0.0-beta1 — 2009-10-31</h2> +<ul> +<li>This is the first public release of LuaJIT 2.0.</li> +<li>The whole VM has been rewritten from the ground up, so there's +no point in listing differences over earlier versions.</li> +</ul> +</div> + +<div class="major" style="background: #ffff80;"> +<h2 id="LuaJIT-1.1.8">LuaJIT 1.1.8 — 2012-04-16</h2> +<ul> +<li>Merged with Lua 5.1.5. Also integrated fixes for all +<a href="http://www.lua.org/bugs.html#5.1.5"><span class="ext">»</span> <span class="ext">»</span> currently known bugs in Lua 5.1.5</a>.</li> +</ul> + +<h2 id="LuaJIT-1.1.7">LuaJIT 1.1.7 — 2011-05-05</h2> +<ul> +<li>Added fixes for the +<a href="http://www.lua.org/bugs.html#5.1.4"><span class="ext">»</span> currently known bugs in Lua 5.1.4</a>.</li> +</ul> + +<h2 id="LuaJIT-1.1.6">LuaJIT 1.1.6 — 2010-03-28</h2> +<ul> +<li>Added fixes for the +<a href="http://www.lua.org/bugs.html#5.1.4"><span class="ext">»</span> currently known bugs in Lua 5.1.4</a>.</li> +<li>Removed wrong GC check in <tt>jit_createstate()</tt>. +Thanks to Tim Mensch.</li> +<li>Fixed bad assertions while compiling <tt>table.insert()</tt> and +<tt>table.remove()</tt>.</li> +</ul> + +<h2 id="LuaJIT-1.1.5">LuaJIT 1.1.5 — 2008-10-25</h2> +<ul> +<li>Merged with Lua 5.1.4. Fixes all +<a href="http://www.lua.org/bugs.html#5.1.3"><span class="ext">»</span> known bugs in Lua 5.1.3</a>.</li> +</ul> + +<h2 id="LuaJIT-1.1.4">LuaJIT 1.1.4 — 2008-02-05</h2> +<ul> +<li>Merged with Lua 5.1.3. Fixes all +<a href="http://www.lua.org/bugs.html#5.1.2"><span class="ext">»</span> known bugs in Lua 5.1.2</a>.</li> +<li>Fixed possible (but unlikely) stack corruption while compiling +<tt>k^x</tt> expressions.</li> +<li>Fixed DynASM template for cmpss instruction.</li> +</ul> + +<h2 id="LuaJIT-1.1.3">LuaJIT 1.1.3 — 2007-05-24</h2> +<ul> +<li>Merged with Lua 5.1.2. Fixes all +<a href="http://www.lua.org/bugs.html#5.1.1"><span class="ext">»</span> known bugs in Lua 5.1.1</a>.</li> +<li>Merged pending Lua 5.1.x fixes: "return -nil" bug, spurious count hook call.</li> +<li>Remove a (sometimes) wrong assertion in <tt>luaJIT_findpc()</tt>.</li> +<li>DynASM now allows labels for displacements and <tt>.aword</tt>.</li> +<li>Fix some compiler warnings for DynASM glue (internal API change).</li> +<li>Correct naming for SSSE3 (temporarily known as SSE4) in DynASM and x86 disassembler.</li> +<li>The loadable debug modules now handle redirection to stdout +(e.g. <tt>-j trace=-</tt>).</li> +</ul> + +<h2 id="LuaJIT-1.1.2">LuaJIT 1.1.2 — 2006-06-24</h2> +<ul> +<li>Fix MSVC inline assembly: use only local variables with +<tt>lua_number2int()</tt>.</li> +<li>Fix "attempt to call a thread value" bug on Mac OS X: +make values of consts used as lightuserdata keys unique +to avoid joining by the compiler/linker.</li> +</ul> + +<h2 id="LuaJIT-1.1.1">LuaJIT 1.1.1 — 2006-06-20</h2> +<ul> +<li>Merged with Lua 5.1.1. Fixes all +<a href="http://www.lua.org/bugs.html#5.1"><span class="ext">»</span> known bugs in Lua 5.1</a>.</li> +<li>Enforce (dynamic) linker error for EXE/DLL version mismatches.</li> +<li>Minor changes to DynASM: faster pre-processing, smaller encoding +for some immediates.</li> +</ul> +<p> +This release is in sync with Coco 1.1.1 (see the +<a href="http://coco.luajit.org/changes.html"><span class="ext">»</span> Coco Change History</a>). +</p> + +<h2 id="LuaJIT-1.1.0">LuaJIT 1.1.0 — 2006-03-13</h2> +<ul> +<li>Merged with Lua 5.1 (final).</li> + +<li>New JIT call frame setup: +<ul> +<li>The C stack is kept 16 byte aligned (faster). +Mandatory for Mac OS X on Intel, too.</li> +<li>Faster calling conventions for internal C helper functions.</li> +<li>Better instruction scheduling for function prologue, OP_CALL and +OP_RETURN.</li> +</ul></li> + +<li>Miscellaneous optimizations: +<ul> +<li>Faster loads of FP constants. Remove narrow-to-wide store-to-load +forwarding stalls.</li> +<li>Use (scalar) SSE2 ops (if the CPU supports it) to speed up slot moves +and FP to integer conversions.</li> +<li>Optimized the two-argument form of <tt>OP_CONCAT</tt> (<tt>a..b</tt>).</li> +<li>Inlined <tt>OP_MOD</tt> (<tt>a%b</tt>). +With better accuracy than the C variant, too.</li> +<li>Inlined <tt>OP_POW</tt> (<tt>a^b</tt>). Unroll <tt>x^k</tt> or +use <tt>k^x = 2^(log2(k)*x)</tt> or call <tt>pow()</tt>.</li> +</ul></li> + +<li>Changes in the optimizer: +<ul> +<li>Improved hinting for table keys derived from table values +(<tt>t1[t2[x]]</tt>).</li> +<li>Lookup hinting now works with arbitrary object types and +supports index chains, too.</li> +<li>Generate type hints for arithmetic and comparison operators, +OP_LEN, OP_CONCAT and OP_FORPREP.</li> +<li>Remove several hint definitions in favour of a generic COMBINE hint.</li> +<li>Complete rewrite of <tt>jit.opt_inline</tt> module +(ex <tt>jit.opt_lib</tt>).</li> +</ul></li> + +<li>Use adaptive deoptimization: +<ul> +<li>If runtime verification of a contract fails, the affected +instruction is recompiled and patched on-the-fly. +Regular programs will trigger deoptimization only occasionally.</li> +<li>This avoids generating code for uncommon fallback cases +most of the time. Generated code is up to 30% smaller compared to +LuaJIT 1.0.3.</li> +<li>Deoptimization is used for many opcodes and contracts: +<ul> +<li>OP_CALL, OP_TAILCALL: type mismatch for callable.</li> +<li>Inlined calls: closure mismatch, parameter number and type mismatches.</li> +<li>OP_GETTABLE, OP_SETTABLE: table or key type and range mismatches.</li> +<li>All arithmetic and comparison operators, OP_LEN, OP_CONCAT, +OP_FORPREP: operand type and range mismatches.</li> +</ul></li> +<li>Complete redesign of the debug and traceback info +(bytecode ↔ mcode) to support deoptimization. +Much more flexible and needs only 50% of the space.</li> +<li>The modules <tt>jit.trace</tt>, <tt>jit.dumphints</tt> and +<tt>jit.dump</tt> handle deoptimization.</li> +</ul></li> + +<li>Inlined many popular library functions +(for commonly used arguments only): +<ul> +<li>Most <tt>math.*</tt> functions (the 18 most used ones) +[2x-10x faster].</li> +<li><tt>string.len</tt>, <tt>string.sub</tt> and <tt>string.char</tt> +[2x-10x faster].</li> +<li><tt>table.insert</tt>, <tt>table.remove</tt> and <tt>table.getn</tt> +[3x-5x faster].</li> +<li><tt>coroutine.yield</tt> and <tt>coroutine.resume</tt> +[3x-5x faster].</li> +<li><tt>pairs</tt>, <tt>ipairs</tt> and the corresponding iterators +[8x-15x faster].</li> +</ul></li> + +<li>Changes in the core and loadable modules and the stand-alone executable: +<ul> +<li>Added <tt>jit.version</tt>, <tt>jit.version_num</tt> +and <tt>jit.arch</tt>.</li> +<li>Reorganized some internal API functions (<tt>jit.util.*mcode*</tt>).</li> +<li>The <tt>-j dump</tt> output now shows JSUB names, too.</li> +<li>New x86 disassembler module written in pure Lua. No dependency +on ndisasm anymore. Flexible API, very compact (500 lines) +and complete (x87, MMX, SSE, SSE2, SSE3, SSSE3, privileged instructions).</li> +<li><tt>luajit -v</tt> prints the LuaJIT version and copyright +on a separate line.</li> +</ul></li> + +<li>Added SSE, SSE2, SSE3 and SSSE3 support to DynASM.</li> +<li>Miscellaneous doc changes. Added a section about +<a href="install.html#embedding">embedding LuaJIT</a>.</li> +</ul> +<p> +This release is in sync with Coco 1.1.0 (see the +<a href="http://coco.luajit.org/changes.html"><span class="ext">»</span> Coco Change History</a>). +</p> +</div> + +<div class="major" style="background: #ffffd0;"> +<h2 id="LuaJIT-1.0.3">LuaJIT 1.0.3 — 2005-09-08</h2> +<ul> +<li>Even more docs.</li> +<li>Unified closure checks in <tt>jit.*</tt>.</li> +<li>Fixed some range checks in <tt>jit.util.*</tt>.</li> +<li>Fixed __newindex call originating from <tt>jit_settable_str()</tt>.</li> +<li>Merged with Lua 5.1 alpha (including early bug fixes).</li> +</ul> +<p> +This is the first public release of LuaJIT. +</p> + +<h2 id="LuaJIT-1.0.2">LuaJIT 1.0.2 — 2005-09-02</h2> +<ul> +<li>Add support for flushing the Valgrind translation cache <br> +(<tt>MYCFLAGS= -DUSE_VALGRIND</tt>).</li> +<li>Add support for freeing executable mcode memory to the <tt>mmap()</tt>-based +variant for POSIX systems.</li> +<li>Reorganized the C function signature handling in +<tt>jit.opt_lib</tt>.</li> +<li>Changed to index-based hints for inlining C functions. +Still no support in the backend for inlining.</li> +<li>Hardcode <tt>HEAP_CREATE_ENABLE_EXECUTE</tt> value if undefined.</li> +<li>Misc. changes to the <tt>jit.*</tt> modules.</li> +<li>Misc. changes to the Makefiles.</li> +<li>Lots of new docs.</li> +<li>Complete doc reorg.</li> +</ul> +<p> +Not released because Lua 5.1 alpha came out today. +</p> + +<h2 id="LuaJIT-1.0.1">LuaJIT 1.0.1 — 2005-08-31</h2> +<ul> +<li>Missing GC step in <tt>OP_CONCAT</tt>.</li> +<li>Fix result handling for C –> JIT calls.</li> +<li>Detect CPU feature bits.</li> +<li>Encode conditional moves (<tt>fucomip</tt>) only when supported.</li> +<li>Add fallback instructions for FP compares.</li> +<li>Add support for <tt>LUA_COMPAT_VARARG</tt>. Still disabled by default.</li> +<li>MSVC needs a specific place for the <tt>CALLBACK</tt> attribute +(David Burgess).</li> +<li>Misc. doc updates.</li> +</ul> +<p> +Interim non-public release. +Special thanks to Adam D. Moss for reporting most of the bugs. +</p> + +<h2 id="LuaJIT-1.0.0">LuaJIT 1.0.0 — 2005-08-29</h2> +<p> +This is the initial non-public release of LuaJIT. +</p> +</div> +<br class="flush"> +</div> +<div id="foot"> +<hr class="hide"> +Copyright © 2005-2014 Mike Pall +<span class="noprint"> +· +<a href="contact.html">Contact</a> +</span> +</div> +</body> +</html> diff --git a/Build/source/libs/luajit/LuaJIT-2.0.3/doc/contact.html b/Build/source/libs/luajit/LuaJIT-2.0.3/doc/contact.html new file mode 100644 index 00000000000..0483a829bdf --- /dev/null +++ b/Build/source/libs/luajit/LuaJIT-2.0.3/doc/contact.html @@ -0,0 +1,102 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> +<html> +<head> +<title>Contact</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-2014, 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>Contact</h1> +</div> +<div id="nav"> +<ul><li> +<a href="luajit.html">LuaJIT</a> +<ul><li> +<a href="http://luajit.org/download.html">Download <span class="ext">»</span></a> +</li><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_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_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://wiki.luajit.org/">Wiki <span class="ext">»</span></a> +</li><li> +<a href="http://luajit.org/list.html">Mailing List <span class="ext">»</span></a> +</li></ul> +</div> +<div id="main"> +<p> +Please send general questions to the +<a href="http://luajit.org/list.html"><span class="ext">»</span> LuaJIT mailing list</a>. +You can also send any questions you have directly to me: +</p> + +<script type="text/javascript"> +<!-- +var xS="@-:\" .0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ<abc>defghijklmnopqrstuvwxyz";function xD(s) +{var len=s.length;var r="";for(var i=0;i<len;i++) +{var c=s.charAt(i);var n=xS.indexOf(c);if(n!=-1)c=xS.charAt(69-n);r+=c;} +document.write("<"+"p>"+r+"<"+"/p>\n");} +//--> +</script> +<script type="text/javascript"> +<!-- +xD("fyZKB8xv\"FJytmz8.KAB0u52D") +//--></script> +<noscript> +<p><img src="img/contact.png" alt="Contact info in image" width="170" height="13"> +</p> +</noscript> + +<h2>Copyright</h2> +<p> +All documentation is +Copyright © 2005-2014 Mike Pall. +</p> + + +<br class="flush"> +</div> +<div id="foot"> +<hr class="hide"> +Copyright © 2005-2014 Mike Pall +<span class="noprint"> +· +<a href="contact.html">Contact</a> +</span> +</div> +</body> +</html> diff --git a/Build/source/libs/luajit/LuaJIT-2.0.3/doc/ext_c_api.html b/Build/source/libs/luajit/LuaJIT-2.0.3/doc/ext_c_api.html new file mode 100644 index 00000000000..48503361331 --- /dev/null +++ b/Build/source/libs/luajit/LuaJIT-2.0.3/doc/ext_c_api.html @@ -0,0 +1,187 @@ +<!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-2014, 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="http://luajit.org/download.html">Download <span class="ext">»</span></a> +</li><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_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_semantics.html">FFI Semantics</a> +</li></ul> +</li><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://wiki.luajit.org/">Wiki <span class="ext">»</span></a> +</li><li> +<a href="http://luajit.org/list.html">Mailing List <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-2014 Mike Pall +<span class="noprint"> +· +<a href="contact.html">Contact</a> +</span> +</div> +</body> +</html> diff --git a/Build/source/libs/luajit/LuaJIT-2.0.3/doc/ext_ffi.html b/Build/source/libs/luajit/LuaJIT-2.0.3/doc/ext_ffi.html new file mode 100644 index 00000000000..fa9ca971c1f --- /dev/null +++ b/Build/source/libs/luajit/LuaJIT-2.0.3/doc/ext_ffi.html @@ -0,0 +1,330 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> +<html> +<head> +<title>FFI 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-2014, 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>FFI Library</h1> +</div> +<div id="nav"> +<ul><li> +<a href="luajit.html">LuaJIT</a> +<ul><li> +<a href="http://luajit.org/download.html">Download <span class="ext">»</span></a> +</li><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_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_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://wiki.luajit.org/">Wiki <span class="ext">»</span></a> +</li><li> +<a href="http://luajit.org/list.html">Mailing List <span class="ext">»</span></a> +</li></ul> +</div> +<div id="main"> +<p> + +The FFI library allows <b>calling external C functions</b> and +<b>using C data structures</b> from pure Lua code. + +</p> +<p> + +The FFI library largely obviates the need to write tedious manual +Lua/C bindings in C. No need to learn a separate binding language +— <b>it parses plain C declarations!</b> These can be +cut-n-pasted from C header files or reference manuals. It's up to +the task of binding large libraries without the need for dealing with +fragile binding generators. + +</p> +<p> +The FFI library is tightly integrated into LuaJIT (it's not available +as a separate module). The code generated by the JIT-compiler for +accesses to C data structures from Lua code is on par with the +code a C compiler would generate. Calls to C functions can +be inlined in JIT-compiled code, unlike calls to functions bound via +the classic Lua/C API. +</p> +<p> +This page gives a short introduction to the usage of the FFI library. +<em>Please use the FFI sub-topics in the navigation bar to learn more.</em> +</p> + +<h2 id="call">Motivating Example: Calling External C Functions</h2> +<p> +It's really easy to call an external C library function: +</p> +<pre class="code mark"> +<span class="codemark">① +② + + +③</span>local ffi = require("ffi") +ffi.cdef[[ +<span style="color:#00a000;">int printf(const char *fmt, ...);</span> +]] +ffi.C.printf("Hello %s!", "world") +</pre> +<p> +So, let's pick that apart: +</p> +<p> +<span class="mark">①</span> Load the FFI library. +</p> +<p> +<span class="mark">②</span> Add a C declaration +for the function. The part inside the double-brackets (in green) is +just standard C syntax. +</p> +<p> +<span class="mark">③</span> Call the named +C function — Yes, it's that simple! +</p> +<p style="font-size: 8pt;"> +Actually, what goes on behind the scenes is far from simple: <span +style="color:#4040c0;">③</span> makes use of the standard +C library namespace <tt>ffi.C</tt>. Indexing this namespace with +a symbol name (<tt>"printf"</tt>) automatically binds it to the +standard C library. The result is a special kind of object which, +when called, runs the <tt>printf</tt> function. The arguments passed +to this function are automatically converted from Lua objects to the +corresponding C types. +</p> +<p> +Ok, so maybe the use of <tt>printf()</tt> wasn't such a spectacular +example. You could have done that with <tt>io.write()</tt> and +<tt>string.format()</tt>, too. But you get the idea ... +</p> +<p> +So here's something to pop up a message box on Windows: +</p> +<pre class="code"> +local ffi = require("ffi") +ffi.cdef[[ +<span style="color:#00a000;">int MessageBoxA(void *w, const char *txt, const char *cap, int type);</span> +]] +ffi.C.MessageBoxA(nil, "Hello world!", "Test", 0) +</pre> +<p> +Bing! Again, that was far too easy, no? +</p> +<p style="font-size: 8pt;"> +Compare this with the effort required to bind that function using the +classic Lua/C API: create an extra C file, add a C function +that retrieves and checks the argument types passed from Lua and calls +the actual C function, add a list of module functions and their +names, add a <tt>luaopen_*</tt> function and register all module +functions, compile and link it into a shared library (DLL), move it to +the proper path, add Lua code that loads the module aaaand ... finally +call the binding function. Phew! +</p> + +<h2 id="cdata">Motivating Example: Using C Data Structures</h2> +<p> +The FFI library allows you to create and access C data +structures. Of course the main use for this is for interfacing with +C functions. But they can be used stand-alone, too. +</p> +<p> +Lua is built upon high-level data types. They are flexible, extensible +and dynamic. That's why we all love Lua so much. Alas, this can be +inefficient for certain tasks, where you'd really want a low-level +data type. E.g. a large array of a fixed structure needs to be +implemented with a big table holding lots of tiny tables. This imposes +both a substantial memory overhead as well as a performance overhead. +</p> +<p> +Here's a sketch of a library that operates on color images plus a +simple benchmark. First, the plain Lua version: +</p> +<pre class="code"> +local floor = math.floor + +local function image_ramp_green(n) + local img = {} + local f = 255/(n-1) + for i=1,n do + img[i] = { red = 0, green = floor((i-1)*f), blue = 0, alpha = 255 } + end + return img +end + +local function image_to_grey(img, n) + for i=1,n do + local y = floor(0.3*img[i].red + 0.59*img[i].green + 0.11*img[i].blue) + img[i].red = y; img[i].green = y; img[i].blue = y + end +end + +local N = 400*400 +local img = image_ramp_green(N) +for i=1,1000 do + image_to_grey(img, N) +end +</pre> +<p> +This creates a table with 160.000 pixels, each of which is a table +holding four number values in the range of 0-255. First an image with +a green ramp is created (1D for simplicity), then the image is +converted to greyscale 1000 times. Yes, that's silly, but I was in +need of a simple example ... +</p> +<p> +And here's the FFI version. The modified parts have been marked in +bold: +</p> +<pre class="code mark"> +<span class="codemark">① + + + + + +② + +③ +④ + + + + + + +③ +⑤</span><b>local ffi = require("ffi") +ffi.cdef[[ +</b><span style="color:#00a000;">typedef struct { uint8_t red, green, blue, alpha; } rgba_pixel;</span><b> +]]</b> + +local function image_ramp_green(n) + <b>local img = ffi.new("rgba_pixel[?]", n)</b> + local f = 255/(n-1) + for i=<b>0,n-1</b> do + <b>img[i].green = i*f</b> + <b>img[i].alpha = 255</b> + end + return img +end + +local function image_to_grey(img, n) + for i=<b>0,n-1</b> do + local y = <b>0.3*img[i].red + 0.59*img[i].green + 0.11*img[i].blue</b> + img[i].red = y; img[i].green = y; img[i].blue = y + end +end + +local N = 400*400 +local img = image_ramp_green(N) +for i=1,1000 do + image_to_grey(img, N) +end +</pre> +<p> +Ok, so that wasn't too difficult: +</p> +<p> +<span class="mark">①</span> First, load the FFI +library and declare the low-level data type. Here we choose a +<tt>struct</tt> which holds four byte fields, one for each component +of a 4x8 bit RGBA pixel. +</p> +<p> +<span class="mark">②</span> Creating the data +structure with <tt>ffi.new()</tt> is straightforward — the +<tt>'?'</tt> is a placeholder for the number of elements of a +variable-length array. +</p> +<p> +<span class="mark">③</span> C arrays are +zero-based, so the indexes have to run from <tt>0</tt> to +<tt>n-1</tt>. One might want to allocate one more element instead to +simplify converting legacy code. +</p> +<p> +<span class="mark">④</span> Since <tt>ffi.new()</tt> +zero-fills the array by default, we only need to set the green and the +alpha fields. +</p> +<p> +<span class="mark">⑤</span> The calls to +<tt>math.floor()</tt> can be omitted here, because floating-point +numbers are already truncated towards zero when converting them to an +integer. This happens implicitly when the number is stored in the +fields of each pixel. +</p> +<p> +Now let's have a look at the impact of the changes: first, memory +consumption for the image is down from 22 Megabytes to +640 Kilobytes (400*400*4 bytes). That's a factor of 35x less! So, +yes, tables do have a noticeable overhead. BTW: The original program +would consume 40 Megabytes in plain Lua (on x64). +</p> +<p> +Next, performance: the pure Lua version runs in 9.57 seconds (52.9 +seconds with the Lua interpreter) and the FFI version runs in 0.48 +seconds on my machine (YMMV). That's a factor of 20x faster (110x +faster than the Lua interpreter). +</p> +<p style="font-size: 8pt;"> +The avid reader may notice that converting the pure Lua version over +to use array indexes for the colors (<tt>[1]</tt> instead of +<tt>.red</tt>, <tt>[2]</tt> instead of <tt>.green</tt> etc.) ought to +be more compact and faster. This is certainly true (by a factor of +~1.7x). Switching to a struct-of-arrays would help, too. +</p> +<p style="font-size: 8pt;"> +However the resulting code would be less idiomatic and rather +error-prone. And it still doesn't get even close to the performance of +the FFI version of the code. Also, high-level data structures cannot +be easily passed to other C functions, especially I/O functions, +without undue conversion penalties. +</p> +<br class="flush"> +</div> +<div id="foot"> +<hr class="hide"> +Copyright © 2005-2014 Mike Pall +<span class="noprint"> +· +<a href="contact.html">Contact</a> +</span> +</div> +</body> +</html> diff --git a/Build/source/libs/luajit/LuaJIT-2.0.3/doc/ext_ffi_api.html b/Build/source/libs/luajit/LuaJIT-2.0.3/doc/ext_ffi_api.html new file mode 100644 index 00000000000..dcffcfa387f --- /dev/null +++ b/Build/source/libs/luajit/LuaJIT-2.0.3/doc/ext_ffi_api.html @@ -0,0 +1,566 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> +<html> +<head> +<title>ffi.* API Functions</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-2014, 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.abitable { width: 30em; line-height: 1.2; } +tr.abihead td { font-weight: bold; } +td.abiparam { font-weight: bold; width: 6em; } +</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><tt>ffi.*</tt> API Functions</h1> +</div> +<div id="nav"> +<ul><li> +<a href="luajit.html">LuaJIT</a> +<ul><li> +<a href="http://luajit.org/download.html">Download <span class="ext">»</span></a> +</li><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_ffi.html">FFI Library</a> +<ul><li> +<a href="ext_ffi_tutorial.html">FFI Tutorial</a> +</li><li> +<a class="current" href="ext_ffi_api.html">ffi.* API</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://wiki.luajit.org/">Wiki <span class="ext">»</span></a> +</li><li> +<a href="http://luajit.org/list.html">Mailing List <span class="ext">»</span></a> +</li></ul> +</div> +<div id="main"> +<p> +This page describes the API functions provided by the FFI library in +detail. It's recommended to read through the +<a href="ext_ffi.html">introduction</a> and the +<a href="ext_ffi_tutorial.html">FFI tutorial</a> first. +</p> + +<h2 id="glossary">Glossary</h2> +<ul> +<li><b>cdecl</b> — An abstract C type declaration (a Lua +string).</li> +<li><b>ctype</b> — A C type object. This is a special kind of +<b>cdata</b> returned by <tt>ffi.typeof()</tt>. It serves as a +<b>cdata</b> <a href="#ffi_new">constructor</a> when called.</li> +<li><b>cdata</b> — A C data object. It holds a value of the +corresponding <b>ctype</b>.</li> +<li><b>ct</b> — A C type specification which can be used for +most of the API functions. Either a <b>cdecl</b>, a <b>ctype</b> or a +<b>cdata</b> serving as a template type.</li> +<li><b>cb</b> — A callback object. This is a C data object +holding a special function pointer. Calling this function from +C code runs an associated Lua function.</li> +<li><b>VLA</b> — A variable-length array is declared with a +<tt>?</tt> instead of the number of elements, e.g. <tt>"int[?]"</tt>. +The number of elements (<tt>nelem</tt>) must be given when it's +<a href="#ffi_new">created</a>.</li> +<li><b>VLS</b> — A variable-length struct is a <tt>struct</tt> C +type where the last element is a <b>VLA</b>. The same rules for +declaration and creation apply.</li> +</ul> + +<h2 id="decl">Declaring and Accessing External Symbols</h2> +<p> +External symbols must be declared first and can then be accessed by +indexing a <a href="ext_ffi_semantics.html#clib">C library +namespace</a>, which automatically binds the symbol to a specific +library. +</p> + +<h3 id="ffi_cdef"><tt>ffi.cdef(def)</tt></h3> +<p> +Adds multiple C declarations for types or external symbols (named +variables or functions). <tt>def</tt> must be a Lua string. It's +recommended to use the syntactic sugar for string arguments as +follows: +</p> +<pre class="code"> +ffi.cdef[[ +<span style="color:#00a000;">typedef struct foo { int a, b; } foo_t; // Declare a struct and typedef. +int dofoo(foo_t *f, int n); /* Declare an external C function. */</span> +]] +</pre> +<p> +The contents of the string (the part in green above) must be a +sequence of +<a href="ext_ffi_semantics.html#clang">C declarations</a>, +separated by semicolons. The trailing semicolon for a single +declaration may be omitted. +</p> +<p> +Please note that external symbols are only <em>declared</em>, but they +are <em>not bound</em> to any specific address, yet. Binding is +achieved with C library namespaces (see below). +</p> +<p style="color: #c00000;"> +C declarations are not passed through a C pre-processor, +yet. No pre-processor tokens are allowed, except for +<tt>#pragma pack</tt>. Replace <tt>#define</tt> in existing +C header files with <tt>enum</tt>, <tt>static const</tt> +or <tt>typedef</tt> and/or pass the files through an external +C pre-processor (once). Be careful not to include unneeded or +redundant declarations from unrelated header files. +</p> + +<h3 id="ffi_C"><tt>ffi.C</tt></h3> +<p> +This is the default C library namespace — note the +uppercase <tt>'C'</tt>. It binds to the default set of symbols or +libraries on the target system. These are more or less the same as a +C compiler would offer by default, without specifying extra link +libraries. +</p> +<p> +On POSIX systems, this binds to symbols in the default or global +namespace. This includes all exported symbols from the executable and +any libraries loaded into the global namespace. This includes at least +<tt>libc</tt>, <tt>libm</tt>, <tt>libdl</tt> (on Linux), +<tt>libgcc</tt> (if compiled with GCC), as well as any exported +symbols from the Lua/C API provided by LuaJIT itself. +</p> +<p> +On Windows systems, this binds to symbols exported from the +<tt>*.exe</tt>, the <tt>lua51.dll</tt> (i.e. the Lua/C API +provided by LuaJIT itself), the C runtime library LuaJIT was linked +with (<tt>msvcrt*.dll</tt>), <tt>kernel32.dll</tt>, +<tt>user32.dll</tt> and <tt>gdi32.dll</tt>. +</p> + +<h3 id="ffi_load"><tt>clib = ffi.load(name [,global])</tt></h3> +<p> +This loads the dynamic library given by <tt>name</tt> and returns +a new C library namespace which binds to its symbols. On POSIX +systems, if <tt>global</tt> is <tt>true</tt>, the library symbols are +loaded into the global namespace, too. +</p> +<p> +If <tt>name</tt> is a path, the library is loaded from this path. +Otherwise <tt>name</tt> is canonicalized in a system-dependent way and +searched in the default search path for dynamic libraries: +</p> +<p> +On POSIX systems, if the name contains no dot, the extension +<tt>.so</tt> is appended. Also, the <tt>lib</tt> prefix is prepended +if necessary. So <tt>ffi.load("z")</tt> looks for <tt>"libz.so"</tt> +in the default shared library search path. +</p> +<p> +On Windows systems, if the name contains no dot, the extension +<tt>.dll</tt> is appended. So <tt>ffi.load("ws2_32")</tt> looks for +<tt>"ws2_32.dll"</tt> in the default DLL search path. +</p> + +<h2 id="create">Creating cdata Objects</h2> +<p> +The following API functions create cdata objects (<tt>type()</tt> +returns <tt>"cdata"</tt>). All created cdata objects are +<a href="ext_ffi_semantics.html#gc">garbage collected</a>. +</p> + +<h3 id="ffi_new"><tt>cdata = ffi.new(ct [,nelem] [,init...])<br> +cdata = <em>ctype</em>([nelem,] [init...])</tt></h3> +<p> +Creates a cdata object for the given <tt>ct</tt>. VLA/VLS types +require the <tt>nelem</tt> argument. The second syntax uses a ctype as +a constructor and is otherwise fully equivalent. +</p> +<p> +The cdata object is initialized according to the +<a href="ext_ffi_semantics.html#init">rules for initializers</a>, +using the optional <tt>init</tt> arguments. Excess initializers cause +an error. +</p> +<p> +Performance notice: if you want to create many objects of one kind, +parse the cdecl only once and get its ctype with +<tt>ffi.typeof()</tt>. Then use the ctype as a constructor repeatedly. +</p> +<p style="font-size: 8pt;"> +Please note that an anonymous <tt>struct</tt> declaration implicitly +creates a new and distinguished ctype every time you use it for +<tt>ffi.new()</tt>. This is probably <b>not</b> what you want, +especially if you create more than one cdata object. Different anonymous +<tt>structs</tt> are not considered assignment-compatible by the +C standard, even though they may have the same fields! Also, they +are considered different types by the JIT-compiler, which may cause an +excessive number of traces. It's strongly suggested to either declare +a named <tt>struct</tt> or <tt>typedef</tt> with <tt>ffi.cdef()</tt> +or to create a single ctype object for an anonymous <tt>struct</tt> +with <tt>ffi.typeof()</tt>. +</p> + +<h3 id="ffi_typeof"><tt>ctype = ffi.typeof(ct)</tt></h3> +<p> +Creates a ctype object for the given <tt>ct</tt>. +</p> +<p> +This function is especially useful to parse a cdecl only once and then +use the resulting ctype object as a <a href="#ffi_new">constructor</a>. +</p> + +<h3 id="ffi_cast"><tt>cdata = ffi.cast(ct, init)</tt></h3> +<p> +Creates a scalar cdata object for the given <tt>ct</tt>. The cdata +object is initialized with <tt>init</tt> using the "cast" variant of +the <a href="ext_ffi_semantics.html#convert">C type conversion +rules</a>. +</p> +<p> +This functions is mainly useful to override the pointer compatibility +checks or to convert pointers to addresses or vice versa. +</p> + +<h3 id="ffi_metatype"><tt>ctype = ffi.metatype(ct, metatable)</tt></h3> +<p> +Creates a ctype object for the given <tt>ct</tt> and associates it with +a metatable. Only <tt>struct</tt>/<tt>union</tt> types, complex numbers +and vectors are allowed. Other types may be wrapped in a +<tt>struct</tt>, if needed. +</p> +<p> +The association with a metatable is permanent and cannot be changed +afterwards. Neither the contents of the <tt>metatable</tt> nor the +contents of an <tt>__index</tt> table (if any) may be modified +afterwards. The associated metatable automatically applies to all uses +of this type, no matter how the objects are created or where they +originate from. Note that pre-defined operations on types have +precedence (e.g. declared field names cannot be overriden). +</p> +<p> +All standard Lua metamethods are implemented. These are called directly, +without shortcuts and on any mix of types. For binary operations, the +left operand is checked first for a valid ctype metamethod. The +<tt>__gc</tt> metamethod only applies to <tt>struct</tt>/<tt>union</tt> +types and performs an implicit <a href="#ffi_gc"><tt>ffi.gc()</tt></a> +call during creation of an instance. +</p> + +<h3 id="ffi_gc"><tt>cdata = ffi.gc(cdata, finalizer)</tt></h3> +<p> +Associates a finalizer with a pointer or aggregate cdata object. The +cdata object is returned unchanged. +</p> +<p> +This function allows safe integration of unmanaged resources into the +automatic memory management of the LuaJIT garbage collector. Typical +usage: +</p> +<pre class="code"> +local p = ffi.gc(ffi.C.malloc(n), ffi.C.free) +... +p = nil -- Last reference to p is gone. +-- GC will eventually run finalizer: ffi.C.free(p) +</pre> +<p> +A cdata finalizer works like the <tt>__gc</tt> metamethod for userdata +objects: when the last reference to a cdata object is gone, the +associated finalizer is called with the cdata object as an argument. The +finalizer can be a Lua function or a cdata function or cdata function +pointer. An existing finalizer can be removed by setting a <tt>nil</tt> +finalizer, e.g. right before explicitly deleting a resource: +</p> +<pre class="code"> +ffi.C.free(ffi.gc(p, nil)) -- Manually free the memory. +</pre> + +<h2 id="info">C Type Information</h2> +<p> +The following API functions return information about C types. +They are most useful for inspecting cdata objects. +</p> + +<h3 id="ffi_sizeof"><tt>size = ffi.sizeof(ct [,nelem])</tt></h3> +<p> +Returns the size of <tt>ct</tt> in bytes. Returns <tt>nil</tt> if +the size is not known (e.g. for <tt>"void"</tt> or function types). +Requires <tt>nelem</tt> for VLA/VLS types, except for cdata objects. +</p> + +<h3 id="ffi_alignof"><tt>align = ffi.alignof(ct)</tt></h3> +<p> +Returns the minimum required alignment for <tt>ct</tt> in bytes. +</p> + +<h3 id="ffi_offsetof"><tt>ofs [,bpos,bsize] = ffi.offsetof(ct, field)</tt></h3> +<p> +Returns the offset (in bytes) of <tt>field</tt> relative to the start +of <tt>ct</tt>, which must be a <tt>struct</tt>. Additionally returns +the position and the field size (in bits) for bit fields. +</p> + +<h3 id="ffi_istype"><tt>status = ffi.istype(ct, obj)</tt></h3> +<p> +Returns <tt>true</tt> if <tt>obj</tt> has the C type given by +<tt>ct</tt>. Returns <tt>false</tt> otherwise. +</p> +<p> +C type qualifiers (<tt>const</tt> etc.) are ignored. Pointers are +checked with the standard pointer compatibility rules, but without any +special treatment for <tt>void *</tt>. If <tt>ct</tt> specifies a +<tt>struct</tt>/<tt>union</tt>, then a pointer to this type is accepted, +too. Otherwise the types must match exactly. +</p> +<p> +Note: this function accepts all kinds of Lua objects for the +<tt>obj</tt> argument, but always returns <tt>false</tt> for non-cdata +objects. +</p> + +<h2 id="util">Utility Functions</h2> + +<h3 id="ffi_errno"><tt>err = ffi.errno([newerr])</tt></h3> +<p> +Returns the error number set by the last C function call which +indicated an error condition. If the optional <tt>newerr</tt> argument +is present, the error number is set to the new value and the previous +value is returned. +</p> +<p> +This function offers a portable and OS-independent way to get and set the +error number. Note that only <em>some</em> C functions set the error +number. And it's only significant if the function actually indicated an +error condition (e.g. with a return value of <tt>-1</tt> or +<tt>NULL</tt>). Otherwise, it may or may not contain any previously set +value. +</p> +<p> +You're advised to call this function only when needed and as close as +possible after the return of the related C function. The +<tt>errno</tt> value is preserved across hooks, memory allocations, +invocations of the JIT compiler and other internal VM activity. The same +applies to the value returned by <tt>GetLastError()</tt> on Windows, but +you need to declare and call it yourself. +</p> + +<h3 id="ffi_string"><tt>str = ffi.string(ptr [,len])</tt></h3> +<p> +Creates an interned Lua string from the data pointed to by +<tt>ptr</tt>. +</p> +<p> +If the optional argument <tt>len</tt> is missing, <tt>ptr</tt> is +converted to a <tt>"char *"</tt> and the data is assumed to be +zero-terminated. The length of the string is computed with +<tt>strlen()</tt>. +</p> +<p> +Otherwise <tt>ptr</tt> is converted to a <tt>"void *"</tt> and +<tt>len</tt> gives the length of the data. The data may contain +embedded zeros and need not be byte-oriented (though this may cause +endianess issues). +</p> +<p> +This function is mainly useful to convert (temporary) +<tt>"const char *"</tt> pointers returned by +C functions to Lua strings and store them or pass them to other +functions expecting a Lua string. The Lua string is an (interned) copy +of the data and bears no relation to the original data area anymore. +Lua strings are 8 bit clean and may be used to hold arbitrary, +non-character data. +</p> +<p> +Performance notice: it's faster to pass the length of the string, if +it's known. E.g. when the length is returned by a C call like +<tt>sprintf()</tt>. +</p> + +<h3 id="ffi_copy"><tt>ffi.copy(dst, src, len)<br> +ffi.copy(dst, str)</tt></h3> +<p> +Copies the data pointed to by <tt>src</tt> to <tt>dst</tt>. +<tt>dst</tt> is converted to a <tt>"void *"</tt> and <tt>src</tt> +is converted to a <tt>"const void *"</tt>. +</p> +<p> +In the first syntax, <tt>len</tt> gives the number of bytes to copy. +Caveat: if <tt>src</tt> is a Lua string, then <tt>len</tt> must not +exceed <tt>#src+1</tt>. +</p> +<p> +In the second syntax, the source of the copy must be a Lua string. All +bytes of the string <em>plus a zero-terminator</em> are copied to +<tt>dst</tt> (i.e. <tt>#src+1</tt> bytes). +</p> +<p> +Performance notice: <tt>ffi.copy()</tt> may be used as a faster +(inlinable) replacement for the C library functions +<tt>memcpy()</tt>, <tt>strcpy()</tt> and <tt>strncpy()</tt>. +</p> + +<h3 id="ffi_fill"><tt>ffi.fill(dst, len [,c])</tt></h3> +<p> +Fills the data pointed to by <tt>dst</tt> with <tt>len</tt> constant +bytes, given by <tt>c</tt>. If <tt>c</tt> is omitted, the data is +zero-filled. +</p> +<p> +Performance notice: <tt>ffi.fill()</tt> may be used as a faster +(inlinable) replacement for the C library function +<tt>memset(dst, c, len)</tt>. Please note the different +order of arguments! +</p> + +<h2 id="target">Target-specific Information</h2> + +<h3 id="ffi_abi"><tt>status = ffi.abi(param)</tt></h3> +<p> +Returns <tt>true</tt> if <tt>param</tt> (a Lua string) applies for the +target ABI (Application Binary Interface). Returns <tt>false</tt> +otherwise. The following parameters are currently defined: +</p> +<table class="abitable"> +<tr class="abihead"> +<td class="abiparam">Parameter</td> +<td class="abidesc">Description</td> +</tr> +<tr class="odd separate"> +<td class="abiparam">32bit</td><td class="abidesc">32 bit architecture</td></tr> +<tr class="even"> +<td class="abiparam">64bit</td><td class="abidesc">64 bit architecture</td></tr> +<tr class="odd separate"> +<td class="abiparam">le</td><td class="abidesc">Little-endian architecture</td></tr> +<tr class="even"> +<td class="abiparam">be</td><td class="abidesc">Big-endian architecture</td></tr> +<tr class="odd separate"> +<td class="abiparam">fpu</td><td class="abidesc">Target has a hardware FPU</td></tr> +<tr class="even"> +<td class="abiparam">softfp</td><td class="abidesc">softfp calling conventions</td></tr> +<tr class="odd"> +<td class="abiparam">hardfp</td><td class="abidesc">hardfp calling conventions</td></tr> +<tr class="even separate"> +<td class="abiparam">eabi</td><td class="abidesc">EABI variant of the standard ABI</td></tr> +<tr class="odd"> +<td class="abiparam">win</td><td class="abidesc">Windows variant of the standard ABI</td></tr> +</table> + +<h3 id="ffi_os"><tt>ffi.os</tt></h3> +<p> +Contains the target OS name. Same contents as +<a href="ext_jit.html#jit_os"><tt>jit.os</tt></a>. +</p> + +<h3 id="ffi_arch"><tt>ffi.arch</tt></h3> +<p> +Contains the target architecture name. Same contents as +<a href="ext_jit.html#jit_arch"><tt>jit.arch</tt></a>. +</p> + +<h2 id="callback">Methods for Callbacks</h2> +<p> +The C types for <a href="ext_ffi_semantics.html#callback">callbacks</a> +have some extra methods: +</p> + +<h3 id="callback_free"><tt>cb:free()</tt></h3> +<p> +Free the resources associated with a callback. The associated Lua +function is unanchored and may be garbage collected. The callback +function pointer is no longer valid and must not be called anymore +(it may be reused by a subsequently created callback). +</p> + +<h3 id="callback_set"><tt>cb:set(func)</tt></h3> +<p> +Associate a new Lua function with a callback. The C type of the +callback and the callback function pointer are unchanged. +</p> +<p> +This method is useful to dynamically switch the receiver of callbacks +without creating a new callback each time and registering it again (e.g. +with a GUI library). +</p> + +<h2 id="extended">Extended Standard Library Functions</h2> +<p> +The following standard library functions have been extended to work +with cdata objects: +</p> + +<h3 id="tonumber"><tt>n = tonumber(cdata)</tt></h3> +<p> +Converts a number cdata object to a <tt>double</tt> and returns it as +a Lua number. This is particularly useful for boxed 64 bit +integer values. Caveat: this conversion may incur a precision loss. +</p> + +<h3 id="tostring"><tt>s = tostring(cdata)</tt></h3> +<p> +Returns a string representation of the value of 64 bit integers +(<tt><b>"</b>nnn<b>LL"</b></tt> or <tt><b>"</b>nnn<b>ULL"</b></tt>) or +complex numbers (<tt><b>"</b>re±im<b>i"</b></tt>). Otherwise +returns a string representation of the C type of a ctype object +(<tt><b>"ctype<</b>type<b>>"</b></tt>) or a cdata object +(<tt><b>"cdata<</b>type<b>>: </b>address"</tt>), unless you +override it with a <tt>__tostring</tt> metamethod (see +<a href="#ffi_metatype"><tt>ffi.metatype()</tt></a>). +</p> + +<h3 id="pairs"><tt>iter, obj, start = pairs(cdata)<br> +iter, obj, start = ipairs(cdata)<br></tt></h3> +<p> +Calls the <tt>__pairs</tt> or <tt>__ipairs</tt> metamethod of the +corresponding ctype. +</p> + +<h2 id="literals">Extensions to the Lua Parser</h2> +<p> +The parser for Lua source code treats numeric literals with the +suffixes <tt>LL</tt> or <tt>ULL</tt> as signed or unsigned 64 bit +integers. Case doesn't matter, but uppercase is recommended for +readability. It handles both decimal (<tt>42LL</tt>) and hexadecimal +(<tt>0x2aLL</tt>) literals. +</p> +<p> +The imaginary part of complex numbers can be specified by suffixing +number literals with <tt>i</tt> or <tt>I</tt>, e.g. <tt>12.5i</tt>. +Caveat: you'll need to use <tt>1i</tt> to get an imaginary part with +the value one, since <tt>i</tt> itself still refers to a variable +named <tt>i</tt>. +</p> +<br class="flush"> +</div> +<div id="foot"> +<hr class="hide"> +Copyright © 2005-2014 Mike Pall +<span class="noprint"> +· +<a href="contact.html">Contact</a> +</span> +</div> +</body> +</html> diff --git a/Build/source/libs/luajit/LuaJIT-2.0.3/doc/ext_ffi_semantics.html b/Build/source/libs/luajit/LuaJIT-2.0.3/doc/ext_ffi_semantics.html new file mode 100644 index 00000000000..7e5f70357de --- /dev/null +++ b/Build/source/libs/luajit/LuaJIT-2.0.3/doc/ext_ffi_semantics.html @@ -0,0 +1,1245 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> +<html> +<head> +<title>FFI Semantics</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-2014, 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.convtable { line-height: 1.2; } +tr.convhead td { font-weight: bold; } +td.convop { font-style: italic; width: 40%; } +</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>FFI Semantics</h1> +</div> +<div id="nav"> +<ul><li> +<a href="luajit.html">LuaJIT</a> +<ul><li> +<a href="http://luajit.org/download.html">Download <span class="ext">»</span></a> +</li><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_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 class="current" 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://wiki.luajit.org/">Wiki <span class="ext">»</span></a> +</li><li> +<a href="http://luajit.org/list.html">Mailing List <span class="ext">»</span></a> +</li></ul> +</div> +<div id="main"> +<p> +This page describes the detailed semantics underlying the FFI library +and its interaction with both Lua and C code. +</p> +<p> +Given that the FFI library is designed to interface with C code +and that declarations can be written in plain C syntax, <b>it +closely follows the C language semantics</b>, wherever possible. +Some minor concessions are needed for smoother interoperation with Lua +language semantics. +</p> +<p> +Please don't be overwhelmed by the contents of this page — this +is a reference and you may need to consult it, if in doubt. It doesn't +hurt to skim this page, but most of the semantics "just work" as you'd +expect them to work. It should be straightforward to write +applications using the LuaJIT FFI for developers with a C or C++ +background. +</p> + +<h2 id="clang">C Language Support</h2> +<p> +The FFI library has a built-in C parser with a minimal memory +footprint. It's used by the <a href="ext_ffi_api.html">ffi.* library +functions</a> to declare C types or external symbols. +</p> +<p> +It's only purpose is to parse C declarations, as found e.g. in +C header files. Although it does evaluate constant expressions, +it's <em>not</em> a C compiler. The body of <tt>inline</tt> +C function definitions is simply ignored. +</p> +<p> +Also, this is <em>not</em> a validating C parser. It expects and +accepts correctly formed C declarations, but it may choose to +ignore bad declarations or show rather generic error messages. If in +doubt, please check the input against your favorite C compiler. +</p> +<p> +The C parser complies to the <b>C99 language standard</b> plus +the following extensions: +</p> +<ul> + +<li>The <tt>'\e'</tt> escape in character and string literals.</li> + +<li>The C99/C++ boolean type, declared with the keywords <tt>bool</tt> +or <tt>_Bool</tt>.</li> + +<li>Complex numbers, declared with the keywords <tt>complex</tt> or +<tt>_Complex</tt>.</li> + +<li>Two complex number types: <tt>complex</tt> (aka +<tt>complex double</tt>) and <tt>complex float</tt>.</li> + +<li>Vector types, declared with the GCC <tt>mode</tt> or +<tt>vector_size</tt> attribute.</li> + +<li>Unnamed ('transparent') <tt>struct</tt>/<tt>union</tt> fields +inside a <tt>struct</tt>/<tt>union</tt>.</li> + +<li>Incomplete <tt>enum</tt> declarations, handled like incomplete +<tt>struct</tt> declarations.</li> + +<li>Unnamed <tt>enum</tt> fields inside a +<tt>struct</tt>/<tt>union</tt>. This is similar to a scoped C++ +<tt>enum</tt>, except that declared constants are visible in the +global namespace, too.</li> + +<li>Scoped <tt>static const</tt> declarations inside a +<tt>struct</tt>/<tt>union</tt> (from C++).</li> + +<li>Zero-length arrays (<tt>[0]</tt>), empty +<tt>struct</tt>/<tt>union</tt>, variable-length arrays (VLA, +<tt>[?]</tt>) and variable-length structs (VLS, with a trailing +VLA).</li> + +<li>C++ reference types (<tt>int &x</tt>).</li> + +<li>Alternate GCC keywords with '<tt>__</tt>', e.g. +<tt>__const__</tt>.</li> + +<li>GCC <tt>__attribute__</tt> with the following attributes: +<tt>aligned</tt>, <tt>packed</tt>, <tt>mode</tt>, +<tt>vector_size</tt>, <tt>cdecl</tt>, <tt>fastcall</tt>, +<tt>stdcall</tt>, <tt>thiscall</tt>.</li> + +<li>The GCC <tt>__extension__</tt> keyword and the GCC +<tt>__alignof__</tt> operator.</li> + +<li>GCC <tt>__asm__("symname")</tt> symbol name redirection for +function declarations.</li> + +<li>MSVC keywords for fixed-length types: <tt>__int8</tt>, +<tt>__int16</tt>, <tt>__int32</tt> and <tt>__int64</tt>.</li> + +<li>MSVC <tt>__cdecl</tt>, <tt>__fastcall</tt>, <tt>__stdcall</tt>, +<tt>__thiscall</tt>, <tt>__ptr32</tt>, <tt>__ptr64</tt>, +<tt>__declspec(align(n))</tt> and <tt>#pragma pack</tt>.</li> + +<li>All other GCC/MSVC-specific attributes are ignored.</li> + +</ul> +<p> +The following C types are pre-defined by the C parser (like +a <tt>typedef</tt>, except re-declarations will be ignored): +</p> +<ul> + +<li>Vararg handling: <tt>va_list</tt>, <tt>__builtin_va_list</tt>, +<tt>__gnuc_va_list</tt>.</li> + +<li>From <tt><stddef.h></tt>: <tt>ptrdiff_t</tt>, +<tt>size_t</tt>, <tt>wchar_t</tt>.</li> + +<li>From <tt><stdint.h></tt>: <tt>int8_t</tt>, <tt>int16_t</tt>, +<tt>int32_t</tt>, <tt>int64_t</tt>, <tt>uint8_t</tt>, +<tt>uint16_t</tt>, <tt>uint32_t</tt>, <tt>uint64_t</tt>, +<tt>intptr_t</tt>, <tt>uintptr_t</tt>.</li> + +</ul> +<p> +You're encouraged to use these types in preference to +compiler-specific extensions or target-dependent standard types. +E.g. <tt>char</tt> differs in signedness and <tt>long</tt> differs in +size, depending on the target architecture and platform ABI. +</p> +<p> +The following C features are <b>not</b> supported: +</p> +<ul> + +<li>A declaration must always have a type specifier; it doesn't +default to an <tt>int</tt> type.</li> + +<li>Old-style empty function declarations (K&R) are not allowed. +All C functions must have a proper prototype declaration. A +function declared without parameters (<tt>int foo();</tt>) is +treated as a function taking zero arguments, like in C++.</li> + +<li>The <tt>long double</tt> C type is parsed correctly, but +there's no support for the related conversions, accesses or arithmetic +operations.</li> + +<li>Wide character strings and character literals are not +supported.</li> + +<li><a href="#status">See below</a> for features that are currently +not implemented.</li> + +</ul> + +<h2 id="convert">C Type Conversion Rules</h2> + +<h3 id="convert_tolua">Conversions from C types to Lua objects</h3> +<p> +These conversion rules apply for <em>read accesses</em> to +C types: indexing pointers, arrays or +<tt>struct</tt>/<tt>union</tt> types; reading external variables or +constant values; retrieving return values from C calls: +</p> +<table class="convtable"> +<tr class="convhead"> +<td class="convin">Input</td> +<td class="convop">Conversion</td> +<td class="convout">Output</td> +</tr> +<tr class="odd separate"> +<td class="convin"><tt>int8_t</tt>, <tt>int16_t</tt></td><td class="convop">→<sup>sign-ext</sup> <tt>int32_t</tt> → <tt>double</tt></td><td class="convout">number</td></tr> +<tr class="even"> +<td class="convin"><tt>uint8_t</tt>, <tt>uint16_t</tt></td><td class="convop">→<sup>zero-ext</sup> <tt>int32_t</tt> → <tt>double</tt></td><td class="convout">number</td></tr> +<tr class="odd"> +<td class="convin"><tt>int32_t</tt>, <tt>uint32_t</tt></td><td class="convop">→ <tt>double</tt></td><td class="convout">number</td></tr> +<tr class="even"> +<td class="convin"><tt>int64_t</tt>, <tt>uint64_t</tt></td><td class="convop">boxed value</td><td class="convout">64 bit int cdata</td></tr> +<tr class="odd separate"> +<td class="convin"><tt>double</tt>, <tt>float</tt></td><td class="convop">→ <tt>double</tt></td><td class="convout">number</td></tr> +<tr class="even separate"> +<td class="convin"><tt>bool</tt></td><td class="convop">0 → <tt>false</tt>, otherwise <tt>true</tt></td><td class="convout">boolean</td></tr> +<tr class="odd separate"> +<td class="convin"><tt>enum</tt></td><td class="convop">boxed value</td><td class="convout">enum cdata</td></tr> +<tr class="even"> +<td class="convin">Complex number</td><td class="convop">boxed value</td><td class="convout">complex cdata</td></tr> +<tr class="odd"> +<td class="convin">Vector</td><td class="convop">boxed value</td><td class="convout">vector cdata</td></tr> +<tr class="even"> +<td class="convin">Pointer</td><td class="convop">boxed value</td><td class="convout">pointer cdata</td></tr> +<tr class="odd separate"> +<td class="convin">Array</td><td class="convop">boxed reference</td><td class="convout">reference cdata</td></tr> +<tr class="even"> +<td class="convin"><tt>struct</tt>/<tt>union</tt></td><td class="convop">boxed reference</td><td class="convout">reference cdata</td></tr> +</table> +<p> +Bitfields are treated like their underlying type. +</p> +<p> +Reference types are dereferenced <em>before</em> a conversion can take +place — the conversion is applied to the C type pointed to +by the reference. +</p> + +<h3 id="convert_fromlua">Conversions from Lua objects to C types</h3> +<p> +These conversion rules apply for <em>write accesses</em> to +C types: indexing pointers, arrays or +<tt>struct</tt>/<tt>union</tt> types; initializing cdata objects; +casts to C types; writing to external variables; passing +arguments to C calls: +</p> +<table class="convtable"> +<tr class="convhead"> +<td class="convin">Input</td> +<td class="convop">Conversion</td> +<td class="convout">Output</td> +</tr> +<tr class="odd separate"> +<td class="convin">number</td><td class="convop">→</td><td class="convout"><tt>double</tt></td></tr> +<tr class="even"> +<td class="convin">boolean</td><td class="convop"><tt>false</tt> → 0, <tt>true</tt> → 1</td><td class="convout"><tt>bool</tt></td></tr> +<tr class="odd separate"> +<td class="convin">nil</td><td class="convop"><tt>NULL</tt> →</td><td class="convout"><tt>(void *)</tt></td></tr> +<tr class="even"> +<td class="convin">lightuserdata</td><td class="convop">lightuserdata address →</td><td class="convout"><tt>(void *)</tt></td></tr> +<tr class="odd"> +<td class="convin">userdata</td><td class="convop">userdata payload →</td><td class="convout"><tt>(void *)</tt></td></tr> +<tr class="even"> +<td class="convin">io.* file</td><td class="convop">get FILE * handle →</td><td class="convout"><tt>(void *)</tt></td></tr> +<tr class="odd separate"> +<td class="convin">string</td><td class="convop">match against <tt>enum</tt> constant</td><td class="convout"><tt>enum</tt></td></tr> +<tr class="even"> +<td class="convin">string</td><td class="convop">copy string data + zero-byte</td><td class="convout"><tt>int8_t[]</tt>, <tt>uint8_t[]</tt></td></tr> +<tr class="odd"> +<td class="convin">string</td><td class="convop">string data →</td><td class="convout"><tt>const char[]</tt></td></tr> +<tr class="even separate"> +<td class="convin">function</td><td class="convop"><a href="#callback">create callback</a> →</td><td class="convout">C function type</td></tr> +<tr class="odd separate"> +<td class="convin">table</td><td class="convop"><a href="#init_table">table initializer</a></td><td class="convout">Array</td></tr> +<tr class="even"> +<td class="convin">table</td><td class="convop"><a href="#init_table">table initializer</a></td><td class="convout"><tt>struct</tt>/<tt>union</tt></td></tr> +<tr class="odd separate"> +<td class="convin">cdata</td><td class="convop">cdata payload →</td><td class="convout">C type</td></tr> +</table> +<p> +If the result type of this conversion doesn't match the +C type of the destination, the +<a href="#convert_between">conversion rules between C types</a> +are applied. +</p> +<p> +Reference types are immutable after initialization ("no re-seating of +references"). For initialization purposes or when passing values to +reference parameters, they are treated like pointers. Note that unlike +in C++, there's no way to implement automatic reference generation of +variables under the Lua language semantics. If you want to call a +function with a reference parameter, you need to explicitly pass a +one-element array. +</p> + +<h3 id="convert_between">Conversions between C types</h3> +<p> +These conversion rules are more or less the same as the standard +C conversion rules. Some rules only apply to casts, or require +pointer or type compatibility: +</p> +<table class="convtable"> +<tr class="convhead"> +<td class="convin">Input</td> +<td class="convop">Conversion</td> +<td class="convout">Output</td> +</tr> +<tr class="odd separate"> +<td class="convin">Signed integer</td><td class="convop">→<sup>narrow or sign-extend</sup></td><td class="convout">Integer</td></tr> +<tr class="even"> +<td class="convin">Unsigned integer</td><td class="convop">→<sup>narrow or zero-extend</sup></td><td class="convout">Integer</td></tr> +<tr class="odd"> +<td class="convin">Integer</td><td class="convop">→<sup>round</sup></td><td class="convout"><tt>double</tt>, <tt>float</tt></td></tr> +<tr class="even"> +<td class="convin"><tt>double</tt>, <tt>float</tt></td><td class="convop">→<sup>trunc</sup> <tt>int32_t</tt> →<sup>narrow</sup></td><td class="convout"><tt>(u)int8_t</tt>, <tt>(u)int16_t</tt></td></tr> +<tr class="odd"> +<td class="convin"><tt>double</tt>, <tt>float</tt></td><td class="convop">→<sup>trunc</sup></td><td class="convout"><tt>(u)int32_t</tt>, <tt>(u)int64_t</tt></td></tr> +<tr class="even"> +<td class="convin"><tt>double</tt>, <tt>float</tt></td><td class="convop">→<sup>round</sup></td><td class="convout"><tt>float</tt>, <tt>double</tt></td></tr> +<tr class="odd separate"> +<td class="convin">Number</td><td class="convop">n == 0 → 0, otherwise 1</td><td class="convout"><tt>bool</tt></td></tr> +<tr class="even"> +<td class="convin"><tt>bool</tt></td><td class="convop"><tt>false</tt> → 0, <tt>true</tt> → 1</td><td class="convout">Number</td></tr> +<tr class="odd separate"> +<td class="convin">Complex number</td><td class="convop">convert real part</td><td class="convout">Number</td></tr> +<tr class="even"> +<td class="convin">Number</td><td class="convop">convert real part, imag = 0</td><td class="convout">Complex number</td></tr> +<tr class="odd"> +<td class="convin">Complex number</td><td class="convop">convert real and imag part</td><td class="convout">Complex number</td></tr> +<tr class="even separate"> +<td class="convin">Number</td><td class="convop">convert scalar and replicate</td><td class="convout">Vector</td></tr> +<tr class="odd"> +<td class="convin">Vector</td><td class="convop">copy (same size)</td><td class="convout">Vector</td></tr> +<tr class="even separate"> +<td class="convin"><tt>struct</tt>/<tt>union</tt></td><td class="convop">take base address (compat)</td><td class="convout">Pointer</td></tr> +<tr class="odd"> +<td class="convin">Array</td><td class="convop">take base address (compat)</td><td class="convout">Pointer</td></tr> +<tr class="even"> +<td class="convin">Function</td><td class="convop">take function address</td><td class="convout">Function pointer</td></tr> +<tr class="odd separate"> +<td class="convin">Number</td><td class="convop">convert via <tt>uintptr_t</tt> (cast)</td><td class="convout">Pointer</td></tr> +<tr class="even"> +<td class="convin">Pointer</td><td class="convop">convert address (compat/cast)</td><td class="convout">Pointer</td></tr> +<tr class="odd"> +<td class="convin">Pointer</td><td class="convop">convert address (cast)</td><td class="convout">Integer</td></tr> +<tr class="even"> +<td class="convin">Array</td><td class="convop">convert base address (cast)</td><td class="convout">Integer</td></tr> +<tr class="odd separate"> +<td class="convin">Array</td><td class="convop">copy (compat)</td><td class="convout">Array</td></tr> +<tr class="even"> +<td class="convin"><tt>struct</tt>/<tt>union</tt></td><td class="convop">copy (identical type)</td><td class="convout"><tt>struct</tt>/<tt>union</tt></td></tr> +</table> +<p> +Bitfields or <tt>enum</tt> types are treated like their underlying +type. +</p> +<p> +Conversions not listed above will raise an error. E.g. it's not +possible to convert a pointer to a complex number or vice versa. +</p> + +<h3 id="convert_vararg">Conversions for vararg C function arguments</h3> +<p> +The following default conversion rules apply when passing Lua objects +to the variable argument part of vararg C functions: +</p> +<table class="convtable"> +<tr class="convhead"> +<td class="convin">Input</td> +<td class="convop">Conversion</td> +<td class="convout">Output</td> +</tr> +<tr class="odd separate"> +<td class="convin">number</td><td class="convop">→</td><td class="convout"><tt>double</tt></td></tr> +<tr class="even"> +<td class="convin">boolean</td><td class="convop"><tt>false</tt> → 0, <tt>true</tt> → 1</td><td class="convout"><tt>bool</tt></td></tr> +<tr class="odd separate"> +<td class="convin">nil</td><td class="convop"><tt>NULL</tt> →</td><td class="convout"><tt>(void *)</tt></td></tr> +<tr class="even"> +<td class="convin">userdata</td><td class="convop">userdata payload →</td><td class="convout"><tt>(void *)</tt></td></tr> +<tr class="odd"> +<td class="convin">lightuserdata</td><td class="convop">lightuserdata address →</td><td class="convout"><tt>(void *)</tt></td></tr> +<tr class="even separate"> +<td class="convin">string</td><td class="convop">string data →</td><td class="convout"><tt>const char *</tt></td></tr> +<tr class="odd separate"> +<td class="convin"><tt>float</tt> cdata</td><td class="convop">→</td><td class="convout"><tt>double</tt></td></tr> +<tr class="even"> +<td class="convin">Array cdata</td><td class="convop">take base address</td><td class="convout">Element pointer</td></tr> +<tr class="odd"> +<td class="convin"><tt>struct</tt>/<tt>union</tt> cdata</td><td class="convop">take base address</td><td class="convout"><tt>struct</tt>/<tt>union</tt> pointer</td></tr> +<tr class="even"> +<td class="convin">Function cdata</td><td class="convop">take function address</td><td class="convout">Function pointer</td></tr> +<tr class="odd"> +<td class="convin">Any other cdata</td><td class="convop">no conversion</td><td class="convout">C type</td></tr> +</table> +<p> +To pass a Lua object, other than a cdata object, as a specific type, +you need to override the conversion rules: create a temporary cdata +object with a constructor or a cast and initialize it with the value +to pass: +</p> +<p> +Assuming <tt>x</tt> is a Lua number, here's how to pass it as an +integer to a vararg function: +</p> +<pre class="code"> +ffi.cdef[[ +int printf(const char *fmt, ...); +]] +ffi.C.printf("integer value: %d\n", ffi.new("int", x)) +</pre> +<p> +If you don't do this, the default Lua number → <tt>double</tt> +conversion rule applies. A vararg C function expecting an integer +will see a garbled or uninitialized value. +</p> + +<h2 id="init">Initializers</h2> +<p> +Creating a cdata object with +<a href="ext_ffi_api.html#ffi_new"><tt>ffi.new()</tt></a> or the +equivalent constructor syntax always initializes its contents, too. +Different rules apply, depending on the number of optional +initializers and the C types involved: +</p> +<ul> +<li>If no initializers are given, the object is filled with zero bytes.</li> + +<li>Scalar types (numbers and pointers) accept a single initializer. +The Lua object is <a href="#convert_fromlua">converted to the scalar +C type</a>.</li> + +<li>Valarrays (complex numbers and vectors) are treated like scalars +when a single initializer is given. Otherwise they are treated like +regular arrays.</li> + +<li>Aggregate types (arrays and structs) accept either a single cdata +initializer of the same type (copy constructor), a single +<a href="#init_table">table initializer</a>, or a flat list of +initializers.</li> + +<li>The elements of an array are initialized, starting at index zero. +If a single initializer is given for an array, it's repeated for all +remaining elements. This doesn't happen if two or more initializers +are given: all remaining uninitialized elements are filled with zero +bytes.</li> + +<li>Byte arrays may also be initialized with a Lua string. This copies +the whole string plus a terminating zero-byte. The copy stops early only +if the array has a known, fixed size.</li> + +<li>The fields of a <tt>struct</tt> are initialized in the order of +their declaration. Uninitialized fields are filled with zero +bytes.</li> + +<li>Only the first field of a <tt>union</tt> can be initialized with a +flat initializer.</li> + +<li>Elements or fields which are aggregates themselves are initialized +with a <em>single</em> initializer, but this may be a table +initializer or a compatible aggregate.</li> + +<li>Excess initializers cause an error.</li> + +</ul> + +<h2 id="init_table">Table Initializers</h2> +<p> +The following rules apply if a Lua table is used to initialize an +Array or a <tt>struct</tt>/<tt>union</tt>: +</p> +<ul> + +<li>If the table index <tt>[0]</tt> is non-<tt>nil</tt>, then the +table is assumed to be zero-based. Otherwise it's assumed to be +one-based.</li> + +<li>Array elements, starting at index zero, are initialized one-by-one +with the consecutive table elements, starting at either index +<tt>[0]</tt> or <tt>[1]</tt>. This process stops at the first +<tt>nil</tt> table element.</li> + +<li>If exactly one array element was initialized, it's repeated for +all the remaining elements. Otherwise all remaining uninitialized +elements are filled with zero bytes.</li> + +<li>The above logic only applies to arrays with a known fixed size. +A VLA is only initialized with the element(s) given in the table. +Depending on the use case, you may need to explicitly add a +<tt>NULL</tt> or <tt>0</tt> terminator to a VLA.</li> + +<li>A <tt>struct</tt>/<tt>union</tt> can be initialized in the +order of the declaration of its fields. Each field is initialized with +consecutive table elements, starting at either index <tt>[0]</tt> +or <tt>[1]</tt>. This process stops at the first <tt>nil</tt> table +element.</li> + +<li>Otherwise, if neither index <tt>[0]</tt> nor <tt>[1]</tt> is present, +a <tt>struct</tt>/<tt>union</tt> is initialized by looking up each field +name (as a string key) in the table. Each non-<tt>nil</tt> value is +used to initialize the corresponding field.</li> + +<li>Uninitialized fields of a <tt>struct</tt> are filled with zero +bytes, except for the trailing VLA of a VLS.</li> + +<li>Initialization of a <tt>union</tt> stops after one field has been +initialized. If no field has been initialized, the <tt>union</tt> is +filled with zero bytes.</li> + +<li>Elements or fields which are aggregates themselves are initialized +with a <em>single</em> initializer, but this may be a nested table +initializer (or a compatible aggregate).</li> + +<li>Excess initializers for an array cause an error. Excess +initializers for a <tt>struct</tt>/<tt>union</tt> are ignored. +Unrelated table entries are ignored, too.</li> + +</ul> +<p> +Example: +</p> +<pre class="code"> +local ffi = require("ffi") + +ffi.cdef[[ +struct foo { int a, b; }; +union bar { int i; double d; }; +struct nested { int x; struct foo y; }; +]] + +ffi.new("int[3]", {}) --> 0, 0, 0 +ffi.new("int[3]", {1}) --> 1, 1, 1 +ffi.new("int[3]", {1,2}) --> 1, 2, 0 +ffi.new("int[3]", {1,2,3}) --> 1, 2, 3 +ffi.new("int[3]", {[0]=1}) --> 1, 1, 1 +ffi.new("int[3]", {[0]=1,2}) --> 1, 2, 0 +ffi.new("int[3]", {[0]=1,2,3}) --> 1, 2, 3 +ffi.new("int[3]", {[0]=1,2,3,4}) --> error: too many initializers + +ffi.new("struct foo", {}) --> a = 0, b = 0 +ffi.new("struct foo", {1}) --> a = 1, b = 0 +ffi.new("struct foo", {1,2}) --> a = 1, b = 2 +ffi.new("struct foo", {[0]=1,2}) --> a = 1, b = 2 +ffi.new("struct foo", {b=2}) --> a = 0, b = 2 +ffi.new("struct foo", {a=1,b=2,c=3}) --> a = 1, b = 2 'c' is ignored + +ffi.new("union bar", {}) --> i = 0, d = 0.0 +ffi.new("union bar", {1}) --> i = 1, d = ? +ffi.new("union bar", {[0]=1,2}) --> i = 1, d = ? '2' is ignored +ffi.new("union bar", {d=2}) --> i = ?, d = 2.0 + +ffi.new("struct nested", {1,{2,3}}) --> x = 1, y.a = 2, y.b = 3 +ffi.new("struct nested", {x=1,y={2,3}}) --> x = 1, y.a = 2, y.b = 3 +</pre> + +<h2 id="cdata_ops">Operations on cdata Objects</h2> +<p> +All of the standard Lua operators can be applied to cdata objects or a +mix of a cdata object and another Lua object. The following list shows +the pre-defined operations. +</p> +<p> +Reference types are dereferenced <em>before</em> performing each of +the operations below — the operation is applied to the +C type pointed to by the reference. +</p> +<p> +The pre-defined operations are always tried first before deferring to a +metamethod or index table (if any) for the corresponding ctype (except +for <tt>__new</tt>). An error is raised if the metamethod lookup or +index table lookup fails. +</p> + +<h3 id="cdata_array">Indexing a cdata object</h3> +<ul> + +<li><b>Indexing a pointer/array</b>: a cdata pointer/array can be +indexed by a cdata number or a Lua number. The element address is +computed as the base address plus the number value multiplied by the +element size in bytes. A read access loads the element value and +<a href="#convert_tolua">converts it to a Lua object</a>. A write +access <a href="#convert_fromlua">converts a Lua object to the element +type</a> and stores the converted value to the element. An error is +raised if the element size is undefined or a write access to a +constant element is attempted.</li> + +<li><b>Dereferencing a <tt>struct</tt>/<tt>union</tt> field</b>: a +cdata <tt>struct</tt>/<tt>union</tt> or a pointer to a +<tt>struct</tt>/<tt>union</tt> can be dereferenced by a string key, +giving the field name. The field address is computed as the base +address plus the relative offset of the field. A read access loads the +field value and <a href="#convert_tolua">converts it to a Lua +object</a>. A write access <a href="#convert_fromlua">converts a Lua +object to the field type</a> and stores the converted value to the +field. An error is raised if a write access to a constant +<tt>struct</tt>/<tt>union</tt> or a constant field is attempted. +Scoped enum constants or static constants are treated like a constant +field.</li> + +<li><b>Indexing a complex number</b>: a complex number can be indexed +either by a cdata number or a Lua number with the values 0 or 1, or by +the strings <tt>"re"</tt> or <tt>"im"</tt>. A read access loads the +real part (<tt>[0]</tt>, <tt>.re</tt>) or the imaginary part +(<tt>[1]</tt>, <tt>.im</tt>) part of a complex number and +<a href="#convert_tolua">converts it to a Lua number</a>. The +sub-parts of a complex number are immutable — assigning to an +index of a complex number raises an error. Accessing out-of-bound +indexes returns unspecified results, but is guaranteed not to trigger +memory access violations.</li> + +<li><b>Indexing a vector</b>: a vector is treated like an array for +indexing purposes, except the vector elements are immutable — +assigning to an index of a vector raises an error.</li> + +</ul> +<p> +A ctype object can be indexed with a string key, too. The only +pre-defined operation is reading scoped constants of +<tt>struct</tt>/<tt>union</tt> types. All other accesses defer +to the corresponding metamethods or index tables (if any). +</p> +<p> +Note: since there's (deliberately) no address-of operator, a cdata +object holding a value type is effectively immutable after +initialization. The JIT compiler benefits from this fact when applying +certain optimizations. +</p> +<p> +As a consequence, the <em>elements</em> of complex numbers and +vectors are immutable. But the elements of an aggregate holding these +types <em>may</em> be modified of course. I.e. you cannot assign to +<tt>foo.c.im</tt>, but you can assign a (newly created) complex number +to <tt>foo.c</tt>. +</p> +<p> +The JIT compiler implements strict aliasing rules: accesses to different +types do <b>not</b> alias, except for differences in signedness (this +applies even to <tt>char</tt> pointers, unlike C99). Type punning +through unions is explicitly detected and allowed. +</p> + +<h3 id="cdata_call">Calling a cdata object</h3> +<ul> + +<li><b>Constructor</b>: a ctype object can be called and used as a +<a href="ext_ffi_api.html#ffi_new">constructor</a>. This is equivalent +to <tt>ffi.new(ct, ...)</tt>, unless a <tt>__new</tt> metamethod is +defined. The <tt>__new</tt> metamethod is called with the ctype object +plus any other arguments passed to the contructor. Note that you have to +use <tt>ffi.new</tt> inside of it, since calling <tt>ct(...)</tt> would +cause infinite recursion.</li> + +<li><b>C function call</b>: a cdata function or cdata function +pointer can be called. The passed arguments are +<a href="#convert_fromlua">converted to the C types</a> of the +parameters given by the function declaration. Arguments passed to the +variable argument part of vararg C function use +<a href="#convert_vararg">special conversion rules</a>. This +C function is called and the return value (if any) is +<a href="#convert_tolua">converted to a Lua object</a>.<br> +On Windows/x86 systems, <tt>__stdcall</tt> functions are automatically +detected and a function declared as <tt>__cdecl</tt> (the default) is +silently fixed up after the first call.</li> + +</ul> + +<h3 id="cdata_arith">Arithmetic on cdata objects</h3> +<ul> + +<li><b>Pointer arithmetic</b>: a cdata pointer/array and a cdata +number or a Lua number can be added or subtracted. The number must be +on the right hand side for a subtraction. The result is a pointer of +the same type with an address plus or minus the number value +multiplied by the element size in bytes. An error is raised if the +element size is undefined.</li> + +<li><b>Pointer difference</b>: two compatible cdata pointers/arrays +can be subtracted. The result is the difference between their +addresses, divided by the element size in bytes. An error is raised if +the element size is undefined or zero.</li> + +<li><b>64 bit integer arithmetic</b>: the standard arithmetic +operators (<tt>+ - * / % ^</tt> and unary +minus) can be applied to two cdata numbers, or a cdata number and a +Lua number. If one of them is an <tt>uint64_t</tt>, the other side is +converted to an <tt>uint64_t</tt> and an unsigned arithmetic operation +is performed. Otherwise both sides are converted to an +<tt>int64_t</tt> and a signed arithmetic operation is performed. The +result is a boxed 64 bit cdata object.<br> + +If one of the operands is an <tt>enum</tt> and the other operand is a +string, the string is converted to the value of a matching <tt>enum</tt> +constant before the above conversion.<br> + +These rules ensure that 64 bit integers are "sticky". Any +expression involving at least one 64 bit integer operand results +in another one. The undefined cases for the division, modulo and power +operators return <tt>2LL ^ 63</tt> or +<tt>2ULL ^ 63</tt>.<br> + +You'll have to explicitly convert a 64 bit integer to a Lua +number (e.g. for regular floating-point calculations) with +<tt>tonumber()</tt>. But note this may incur a precision loss.</li> + +</ul> + +<h3 id="cdata_comp">Comparisons of cdata objects</h3> +<ul> + +<li><b>Pointer comparison</b>: two compatible cdata pointers/arrays +can be compared. The result is the same as an unsigned comparison of +their addresses. <tt>nil</tt> is treated like a <tt>NULL</tt> pointer, +which is compatible with any other pointer type.</li> + +<li><b>64 bit integer comparison</b>: two cdata numbers, or a +cdata number and a Lua number can be compared with each other. If one +of them is an <tt>uint64_t</tt>, the other side is converted to an +<tt>uint64_t</tt> and an unsigned comparison is performed. Otherwise +both sides are converted to an <tt>int64_t</tt> and a signed +comparison is performed.<br> + +If one of the operands is an <tt>enum</tt> and the other operand is a +string, the string is converted to the value of a matching <tt>enum</tt> +constant before the above conversion.<br> + +<li><b>Comparisons for equality/inequality</b> never raise an error. +Even incompatible pointers can be compared for equality by address. Any +other incompatible comparison (also with non-cdata objects) treats the +two sides as unequal.</li> + +</ul> + +<h3 id="cdata_key">cdata objects as table keys</h3> +<p> +Lua tables may be indexed by cdata objects, but this doesn't provide +any useful semantics — <b>cdata objects are unsuitable as table +keys!</b> +</p> +<p> +A cdata object is treated like any other garbage-collected object and +is hashed and compared by its address for table indexing. Since +there's no interning for cdata value types, the same value may be +boxed in different cdata objects with different addresses. Thus +<tt>t[1LL+1LL]</tt> and <tt>t[2LL]</tt> usually <b>do not</b> point to +the same hash slot and they certainly <b>do not</b> point to the same +hash slot as <tt>t[2]</tt>. +</p> +<p> +It would seriously drive up implementation complexity and slow down +the common case, if one were to add extra handling for by-value +hashing and comparisons to Lua tables. Given the ubiquity of their use +inside the VM, this is not acceptable. +</p> +<p> +There are three viable alternatives, if you really need to use cdata +objects as keys: +</p> +<ul> + +<li>If you can get by with the precision of Lua numbers +(52 bits), then use <tt>tonumber()</tt> on a cdata number or +combine multiple fields of a cdata aggregate to a Lua number. Then use +the resulting Lua number as a key when indexing tables.<br> +One obvious benefit: <tt>t[tonumber(2LL)]</tt> <b>does</b> point to +the same slot as <tt>t[2]</tt>.</li> + +<li>Otherwise use either <tt>tostring()</tt> on 64 bit integers +or complex numbers or combine multiple fields of a cdata aggregate to +a Lua string (e.g. with +<a href="ext_ffi_api.html#ffi_string"><tt>ffi.string()</tt></a>). Then +use the resulting Lua string as a key when indexing tables.</li> + +<li>Create your own specialized hash table implementation using the +C types provided by the FFI library, just like you would in +C code. Ultimately this may give much better performance than the +other alternatives or what a generic by-value hash table could +possibly provide.</li> + +</ul> + +<h2 id="param">Parameterized Types</h2> +<p> +To facilitate some abstractions, the two functions +<a href="ext_ffi_api.html#ffi_typeof"><tt>ffi.typeof</tt></a> and +<a href="ext_ffi_api.html#ffi_cdef"><tt>ffi.cdef</tt></a> support +parameterized types in C declarations. Note: none of the other API +functions taking a cdecl allow this. +</p> +<p> +Any place you can write a <b><tt>typedef</tt> name</b>, an +<b>identifier</b> or a <b>number</b> in a declaration, you can write +<tt>$</tt> (the dollar sign) instead. These placeholders are replaced in +order of appearance with the arguments following the cdecl string: +</p> +<pre class="code"> +-- Declare a struct with a parameterized field type and name: +ffi.cdef([[ +typedef struct { $ $; } foo_t; +]], type1, name1) + +-- Anonymous struct with dynamic names: +local bar_t = ffi.typeof("struct { int $, $; }", name1, name2) +-- Derived pointer type: +local bar_ptr_t = ffi.typeof("$ *", bar_t) + +-- Parameterized dimensions work even where a VLA won't work: +local matrix_t = ffi.typeof("uint8_t[$][$]", width, height) +</pre> +<p> +Caveat: this is <em>not</em> simple text substitution! A passed ctype or +cdata object is treated like the underlying type, a passed string is +considered an identifier and a number is considered a number. You must +not mix this up: e.g. passing <tt>"int"</tt> as a string doesn't work in +place of a type, you'd need to use <tt>ffi.typeof("int")</tt> instead. +</p> +<p> +The main use for parameterized types are libraries implementing abstract +data types +(<a href="http://www.freelists.org/post/luajit/ffi-type-of-pointer-to,8"><span class="ext">»</span> example</a>), +similar to what can be achieved with C++ template metaprogramming. +Another use case are derived types of anonymous structs, which avoids +pollution of the global struct namespace. +</p> +<p> +Please note that parameterized types are a nice tool and indispensable +for certain use cases. But you'll want to use them sparingly in regular +code, e.g. when all types are actually fixed. +</p> + +<h2 id="gc">Garbage Collection of cdata Objects</h2> +<p> +All explicitly (<tt>ffi.new()</tt>, <tt>ffi.cast()</tt> etc.) or +implicitly (accessors) created cdata objects are garbage collected. +You need to ensure to retain valid references to cdata objects +somewhere on a Lua stack, an upvalue or in a Lua table while they are +still in use. Once the last reference to a cdata object is gone, the +garbage collector will automatically free the memory used by it (at +the end of the next GC cycle). +</p> +<p> +Please note that pointers themselves are cdata objects, however they +are <b>not</b> followed by the garbage collector. So e.g. if you +assign a cdata array to a pointer, you must keep the cdata object +holding the array alive as long as the pointer is still in use: +</p> +<pre class="code"> +ffi.cdef[[ +typedef struct { int *a; } foo_t; +]] + +local s = ffi.new("foo_t", ffi.new("int[10]")) -- <span style="color:#c00000;">WRONG!</span> + +local a = ffi.new("int[10]") -- <span style="color:#00a000;">OK</span> +local s = ffi.new("foo_t", a) +-- Now do something with 's', but keep 'a' alive until you're done. +</pre> +<p> +Similar rules apply for Lua strings which are implicitly converted to +<tt>"const char *"</tt>: the string object itself must be +referenced somewhere or it'll be garbage collected eventually. The +pointer will then point to stale data, which may have already been +overwritten. Note that <em>string literals</em> are automatically kept +alive as long as the function containing it (actually its prototype) +is not garbage collected. +</p> +<p> +Objects which are passed as an argument to an external C function +are kept alive until the call returns. So it's generally safe to +create temporary cdata objects in argument lists. This is a common +idiom for <a href="#convert_vararg">passing specific C types to +vararg functions</a>. +</p> +<p> +Memory areas returned by C functions (e.g. from <tt>malloc()</tt>) +must be manually managed, of course (or use +<a href="ext_ffi_api.html#ffi_gc"><tt>ffi.gc()</tt></a>). Pointers to +cdata objects are indistinguishable from pointers returned by C +functions (which is one of the reasons why the GC cannot follow them). +</p> + +<h2 id="callback">Callbacks</h2> +<p> +The LuaJIT FFI automatically generates special callback functions +whenever a Lua function is converted to a C function pointer. This +associates the generated callback function pointer with the C type +of the function pointer and the Lua function object (closure). +</p> +<p> +This can happen implicitly due to the usual conversions, e.g. when +passing a Lua function to a function pointer argument. Or you can use +<tt>ffi.cast()</tt> to explicitly cast a Lua function to a +C function pointer. +</p> +<p> +Currently only certain C function types can be used as callback +functions. Neither C vararg functions nor functions with +pass-by-value aggregate argument or result types are supported. There +are no restrictions for the kind of Lua functions that can be called +from the callback — no checks for the proper number of arguments +are made. The return value of the Lua function will be converted to the +result type and an error will be thrown for invalid conversions. +</p> +<p> +It's allowed to throw errors across a callback invocation, but it's not +advisable in general. Do this only if you know the C function, that +called the callback, copes with the forced stack unwinding and doesn't +leak resources. +</p> +<p> +One thing that's not allowed, is to let an FFI call into a C function +get JIT-compiled, which in turn calls a callback, calling into Lua again. +Usually this attempt is caught by the interpreter first and the +C function is blacklisted for compilation. +</p> +<p> +However, this heuristic may fail under specific circumstances: e.g. a +message polling function might not run Lua callbacks right away and the call +gets JIT-compiled. If it later happens to call back into Lua (e.g. a rarely +invoked error callback), you'll get a VM PANIC with the message +<tt>"bad callback"</tt>. Then you'll need to manually turn off +JIT-compilation with +<a href="ext_jit.html#jit_onoff_func"><tt>jit.off()</tt></a> for the +surrounding Lua function that invokes such a message polling function (or +similar). +</p> + +<h3 id="callback_resources">Callback resource handling</h3> +<p> +Callbacks take up resources — you can only have a limited number +of them at the same time (500 - 1000, depending on the +architecture). The associated Lua functions are anchored to prevent +garbage collection, too. +</p> +<p> +<b>Callbacks due to implicit conversions are permanent!</b> There is no +way to guess their lifetime, since the C side might store the +function pointer for later use (typical for GUI toolkits). The associated +resources cannot be reclaimed until termination: +</p> +<pre class="code"> +ffi.cdef[[ +typedef int (__stdcall *WNDENUMPROC)(void *hwnd, intptr_t l); +int EnumWindows(WNDENUMPROC func, intptr_t l); +]] + +-- Implicit conversion to a callback via function pointer argument. +local count = 0 +ffi.C.EnumWindows(function(hwnd, l) + count = count + 1 + return true +end, 0) +-- The callback is permanent and its resources cannot be reclaimed! +-- Ok, so this may not be a problem, if you do this only once. +</pre> +<p> +Note: this example shows that you <em>must</em> properly declare +<tt>__stdcall</tt> callbacks on Windows/x86 systems. The calling +convention cannot be automatically detected, unlike for +<tt>__stdcall</tt> calls <em>to</em> Windows functions. +</p> +<p> +For some use cases it's necessary to free up the resources or to +dynamically redirect callbacks. Use an explicit cast to a +C function pointer and keep the resulting cdata object. Then use +the <a href="ext_ffi_api.html#callback_free"><tt>cb:free()</tt></a> +or <a href="ext_ffi_api.html#callback_set"><tt>cb:set()</tt></a> methods +on the cdata object: +</p> +<pre class="code"> +-- Explicitly convert to a callback via cast. +local count = 0 +local cb = ffi.cast("WNDENUMPROC", function(hwnd, l) + count = count + 1 + return true +end) + +-- Pass it to a C function. +ffi.C.EnumWindows(cb, 0) +-- EnumWindows doesn't need the callback after it returns, so free it. + +cb:free() +-- The callback function pointer is no longer valid and its resources +-- will be reclaimed. The created Lua closure will be garbage collected. +</pre> + +<h3 id="callback_performance">Callback performance</h3> +<p> +<b>Callbacks are slow!</b> First, the C to Lua transition itself +has an unavoidable cost, similar to a <tt>lua_call()</tt> or +<tt>lua_pcall()</tt>. Argument and result marshalling add to that cost. +And finally, neither the C compiler nor LuaJIT can inline or +optimize across the language barrier and hoist repeated computations out +of a callback function. +</p> +<p> +Do not use callbacks for performance-sensitive work: e.g. consider a +numerical integration routine which takes a user-defined function to +integrate over. It's a bad idea to call a user-defined Lua function from +C code millions of times. The callback overhead will be absolutely +detrimental for performance. +</p> +<p> +It's considerably faster to write the numerical integration routine +itself in Lua — the JIT compiler will be able to inline the +user-defined function and optimize it together with its calling context, +with very competitive performance. +</p> +<p> +As a general guideline: <b>use callbacks only when you must</b>, because +of existing C APIs. E.g. callback performance is irrelevant for a +GUI application, which waits for user input most of the time, anyway. +</p> +<p> +For new designs <b>avoid push-style APIs</b>: a C function repeatedly +calling a callback for each result. Instead <b>use pull-style APIs</b>: +call a C function repeatedly to get a new result. Calls from Lua +to C via the FFI are much faster than the other way round. Most well-designed +libraries already use pull-style APIs (read/write, get/put). +</p> + +<h2 id="clib">C Library Namespaces</h2> +<p> +A C library namespace is a special kind of object which allows +access to the symbols contained in shared libraries or the default +symbol namespace. The default +<a href="ext_ffi_api.html#ffi_C"><tt>ffi.C</tt></a> namespace is +automatically created when the FFI library is loaded. C library +namespaces for specific shared libraries may be created with the +<a href="ext_ffi_api.html#ffi_load"><tt>ffi.load()</tt></a> API +function. +</p> +<p> +Indexing a C library namespace object with a symbol name (a Lua +string) automatically binds it to the library. First the symbol type +is resolved — it must have been declared with +<a href="ext_ffi_api.html#ffi_cdef"><tt>ffi.cdef</tt></a>. Then the +symbol address is resolved by searching for the symbol name in the +associated shared libraries or the default symbol namespace. Finally, +the resulting binding between the symbol name, the symbol type and its +address is cached. Missing symbol declarations or nonexistent symbol +names cause an error. +</p> +<p> +This is what happens on a <b>read access</b> for the different kinds of +symbols: +</p> +<ul> + +<li>External functions: a cdata object with the type of the function +and its address is returned.</li> + +<li>External variables: the symbol address is dereferenced and the +loaded value is <a href="#convert_tolua">converted to a Lua object</a> +and returned.</li> + +<li>Constant values (<tt>static const</tt> or <tt>enum</tt> +constants): the constant is <a href="#convert_tolua">converted to a +Lua object</a> and returned.</li> + +</ul> +<p> +This is what happens on a <b>write access</b>: +</p> +<ul> + +<li>External variables: the value to be written is +<a href="#convert_fromlua">converted to the C type</a> of the +variable and then stored at the symbol address.</li> + +<li>Writing to constant variables or to any other symbol type causes +an error, like any other attempted write to a constant location.</li> + +</ul> +<p> +C library namespaces themselves are garbage collected objects. If +the last reference to the namespace object is gone, the garbage +collector will eventually release the shared library reference and +remove all memory associated with the namespace. Since this may +trigger the removal of the shared library from the memory of the +running process, it's generally <em>not safe</em> to use function +cdata objects obtained from a library if the namespace object may be +unreferenced. +</p> +<p> +Performance notice: the JIT compiler specializes to the identity of +namespace objects and to the strings used to index it. This +effectively turns function cdata objects into constants. It's not +useful and actually counter-productive to explicitly cache these +function objects, e.g. <tt>local strlen = ffi.C.strlen</tt>. OTOH it +<em>is</em> useful to cache the namespace itself, e.g. <tt>local C = +ffi.C</tt>. +</p> + +<h2 id="policy">No Hand-holding!</h2> +<p> +The FFI library has been designed as <b>a low-level library</b>. The +goal is to interface with C code and C data types with a +minimum of overhead. This means <b>you can do anything you can do +from C</b>: access all memory, overwrite anything in memory, call +machine code at any memory address and so on. +</p> +<p> +The FFI library provides <b>no memory safety</b>, unlike regular Lua +code. It will happily allow you to dereference a <tt>NULL</tt> +pointer, to access arrays out of bounds or to misdeclare +C functions. If you make a mistake, your application might crash, +just like equivalent C code would. +</p> +<p> +This behavior is inevitable, since the goal is to provide full +interoperability with C code. Adding extra safety measures, like +bounds checks, would be futile. There's no way to detect +misdeclarations of C functions, since shared libraries only +provide symbol names, but no type information. Likewise there's no way +to infer the valid range of indexes for a returned pointer. +</p> +<p> +Again: the FFI library is a low-level library. This implies it needs +to be used with care, but it's flexibility and performance often +outweigh this concern. If you're a C or C++ developer, it'll be easy +to apply your existing knowledge. OTOH writing code for the FFI +library is not for the faint of heart and probably shouldn't be the +first exercise for someone with little experience in Lua, C or C++. +</p> +<p> +As a corollary of the above, the FFI library is <b>not safe for use by +untrusted Lua code</b>. If you're sandboxing untrusted Lua code, you +definitely don't want to give this code access to the FFI library or +to <em>any</em> cdata object (except 64 bit integers or complex +numbers). Any properly engineered Lua sandbox needs to provide safety +wrappers for many of the standard Lua library functions — +similar wrappers need to be written for high-level operations on FFI +data types, too. +</p> + +<h2 id="status">Current Status</h2> +<p> +The initial release of the FFI library has some limitations and is +missing some features. Most of these will be fixed in future releases. +</p> +<p> +<a href="#clang">C language support</a> is +currently incomplete: +</p> +<ul> +<li>C declarations are not passed through a C pre-processor, +yet.</li> +<li>The C parser is able to evaluate most constant expressions +commonly found in C header files. However it doesn't handle the +full range of C expression semantics and may fail for some +obscure constructs.</li> +<li><tt>static const</tt> declarations only work for integer types +up to 32 bits. Neither declaring string constants nor +floating-point constants is supported.</li> +<li>Packed <tt>struct</tt> bitfields that cross container boundaries +are not implemented.</li> +<li>Native vector types may be defined with the GCC <tt>mode</tt> or +<tt>vector_size</tt> attribute. But no operations other than loading, +storing and initializing them are supported, yet.</li> +<li>The <tt>volatile</tt> type qualifier is currently ignored by +compiled code.</li> +<li><a href="ext_ffi_api.html#ffi_cdef"><tt>ffi.cdef</tt></a> silently +ignores most re-declarations. Note: avoid re-declarations which do not +conform to C99. The implementation will eventually be changed to +perform strict checks.</li> +</ul> +<p> +The JIT compiler already handles a large subset of all FFI operations. +It automatically falls back to the interpreter for unimplemented +operations (you can check for this with the +<a href="running.html#opt_j"><tt>-jv</tt></a> command line option). +The following operations are currently not compiled and may exhibit +suboptimal performance, especially when used in inner loops: +</p> +<ul> +<li>Bitfield accesses and initializations.</li> +<li>Vector operations.</li> +<li>Table initializers.</li> +<li>Initialization of nested <tt>struct</tt>/<tt>union</tt> types.</li> +<li>Allocations of variable-length arrays or structs.</li> +<li>Allocations of C types with a size > 128 bytes or an +alignment > 8 bytes.</li> +<li>Conversions from lightuserdata to <tt>void *</tt>.</li> +<li>Pointer differences for element sizes that are not a power of +two.</li> +<li>Calls to C functions with aggregates passed or returned by +value.</li> +<li>Calls to ctype metamethods which are not plain functions.</li> +<li>ctype <tt>__newindex</tt> tables and non-string lookups in ctype +<tt>__index</tt> tables.</li> +<li><tt>tostring()</tt> for cdata types.</li> +<li>Calls to <tt>ffi.cdef()</tt>, <tt>ffi.load()</tt> and +<tt>ffi.metatype()</tt>.</li> +</ul> +<p> +Other missing features: +</p> +<ul> +<li>Bit operations for 64 bit types.</li> +<li>Arithmetic for <tt>complex</tt> numbers.</li> +<li>Passing structs by value to vararg C functions.</li> +<li><a href="extensions.html#exceptions">C++ exception interoperability</a> +does not extend to C functions called via the FFI, if the call is +compiled.</li> +</ul> +<br class="flush"> +</div> +<div id="foot"> +<hr class="hide"> +Copyright © 2005-2014 Mike Pall +<span class="noprint"> +· +<a href="contact.html">Contact</a> +</span> +</div> +</body> +</html> diff --git a/Build/source/libs/luajit/LuaJIT-2.0.3/doc/ext_ffi_tutorial.html b/Build/source/libs/luajit/LuaJIT-2.0.3/doc/ext_ffi_tutorial.html new file mode 100644 index 00000000000..01fb89929c4 --- /dev/null +++ b/Build/source/libs/luajit/LuaJIT-2.0.3/doc/ext_ffi_tutorial.html @@ -0,0 +1,601 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> +<html> +<head> +<title>FFI Tutorial</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-2014, 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.idiomtable { font-size: 90%; line-height: 1.2; } +table.idiomtable tt { font-size: 100%; } +table.idiomtable td { vertical-align: top; } +tr.idiomhead td { font-weight: bold; } +td.idiomlua b { font-weight: normal; color: #2142bf; } +</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>FFI Tutorial</h1> +</div> +<div id="nav"> +<ul><li> +<a href="luajit.html">LuaJIT</a> +<ul><li> +<a href="http://luajit.org/download.html">Download <span class="ext">»</span></a> +</li><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_ffi.html">FFI Library</a> +<ul><li> +<a class="current" 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_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://wiki.luajit.org/">Wiki <span class="ext">»</span></a> +</li><li> +<a href="http://luajit.org/list.html">Mailing List <span class="ext">»</span></a> +</li></ul> +</div> +<div id="main"> +<p> +This page is intended to give you an overview of the features of the FFI +library by presenting a few use cases and guidelines. +</p> +<p> +This page makes no attempt to explain all of the FFI library, though. +You'll want to have a look at the <a href="ext_ffi_api.html">ffi.* API +function reference</a> and the <a href="ext_ffi_semantics.html">FFI +semantics</a> to learn more. +</p> + +<h2 id="load">Loading the FFI Library</h2> +<p> +The FFI library is built into LuaJIT by default, but it's not loaded +and initialized by default. The suggested way to use the FFI library +is to add the following to the start of every Lua file that needs one +of its functions: +</p> +<pre class="code"> +local ffi = require("ffi") +</pre> +<p> +Please note this doesn't define an <tt>ffi</tt> variable in the table +of globals — you really need to use the local variable. The +<tt>require</tt> function ensures the library is only loaded once. +</p> +<p style="font-size: 8pt;"> +Note: If you want to experiment with the FFI from the interactive prompt +of the command line executable, omit the <tt>local</tt>, as it doesn't +preserve local variables across lines. +</p> + +<h2 id="sleep">Accessing Standard System Functions</h2> +<p> +The following code explains how to access standard system functions. +We slowly print two lines of dots by sleeping for 10 milliseconds +after each dot: +</p> +<pre class="code mark"> +<span class="codemark"> +① + + + + + +② +③ +④ + + + +⑤ + + + + + +⑥</span>local ffi = require("ffi") +ffi.cdef[[ +<span style="color:#00a000;">void Sleep(int ms); +int poll(struct pollfd *fds, unsigned long nfds, int timeout);</span> +]] + +local sleep +if ffi.os == "Windows" then + function sleep(s) + ffi.C.Sleep(s*1000) + end +else + function sleep(s) + ffi.C.poll(nil, 0, s*1000) + end +end + +for i=1,160 do + io.write("."); io.flush() + sleep(0.01) +end +io.write("\n") +</pre> +<p> +Here's the step-by-step explanation: +</p> +<p> +<span class="mark">①</span> This defines the +C library functions we're going to use. The part inside the +double-brackets (in green) is just standard C syntax. You can +usually get this info from the C header files or the +documentation provided by each C library or C compiler. +</p> +<p> +<span class="mark">②</span> The difficulty we're +facing here, is that there are different standards to choose from. +Windows has a simple <tt>Sleep()</tt> function. On other systems there +are a variety of functions available to achieve sub-second sleeps, but +with no clear consensus. Thankfully <tt>poll()</tt> can be used for +this task, too, and it's present on most non-Windows systems. The +check for <tt>ffi.os</tt> makes sure we use the Windows-specific +function only on Windows systems. +</p> +<p> +<span class="mark">③</span> Here we're wrapping the +call to the C function in a Lua function. This isn't strictly +necessary, but it's helpful to deal with system-specific issues only +in one part of the code. The way we're wrapping it ensures the check +for the OS is only done during initialization and not for every call. +</p> +<p> +<span class="mark">④</span> A more subtle point is +that we defined our <tt>sleep()</tt> function (for the sake of this +example) as taking the number of seconds, but accepting fractional +seconds. Multiplying this by 1000 gets us milliseconds, but that still +leaves it a Lua number, which is a floating-point value. Alas, the +<tt>Sleep()</tt> function only accepts an integer value. Luckily for +us, the FFI library automatically performs the conversion when calling +the function (truncating the FP value towards zero, like in C). +</p> +<p style="font-size: 8pt;"> +Some readers will notice that <tt>Sleep()</tt> is part of +<tt>KERNEL32.DLL</tt> and is also a <tt>stdcall</tt> function. So how +can this possibly work? The FFI library provides the <tt>ffi.C</tt> +default C library namespace, which allows calling functions from +the default set of libraries, like a C compiler would. Also, the +FFI library automatically detects <tt>stdcall</tt> functions, so you +don't need to declare them as such. +</p> +<p> +<span class="mark">⑤</span> The <tt>poll()</tt> +function takes a couple more arguments we're not going to use. You can +simply use <tt>nil</tt> to pass a <tt>NULL</tt> pointer and <tt>0</tt> +for the <tt>nfds</tt> parameter. Please note that the +number <tt>0</tt> <em>does not convert to a pointer value</em>, +unlike in C++. You really have to pass pointers to pointer arguments +and numbers to number arguments. +</p> +<p style="font-size: 8pt;"> +The page on <a href="ext_ffi_semantics.html">FFI semantics</a> has all +of the gory details about +<a href="ext_ffi_semantics.html#convert">conversions between Lua +objects and C types</a>. For the most part you don't have to deal +with this, as it's performed automatically and it's carefully designed +to bridge the semantic differences between Lua and C. +</p> +<p> +<span class="mark">⑥</span> Now that we have defined +our own <tt>sleep()</tt> function, we can just call it from plain Lua +code. That wasn't so bad, huh? Turning these boring animated dots into +a fascinating best-selling game is left as an exercise for the reader. +:-) +</p> + +<h2 id="zlib">Accessing the zlib Compression Library</h2> +<p> +The following code shows how to access the <a +href="http://zlib.net/">zlib</a> compression library from Lua code. +We'll define two convenience wrapper functions that take a string and +compress or uncompress it to another string: +</p> +<pre class="code mark"> +<span class="codemark"> +① + + + + + + +② + + +③ + +④ + + +⑤ + + +⑥ + + + + + + + +⑦</span>local ffi = require("ffi") +ffi.cdef[[ +<span style="color:#00a000;">unsigned long compressBound(unsigned long sourceLen); +int compress2(uint8_t *dest, unsigned long *destLen, + const uint8_t *source, unsigned long sourceLen, int level); +int uncompress(uint8_t *dest, unsigned long *destLen, + const uint8_t *source, unsigned long sourceLen);</span> +]] +local zlib = ffi.load(ffi.os == "Windows" and "zlib1" or "z") + +local function compress(txt) + local n = zlib.compressBound(#txt) + local buf = ffi.new("uint8_t[?]", n) + local buflen = ffi.new("unsigned long[1]", n) + local res = zlib.compress2(buf, buflen, txt, #txt, 9) + assert(res == 0) + return ffi.string(buf, buflen[0]) +end + +local function uncompress(comp, n) + local buf = ffi.new("uint8_t[?]", n) + local buflen = ffi.new("unsigned long[1]", n) + local res = zlib.uncompress(buf, buflen, comp, #comp) + assert(res == 0) + return ffi.string(buf, buflen[0]) +end + +-- Simple test code. +local txt = string.rep("abcd", 1000) +print("Uncompressed size: ", #txt) +local c = compress(txt) +print("Compressed size: ", #c) +local txt2 = uncompress(c, #txt) +assert(txt2 == txt) +</pre> +<p> +Here's the step-by-step explanation: +</p> +<p> +<span class="mark">①</span> This defines some of the +C functions provided by zlib. For the sake of this example, some +type indirections have been reduced and it uses the pre-defined +fixed-size integer types, while still adhering to the zlib API/ABI. +</p> +<p> +<span class="mark">②</span> This loads the zlib shared +library. On POSIX systems it's named <tt>libz.so</tt> and usually +comes pre-installed. Since <tt>ffi.load()</tt> automatically adds any +missing standard prefixes/suffixes, we can simply load the +<tt>"z"</tt> library. On Windows it's named <tt>zlib1.dll</tt> and +you'll have to download it first from the +<a href="http://zlib.net/"><span class="ext">»</span> zlib site</a>. The check for +<tt>ffi.os</tt> makes sure we pass the right name to +<tt>ffi.load()</tt>. +</p> +<p> +<span class="mark">③</span> First, the maximum size of +the compression buffer is obtained by calling the +<tt>zlib.compressBound</tt> function with the length of the +uncompressed string. The next line allocates a byte buffer of this +size. The <tt>[?]</tt> in the type specification indicates a +variable-length array (VLA). The actual number of elements of this +array is given as the 2nd argument to <tt>ffi.new()</tt>. +</p> +<p> +<span class="mark">④</span> This may look strange at +first, but have a look at the declaration of the <tt>compress2</tt> +function from zlib: the destination length is defined as a pointer! +This is because you pass in the maximum buffer size and get back the +actual length that was used. +</p> +<p> +In C you'd pass in the address of a local variable +(<tt>&buflen</tt>). But since there's no address-of operator in +Lua, we'll just pass in a one-element array. Conveniently it can be +initialized with the maximum buffer size in one step. Calling the +actual <tt>zlib.compress2</tt> function is then straightforward. +</p> +<p> +<span class="mark">⑤</span> We want to return the +compressed data as a Lua string, so we'll use <tt>ffi.string()</tt>. +It needs a pointer to the start of the data and the actual length. The +length has been returned in the <tt>buflen</tt> array, so we'll just +get it from there. +</p> +<p style="font-size: 8pt;"> +Note that since the function returns now, the <tt>buf</tt> and +<tt>buflen</tt> variables will eventually be garbage collected. This +is fine, because <tt>ffi.string()</tt> has copied the contents to a +newly created (interned) Lua string. If you plan to call this function +lots of times, consider reusing the buffers and/or handing back the +results in buffers instead of strings. This will reduce the overhead +for garbage collection and string interning. +</p> +<p> +<span class="mark">⑥</span> The <tt>uncompress</tt> +functions does the exact opposite of the <tt>compress</tt> function. +The compressed data doesn't include the size of the original string, +so this needs to be passed in. Otherwise no surprises here. +</p> +<p> +<span class="mark">⑦</span> The code, that makes use +of the functions we just defined, is just plain Lua code. It doesn't +need to know anything about the LuaJIT FFI — the convenience +wrapper functions completely hide it. +</p> +<p> +One major advantage of the LuaJIT FFI is that you are now able to +write those wrappers <em>in Lua</em>. And at a fraction of the time it +would cost you to create an extra C module using the Lua/C API. +Many of the simpler C functions can probably be used directly +from your Lua code, without any wrappers. +</p> +<p style="font-size: 8pt;"> +Side note: the zlib API uses the <tt>long</tt> type for passing +lengths and sizes around. But all those zlib functions actually only +deal with 32 bit values. This is an unfortunate choice for a +public API, but may be explained by zlib's history — we'll just +have to deal with it. +</p> +<p style="font-size: 8pt;"> +First, you should know that a <tt>long</tt> is a 64 bit type e.g. +on POSIX/x64 systems, but a 32 bit type on Windows/x64 and on +32 bit systems. Thus a <tt>long</tt> result can be either a plain +Lua number or a boxed 64 bit integer cdata object, depending on +the target system. +</p> +<p style="font-size: 8pt;"> +Ok, so the <tt>ffi.*</tt> functions generally accept cdata objects +wherever you'd want to use a number. That's why we get a away with +passing <tt>n</tt> to <tt>ffi.string()</tt> above. But other Lua +library functions or modules don't know how to deal with this. So for +maximum portability one needs to use <tt>tonumber()</tt> on returned +<tt>long</tt> results before passing them on. Otherwise the +application might work on some systems, but would fail in a POSIX/x64 +environment. +</p> + +<h2 id="metatype">Defining Metamethods for a C Type</h2> +<p> +The following code explains how to define metamethods for a C type. +We define a simple point type and add some operations to it: +</p> +<pre class="code mark"> +<span class="codemark"> +① + + + +② + +③ + +④ + + + +⑤ + +⑥</span>local ffi = require("ffi") +ffi.cdef[[ +<span style="color:#00a000;">typedef struct { double x, y; } point_t;</span> +]] + +local point +local mt = { + __add = function(a, b) return point(a.x+b.x, a.y+b.y) end, + __len = function(a) return math.sqrt(a.x*a.x + a.y*a.y) end, + __index = { + area = function(a) return a.x*a.x + a.y*a.y end, + }, +} +point = ffi.metatype("point_t", mt) + +local a = point(3, 4) +print(a.x, a.y) --> 3 4 +print(#a) --> 5 +print(a:area()) --> 25 +local b = a + point(0.5, 8) +print(#b) --> 12.5 +</pre> +<p> +Here's the step-by-step explanation: +</p> +<p> +<span class="mark">①</span> This defines the C type for a +two-dimensional point object. +</p> +<p> +<span class="mark">②</span> We have to declare the variable +holding the point constructor first, because it's used inside of a +metamethod. +</p> +<p> +<span class="mark">③</span> Let's define an <tt>__add</tt> +metamethod which adds the coordinates of two points and creates a new +point object. For simplicity, this function assumes that both arguments +are points. But it could be any mix of objects, if at least one operand +is of the required type (e.g. adding a point plus a number or vice +versa). Our <tt>__len</tt> metamethod returns the distance of a point to +the origin. +</p> +<p> +<span class="mark">④</span> If we run out of operators, we can +define named methods, too. Here the <tt>__index</tt> table defines an +<tt>area</tt> function. For custom indexing needs, one might want to +define <tt>__index</tt> and <tt>__newindex</tt> <em>functions</em> instead. +</p> +<p> +<span class="mark">⑤</span> This associates the metamethods with +our C type. This only needs to be done once. For convenience, a +constructor is returned by +<a href="ext_ffi_api.html#ffi_metatype"><tt>ffi.metatype()</tt></a>. +We're not required to use it, though. The original C type can still +be used e.g. to create an array of points. The metamethods automatically +apply to any and all uses of this type. +</p> +<p> +Please note that the association with a metatable is permanent and +<b>the metatable must not be modified afterwards!</b> Ditto for the +<tt>__index</tt> table. +</p> +<p> +<span class="mark">⑥</span> Here are some simple usage examples +for the point type and their expected results. The pre-defined +operations (such as <tt>a.x</tt>) can be freely mixed with the newly +defined metamethods. Note that <tt>area</tt> is a method and must be +called with the Lua syntax for methods: <tt>a:area()</tt>, not +<tt>a.area()</tt>. +</p> +<p> +The C type metamethod mechanism is most useful when used in +conjunction with C libraries that are written in an object-oriented +style. Creators return a pointer to a new instance and methods take an +instance pointer as the first argument. Sometimes you can just point +<tt>__index</tt> to the library namespace and <tt>__gc</tt> to the +destructor and you're done. But often enough you'll want to add +convenience wrappers, e.g. to return actual Lua strings or when +returning multiple values. +</p> +<p> +Some C libraries only declare instance pointers as an opaque +<tt>void *</tt> type. In this case you can use a fake type for all +declarations, e.g. a pointer to a named (incomplete) struct will do: +<tt>typedef struct foo_type *foo_handle</tt>. The C side doesn't +know what you declare with the LuaJIT FFI, but as long as the underlying +types are compatible, everything still works. +</p> + +<h2 id="idioms">Translating C Idioms</h2> +<p> +Here's a list of common C idioms and their translation to the +LuaJIT FFI: +</p> +<table class="idiomtable"> +<tr class="idiomhead"> +<td class="idiomdesc">Idiom</td> +<td class="idiomc">C code</td> +<td class="idiomlua">Lua code</td> +</tr> +<tr class="odd separate"> +<td class="idiomdesc">Pointer dereference<br><tt>int *p;</tt></td><td class="idiomc"><tt>x = *p;<br>*p = y;</tt></td><td class="idiomlua"><tt>x = <b>p[0]</b><br><b>p[0]</b> = y</tt></td></tr> +<tr class="even"> +<td class="idiomdesc">Pointer indexing<br><tt>int i, *p;</tt></td><td class="idiomc"><tt>x = p[i];<br>p[i+1] = y;</tt></td><td class="idiomlua"><tt>x = p[i]<br>p[i+1] = y</tt></td></tr> +<tr class="odd"> +<td class="idiomdesc">Array indexing<br><tt>int i, a[];</tt></td><td class="idiomc"><tt>x = a[i];<br>a[i+1] = y;</tt></td><td class="idiomlua"><tt>x = a[i]<br>a[i+1] = y</tt></td></tr> +<tr class="even separate"> +<td class="idiomdesc"><tt>struct</tt>/<tt>union</tt> dereference<br><tt>struct foo s;</tt></td><td class="idiomc"><tt>x = s.field;<br>s.field = y;</tt></td><td class="idiomlua"><tt>x = s.field<br>s.field = y</tt></td></tr> +<tr class="odd"> +<td class="idiomdesc"><tt>struct</tt>/<tt>union</tt> pointer deref.<br><tt>struct foo *sp;</tt></td><td class="idiomc"><tt>x = sp->field;<br>sp->field = y;</tt></td><td class="idiomlua"><tt>x = <b>s.field</b><br><b>s.field</b> = y</tt></td></tr> +<tr class="even separate"> +<td class="idiomdesc">Pointer arithmetic<br><tt>int i, *p;</tt></td><td class="idiomc"><tt>x = p + i;<br>y = p - i;</tt></td><td class="idiomlua"><tt>x = p + i<br>y = p - i</tt></td></tr> +<tr class="odd"> +<td class="idiomdesc">Pointer difference<br><tt>int *p1, *p2;</tt></td><td class="idiomc"><tt>x = p1 - p2;</tt></td><td class="idiomlua"><tt>x = p1 - p2</tt></td></tr> +<tr class="even"> +<td class="idiomdesc">Array element pointer<br><tt>int i, a[];</tt></td><td class="idiomc"><tt>x = &a[i];</tt></td><td class="idiomlua"><tt>x = <b>a+i</b></tt></td></tr> +<tr class="odd"> +<td class="idiomdesc">Cast pointer to address<br><tt>int *p;</tt></td><td class="idiomc"><tt>x = (intptr_t)p;</tt></td><td class="idiomlua"><tt>x = <b>tonumber(<br> ffi.cast("intptr_t",<br> p))</b></tt></td></tr> +<tr class="even separate"> +<td class="idiomdesc">Functions with outargs<br><tt>void foo(int *inoutlen);</tt></td><td class="idiomc"><tt>int len = x;<br>foo(&len);<br>y = len;</tt></td><td class="idiomlua"><tt><b>local len =<br> ffi.new("int[1]", x)<br>foo(len)<br>y = len[0]</b></tt></td></tr> +<tr class="odd"> +<td class="idiomdesc"><a href="ext_ffi_semantics.html#convert_vararg">Vararg conversions</a><br><tt>int printf(char *fmt, ...);</tt></td><td class="idiomc"><tt>printf("%g", 1.0);<br>printf("%d", 1);<br> </tt></td><td class="idiomlua"><tt>printf("%g", 1);<br>printf("%d",<br> <b>ffi.new("int", 1)</b>)</tt></td></tr> +</table> + +<h2 id="cache">To Cache or Not to Cache</h2> +<p> +It's a common Lua idiom to cache library functions in local variables +or upvalues, e.g.: +</p> +<pre class="code"> +local byte, char = string.byte, string.char +local function foo(x) + return char(byte(x)+1) +end +</pre> +<p> +This replaces several hash-table lookups with a (faster) direct use of +a local or an upvalue. This is less important with LuaJIT, since the +JIT compiler optimizes hash-table lookups a lot and is even able to +hoist most of them out of the inner loops. It can't eliminate +<em>all</em> of them, though, and it saves some typing for often-used +functions. So there's still a place for this, even with LuaJIT. +</p> +<p> +The situation is a bit different with C function calls via the +FFI library. The JIT compiler has special logic to eliminate <em>all +of the lookup overhead</em> for functions resolved from a +<a href="ext_ffi_semantics.html#clib">C library namespace</a>! +Thus it's not helpful and actually counter-productive to cache +individual C functions like this: +</p> +<pre class="code"> +local <b>funca</b>, <b>funcb</b> = ffi.C.funcb, ffi.C.funcb -- <span style="color:#c00000;">Not helpful!</span> +local function foo(x, n) + for i=1,n do <b>funcb</b>(<b>funca</b>(x, i), 1) end +end +</pre> +<p> +This turns them into indirect calls and generates bigger and slower +machine code. Instead you'll want to cache the namespace itself and +rely on the JIT compiler to eliminate the lookups: +</p> +<pre class="code"> +local <b>C</b> = ffi.C -- <span style="color:#00a000;">Instead use this!</span> +local function foo(x, n) + for i=1,n do <b>C.funcb</b>(<b>C.funca</b>(x, i), 1) end +end +</pre> +<p> +This generates both shorter and faster code. So <b>don't cache +C functions</b>, but <b>do</b> cache namespaces! Most often the +namespace is already in a local variable at an outer scope, e.g. from +<tt>local lib = ffi.load(...)</tt>. Note that copying +it to a local variable in the function scope is unnecessary. +</p> +<br class="flush"> +</div> +<div id="foot"> +<hr class="hide"> +Copyright © 2005-2014 Mike Pall +<span class="noprint"> +· +<a href="contact.html">Contact</a> +</span> +</div> +</body> +</html> diff --git a/Build/source/libs/luajit/LuaJIT-2.0.3/doc/ext_jit.html b/Build/source/libs/luajit/LuaJIT-2.0.3/doc/ext_jit.html new file mode 100644 index 00000000000..098be5e06a5 --- /dev/null +++ b/Build/source/libs/luajit/LuaJIT-2.0.3/doc/ext_jit.html @@ -0,0 +1,199 @@ +<!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-2014, 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="http://luajit.org/download.html">Download <span class="ext">»</span></a> +</li><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_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_semantics.html">FFI Semantics</a> +</li></ul> +</li><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://wiki.luajit.org/">Wiki <span class="ext">»</span></a> +</li><li> +<a href="http://luajit.org/list.html">Mailing List <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. Note that JIT-compilation is fully automatic — +you probably won't need to use any of the following functions unless +you have special needs. +</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 root trace, specified by its number, 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_os"><tt>jit.os</tt></h3> +<p> +Contains the target OS name: +"Windows", "Linux", "OSX", "BSD", "POSIX" or "Other". +</p> + +<h3 id="jit_arch"><tt>jit.arch</tt></h3> +<p> +Contains the target architecture name: +"x86", "x64" or "ppcspe". +</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-2014 Mike Pall +<span class="noprint"> +· +<a href="contact.html">Contact</a> +</span> +</div> +</body> +</html> diff --git a/Build/source/libs/luajit/LuaJIT-2.0.3/doc/extensions.html b/Build/source/libs/luajit/LuaJIT-2.0.3/doc/extensions.html new file mode 100644 index 00000000000..20b597f132e --- /dev/null +++ b/Build/source/libs/luajit/LuaJIT-2.0.3/doc/extensions.html @@ -0,0 +1,408 @@ +<!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-2014, 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="http://luajit.org/download.html">Download <span class="ext">»</span></a> +</li><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_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://wiki.luajit.org/">Wiki <span class="ext">»</span></a> +</li><li> +<a href="http://luajit.org/list.html">Mailing List <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 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="tonumber"><tt>tonumber()</tt> etc. use builtin string to number conversion</h3> +<p> +All string-to-number conversions consistently convert integer and +floating-point inputs in decimal and hexadecimal on all platforms. +<tt>strtod()</tt> is <em>not</em> 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. <tt>0x1.5p-3</tt>). +</p> + +<h3 id="string_dump"><tt>string.dump(f [,strip])</tt> generates portable bytecode</h3> +<p> +An extra argument has been added to <tt>string.dump()</tt>. If set to +<tt>true</tt>, 'stripped' bytecode without debug information is +generated. This speeds up later bytecode loading and reduces memory +usage. See also the +<a href="running.html#opt_b"><tt>-b</tt> command line option</a>. +</p> +<p> +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 → x.y.1), but may change with major or +minor releases (2.0 → 2.1) or between any beta release. Foreign +bytecode (e.g. from Lua 5.1) is incompatible and cannot be loaded. +</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.0 and 1.0. +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 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> + +<h2 id="lua52">Extensions from Lua 5.2</h2> +<p> +LuaJIT supports some language and library extensions from Lua 5.2. +Features that are unlikely to break existing code are unconditionally +enabled: +</p> +<ul> +<li><tt>goto</tt> and <tt>::labels::</tt>.</li> +<li>Hex escapes <tt>'\x3F'</tt> and <tt>'\*'</tt> escape in strings.</li> +<li><tt>load(string|reader [, chunkname [,mode [,env]]])</tt>.</li> +<li><tt>loadstring()</tt> is an alias for <tt>load()</tt>.</li> +<li><tt>loadfile(filename [,mode [,env]])</tt>.</li> +<li><tt>math.log(x [,base])</tt>. +<li><tt>string.rep(s, n [,sep])</tt>. +<li><tt>string.format()</tt>: <tt>%q</tt> reversible. +<tt>%s</tt> checks <tt>__tostring</tt>. +<tt>%a</tt> and <tt>"%A</tt> added.</li> +<li>String matching pattern <tt>%g</tt> added.</li> +<li><tt>io.read("*L")</tt>.</li> +<li><tt>io.lines()</tt> and <tt>file:lines()</tt> process +<tt>io.read()</tt> options.</li> +<li><tt>os.exit(status|true|false [,close])</tt>.</li> +<li><tt>package.searchpath(name, path [, sep [, rep]])</tt>.</li> +<li><tt>package.loadlib(name, "*")</tt>.</li> +<li><tt>debug.getinfo()</tt> returns <tt>nparams</tt> and <tt>isvararg</tt> +for option <tt>"u"</tt>.</li> +<li><tt>debug.getlocal()</tt> accepts function instead of level.</li> +<li><tt>debug.getlocal()</tt> and <tt>debug.setlocal()</tt> accept negative +indexes for varargs.</li> +<li><tt>debug.getupvalue()</tt> and <tt>debug.setupvalue()</tt> handle +C functions.</li> +<li><tt>debug.upvalueid()</tt> and <tt>debug.upvaluejoin()</tt>.</li> +<li>Command line option <tt>-E</tt>.</li> +<li>Command line checks <tt>__tostring</tt> for errors.</li> +</ul> +<p> +Other features are only enabled, if LuaJIT is built with +<tt>-DLUAJIT_ENABLE_LUA52COMPAT</tt>: +</p> +<ul> +<li><tt>goto</tt> is a keyword and not a valid variable name anymore.</li> +<li><tt>break</tt> can be placed anywhere. Empty statements (<tt>;;</tt>) +are allowed.</li> +<li><tt>__lt</tt>, <tt>__le</tt> are invoked for mixed types.</li> +<li><tt>__len</tt> for tables. <tt>rawlen()</tt> library function.</li> +<li><tt>pairs()</tt> and <tt>ipairs()</tt> check for <tt>__pairs</tt> and +<tt>__ipairs</tt>.</li> +<li><tt>coroutine.running()</tt> returns two results.</li> +<li><tt>table.pack()</tt> and <tt>table.unpack()</tt> +(same as <tt>unpack()</tt>).</li> +<li><tt>io.write()</tt> and <tt>file:write()</tt> return file handle +instead of <tt>true</tt>.</li> +<li><tt>os.execute()</tt> and <tt>pipe:close()</tt> return detailed +exit status.</li> +<li><tt>debug.setmetatable()</tt> returns object.</li> +<li><tt>debug.getuservalue()</tt> and <tt>debug.setuservalue()</tt>.</li> +<li>Remove <tt>math.mod()</tt>, <tt>string.gfind()</tt>. +</ul> +<p> +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. <tt>_ENV</tt>). +</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-2014 Mike Pall +<span class="noprint"> +· +<a href="contact.html">Contact</a> +</span> +</div> +</body> +</html> diff --git a/Build/source/libs/luajit/LuaJIT-2.0.3/doc/faq.html b/Build/source/libs/luajit/LuaJIT-2.0.3/doc/faq.html new file mode 100644 index 00000000000..ffc2ae89973 --- /dev/null +++ b/Build/source/libs/luajit/LuaJIT-2.0.3/doc/faq.html @@ -0,0 +1,184 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> +<html> +<head> +<title>Frequently Asked Questions (FAQ)</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-2014, 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"> +dd { margin-left: 1.5em; } +</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>Frequently Asked Questions (FAQ)</h1> +</div> +<div id="nav"> +<ul><li> +<a href="luajit.html">LuaJIT</a> +<ul><li> +<a href="http://luajit.org/download.html">Download <span class="ext">»</span></a> +</li><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_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_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 class="current" 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://wiki.luajit.org/">Wiki <span class="ext">»</span></a> +</li><li> +<a href="http://luajit.org/list.html">Mailing List <span class="ext">»</span></a> +</li></ul> +</div> +<div id="main"> +<dl> +<dt>Q: Where can I learn more about LuaJIT and Lua?</dt> +<dd> +<ul style="padding: 0;"> +<li>The <a href="http://luajit.org/list.html"><span class="ext">»</span> LuaJIT mailing list</a> focuses on topics +related to LuaJIT.</li> +<li>The <a href="http://wiki.luajit.org/"><span class="ext">»</span> LuaJIT wiki</a> gathers community +resources about LuaJIT.</li> +<li>News about Lua itself can be found at the +<a href="http://www.lua.org/lua-l.html"><span class="ext">»</span> Lua mailing list</a>. +The mailing list archives are worth checking out for older postings +about LuaJIT.</li> +<li>The <a href="http://lua.org"><span class="ext">»</span> main Lua.org site</a> has complete +<a href="http://www.lua.org/docs.html"><span class="ext">»</span> documentation</a> of the language +and links to books and papers about Lua.</li> +<li>The community-managed <a href="http://lua-users.org/wiki/"><span class="ext">»</span> Lua Wiki</a> +has information about diverse topics.</li> +</ul> +</dl> + +<dl> +<dt>Q: Where can I learn more about the compiler technology used by LuaJIT?</dt> +<dd> +I'm planning to write more documentation about the internals of LuaJIT. +In the meantime, please use the following Google Scholar searches +to find relevant papers:<br> +Search for: <a href="http://scholar.google.com/scholar?q=Trace+Compiler"><span class="ext">»</span> Trace Compiler</a><br> +Search for: <a href="http://scholar.google.com/scholar?q=JIT+Compiler"><span class="ext">»</span> JIT Compiler</a><br> +Search for: <a href="http://scholar.google.com/scholar?q=Dynamic+Language+Optimizations"><span class="ext">»</span> Dynamic Language Optimizations</a><br> +Search for: <a href="http://scholar.google.com/scholar?q=SSA+Form"><span class="ext">»</span> SSA Form</a><br> +Search for: <a href="http://scholar.google.com/scholar?q=Linear+Scan+Register+Allocation"><span class="ext">»</span> Linear Scan Register Allocation</a><br> +Here is a list of the <a href="http://article.gmane.org/gmane.comp.lang.lua.general/58908"><span class="ext">»</span> innovative features in LuaJIT</a>.<br> +And, you know, reading the source is of course the only way to enlightenment. :-) +</dd> +</dl> + +<dl> +<dt>Q: Why do I get this error: "attempt to index global 'arg' (a nil value)"?<br> +Q: My vararg functions fail after switching to LuaJIT!</dt> +<dd>LuaJIT is compatible to the Lua 5.1 language standard. It doesn't +support the implicit <tt>arg</tt> parameter for old-style vararg +functions from Lua 5.0.<br>Please convert your code to the +<a href="http://www.lua.org/manual/5.1/manual.html#2.5.9"><span class="ext">»</span> Lua 5.1 +vararg syntax</a>.</dd> +</dl> + +<dl> +<dt>Q: Why do I get this error: "bad FPU precision"?<br> +<dt>Q: I get weird behavior after initializing Direct3D.<br> +<dt>Q: Some FPU operations crash after I load a Delphi DLL.<br> +</dt> +<dd> + +DirectX/Direct3D (up to version 9) sets the x87 FPU to single-precision +mode by default. This violates the Windows ABI and interferes with the +operation of many programs — LuaJIT is affected, too. Please make +sure you always use the <tt>D3DCREATE_FPU_PRESERVE</tt> flag when +initializing Direct3D.<br> + +Direct3D version 10 or higher do not show this behavior anymore. +Consider testing your application with older versions, too.<br> + +Similarly, the Borland/Delphi runtime modifies the FPU control word and +enables FP exceptions. Of course this violates the Windows ABI, too. +Please check the Delphi docs for the Set8087CW method. + +</dl> + +<dl> +<dt>Q: Sometimes Ctrl-C fails to stop my Lua program. Why?</dt> +<dd>The interrupt signal handler sets a Lua debug hook. But this is +currently ignored by compiled code (this will eventually be fixed). If +your program is running in a tight loop and never falls back to the +interpreter, the debug hook never runs and can't throw the +"interrupted!" error.<br> In the meantime you have to press Ctrl-C +twice to get stop your program. That's similar to when it's stuck +running inside a C function under the Lua interpreter.</dd> +</dl> + +<dl> +<dt>Q: Why doesn't my favorite power-patch for Lua apply against LuaJIT?</dt> +<dd>Because it's a completely redesigned VM and has very little code +in common with Lua anymore. Also, if the patch introduces changes to +the Lua semantics, these would need to be reflected everywhere in the +VM, from the interpreter up to all stages of the compiler.<br> Please +use only standard Lua language constructs. For many common needs you +can use source transformations or use wrapper or proxy functions. +The compiler will happily optimize away such indirections.</dd> +</dl> + +<dl> +<dt>Q: Lua runs everywhere. Why doesn't LuaJIT support my CPU?</dt> +<dd>Because it's a compiler — it needs to generate native +machine code. This means the code generator must be ported to each +architecture. And the fast interpreter is written in assembler and +must be ported, too. This is quite an undertaking.<br> +The <a href="install.html">install documentation</a> shows the supported +architectures. Other architectures will follow based on sufficient user +demand and/or sponsoring.</dd> +</dl> + +<dl> +<dt>Q: When will feature X be added? When will the next version be released?</dt> +<dd>When it's ready.<br> +C'mon, it's open source — I'm doing it on my own time and you're +getting it for free. You can either contribute a patch or sponsor +the development of certain features, if they are important to you. +</dd> +</dl> +<br class="flush"> +</div> +<div id="foot"> +<hr class="hide"> +Copyright © 2005-2014 Mike Pall +<span class="noprint"> +· +<a href="contact.html">Contact</a> +</span> +</div> +</body> +</html> diff --git a/Build/source/libs/luajit/LuaJIT-2.0.3/doc/img/contact.png b/Build/source/libs/luajit/LuaJIT-2.0.3/doc/img/contact.png Binary files differnew file mode 100644 index 00000000000..9c73dc594ef --- /dev/null +++ b/Build/source/libs/luajit/LuaJIT-2.0.3/doc/img/contact.png diff --git a/Build/source/libs/luajit/LuaJIT-2.0.3/doc/install.html b/Build/source/libs/luajit/LuaJIT-2.0.3/doc/install.html new file mode 100644 index 00000000000..2388ff338e5 --- /dev/null +++ b/Build/source/libs/luajit/LuaJIT-2.0.3/doc/install.html @@ -0,0 +1,631 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> +<html> +<head> +<title>Installation</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-2014, 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.compat { + line-height: 1.2; + font-size: 80%; +} +table.compat td { + border: 1px solid #bfcfff; + height: 2.5em; +} +table.compat tr.compathead td { + font-weight: bold; + border-bottom: 2px solid #bfcfff; +} +tr.compathead td.compatos { + vertical-align: top; +} +table.compat td.compatcpu { + width: 18%; + border-right: 2px solid #bfcfff; +} +td.compatos { + width: 21%; + vertical-align: middle; +} +td.compatno { + background-color: #d0d0d0; +} +</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>Installation</h1> +</div> +<div id="nav"> +<ul><li> +<a href="luajit.html">LuaJIT</a> +<ul><li> +<a href="http://luajit.org/download.html">Download <span class="ext">»</span></a> +</li><li> +<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_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_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://wiki.luajit.org/">Wiki <span class="ext">»</span></a> +</li><li> +<a href="http://luajit.org/list.html">Mailing List <span class="ext">»</span></a> +</li></ul> +</div> +<div id="main"> +<p> +LuaJIT is only distributed as a source package. This page explains +how to build and install LuaJIT with different operating systems +and C compilers. +</p> +<p> +For the impatient (on POSIX systems): +</p> +<pre class="code"> +make && sudo make install +</pre> +<p> +LuaJIT currently builds out-of-the box on most systems. +Here's the compatibility matrix for the supported combinations of +operating systems, CPUs and compilers: +</p> +<table class="compat"> +<tr class="compathead"> +<td class="compatcpu">CPU / OS</td> +<td class="compatos"><a href="#posix">Linux</a> or<br><a href="#android">Android</a></td> +<td class="compatos"><a href="#posix">*BSD, Other</a></td> +<td class="compatos"><a href="#posix">OSX 10.4+</a> or<br><a href="#ios">iOS 3.0+</a></td> +<td class="compatos"><a href="#windows">Windows<br>XP/Vista/7</a></td> +</tr> +<tr class="odd separate"> +<td class="compatcpu">x86 (32 bit)</td> +<td class="compatos">GCC 4.x<br>GCC 3.4</td> +<td class="compatos">GCC 4.x<br>GCC 3.4</td> +<td class="compatos">GCC 4.x<br>GCC 3.4</td> +<td class="compatos">MSVC, MSVC/EE<br>WinSDK<br>MinGW, Cygwin</td> +</tr> +<tr class="even"> +<td class="compatcpu">x64 (64 bit)</td> +<td class="compatos">GCC 4.x</td> +<td class="compatos">ORBIS (<a href="#ps4">PS4</a>)</td> +<td class="compatos">GCC 4.x</td> +<td class="compatos">MSVC + SDK v7.0<br>WinSDK v7.0</td> +</tr> +<tr class="odd"> +<td class="compatcpu"><a href="#cross2">ARMv5+<br>ARM9E+</a></td> +<td class="compatos">GCC 4.2+</td> +<td class="compatos">GCC 4.2+</td> +<td class="compatos">GCC 4.2+</td> +<td class="compatos compatno"> </td> +</tr> +<tr class="even"> +<td class="compatcpu"><a href="#cross2">PPC</a></td> +<td class="compatos">GCC 4.3+</td> +<td class="compatos">GCC 4.3+<br>GCC 4.1 (<a href="#ps3">PS3</a>)</td> +<td class="compatos compatno"> </td> +<td class="compatos">XEDK (<a href="#xbox360">Xbox 360</a>)</td> +</tr> +<tr class="odd"> +<td class="compatcpu"><a href="#cross2">PPC/e500v2</a></td> +<td class="compatos">GCC 4.3+</td> +<td class="compatos">GCC 4.3+</td> +<td class="compatos compatno"> </td> +<td class="compatos compatno"> </td> +</tr> +<tr class="even"> +<td class="compatcpu"><a href="#cross2">MIPS</a></td> +<td class="compatos">GCC 4.3+</td> +<td class="compatos">GCC 4.3+</td> +<td class="compatos compatno"> </td> +<td class="compatos compatno"> </td> +</tr> +</table> + +<h2>Configuring LuaJIT</h2> +<p> +The standard configuration should work fine for most installations. +Usually there is no need to tweak the settings. The following files +hold all user-configurable settings: +</p> +<ul> +<li><tt>src/luaconf.h</tt> sets some configuration variables.</li> +<li><tt>Makefile</tt> has settings for <b>installing</b> LuaJIT (POSIX +only).</li> +<li><tt>src/Makefile</tt> has settings for <b>compiling</b> LuaJIT +under POSIX, MinGW or Cygwin.</li> +<li><tt>src/msvcbuild.bat</tt> has settings for compiling LuaJIT with +MSVC or WinSDK.</li> +</ul> +<p> +Please read the instructions given in these files, before changing +any settings. +</p> + +<h2 id="posix">POSIX Systems (Linux, OSX, *BSD etc.)</h2> +<h3>Prerequisites</h3> +<p> +Depending on your distribution, you may need to install a package for +GCC, the development headers and/or a complete SDK. E.g. on a current +Debian/Ubuntu, install <tt>libc6-dev</tt> with the package manager. +</p> +<p> +Download the current source package of LuaJIT (pick the .tar.gz), +if you haven't already done so. Move it to a directory of your choice, +open a terminal window and change to this directory. Now unpack the archive +and change to the newly created directory: +</p> +<pre class="code"> +tar zxf LuaJIT-2.0.3.tar.gz +cd LuaJIT-2.0.3</pre> +<h3>Building LuaJIT</h3> +<p> +The supplied Makefiles try to auto-detect the settings needed for your +operating system and your compiler. They need to be run with GNU Make, +which is probably the default on your system, anyway. Simply run: +</p> +<pre class="code"> +make +</pre> +<p> +This always builds a native x86, x64 or PPC binary, depending on the host OS +you're running this command on. Check the section on +<a href="#cross">cross-compilation</a> for more options. +</p> +<p> +By default, modules are only searched under the prefix <tt>/usr/local</tt>. +You can add an extra prefix to the search paths by appending the +<tt>PREFIX</tt> option, e.g.: +</p> +<pre class="code"> +make PREFIX=/home/myself/lj2 +</pre> +<p> +Note for OSX: if the <tt>MACOSX_DEPLOYMENT_TARGET</tt> environment +variable is not set, then it's forced to <tt>10.4</tt>. +</p> +<h3>Installing LuaJIT</h3> +<p> +The top-level Makefile installs LuaJIT by default under +<tt>/usr/local</tt>, i.e. the executable ends up in +<tt>/usr/local/bin</tt> and so on. You need root privileges +to write to this path. So, assuming sudo is installed on your system, +run the following command and enter your sudo password: +</p> +<pre class="code"> +sudo make install +</pre> +<p> +Otherwise specify the directory prefix as an absolute path, e.g.: +</p> +<pre class="code"> +make install PREFIX=/home/myself/lj2 +</pre> +<p> +Obviously the prefixes given during build and installation need to be the same. +</p> + +<h2 id="windows">Windows Systems</h2> +<h3>Prerequisites</h3> +<p> +Either install one of the open source SDKs +(<a href="http://mingw.org/"><span class="ext">»</span> MinGW</a> or +<a href="http://www.cygwin.com/"><span class="ext">»</span> Cygwin</a>), which come with a modified +GCC plus the required development headers. +</p> +<p> +Or install Microsoft's Visual C++ (MSVC). The freely downloadable +<a href="http://www.microsoft.com/Express/VC/"><span class="ext">»</span> Express Edition</a> +works just fine, but only contains an x86 compiler. +</p> +<p> +The freely downloadable +<a href="http://msdn.microsoft.com/en-us/windowsserver/bb980924.aspx"><span class="ext">»</span> Windows SDK</a> +only comes with command line tools, but this is all you need to build LuaJIT. +It contains x86 and x64 compilers. +</p> +<p> +Next, download the source package and unpack it using an archive manager +(e.g. the Windows Explorer) to a directory of your choice. +</p> +<h3>Building with MSVC</h3> +<p> +Open a "Visual Studio .NET Command Prompt", <tt>cd</tt> to the +directory where you've unpacked the sources and run these commands: +</p> +<pre class="code"> +cd src +msvcbuild +</pre> +<p> +Then follow the installation instructions below. +</p> +<h3>Building with the Windows SDK</h3> +<p> +Open a "Windows SDK Command Shell" and select the x86 compiler: +</p> +<pre class="code"> +setenv /release /x86 +</pre> +<p> +Or select the x64 compiler: +</p> +<pre class="code"> +setenv /release /x64 +</pre> +<p> +Then <tt>cd</tt> to the directory where you've unpacked the sources +and run these commands: +</p> +<pre class="code"> +cd src +msvcbuild +</pre> +<p> +Then follow the installation instructions below. +</p> +<h3>Building with MinGW or Cygwin</h3> +<p> +Open a command prompt window and make sure the MinGW or Cygwin programs +are in your path. Then <tt>cd</tt> to the directory where +you've unpacked the sources and run this command for MinGW: +</p> +<pre class="code"> +mingw32-make +</pre> +<p> +Or this command for Cygwin: +</p> +<pre class="code"> +make +</pre> +<p> +Then follow the installation instructions below. +</p> +<h3>Installing LuaJIT</h3> +<p> +Copy <tt>luajit.exe</tt> and <tt>lua51.dll</tt> (built in the <tt>src</tt> +directory) to a newly created directory (any location is ok). +Add <tt>lua</tt> and <tt>lua\jit</tt> directories below it and copy +all Lua files from the <tt>src\jit</tt> directory of the distribution +to the latter directory. +</p> +<p> +There are no hardcoded +absolute path names — all modules are loaded relative to the +directory where <tt>luajit.exe</tt> is installed +(see <tt>src/luaconf.h</tt>). +</p> + +<h2 id="cross">Cross-compiling LuaJIT</h2> +<p> +The GNU Makefile-based build system allows cross-compiling on any host +for any supported target, as long as both architectures have the same +pointer size. If you want to cross-compile to any 32 bit target on an +x64 OS, you need to install the multilib development package (e.g. +<tt>libc6-dev-i386</tt> on Debian/Ubuntu) and build a 32 bit host part +(<tt>HOST_CC="gcc -m32"</tt>). +</p> +<p> +You need to specify <tt>TARGET_SYS</tt> whenever the host OS and the +target OS differ, or you'll get assembler or linker errors. E.g. if +you're compiling on a Windows or OSX host for embedded Linux or Android, +you need to add <tt>TARGET_SYS=Linux</tt> to the examples below. For a +minimal target OS, you may need to disable the built-in allocator in +<tt>src/Makefile</tt> and use <tt>TARGET_SYS=Other</tt>. The examples +below only show some popular targets — please check the comments +in <tt>src/Makefile</tt> for more details. +</p> +<pre class="code"> +# Cross-compile to a 32 bit binary on a multilib x64 OS +make CC="gcc -m32" + +# Cross-compile on Debian/Ubuntu for Windows (mingw32 package) +make HOST_CC="gcc -m32" CROSS=i586-mingw32msvc- TARGET_SYS=Windows +</pre> +<p id="cross2"> +The <tt>CROSS</tt> prefix allows specifying a standard GNU cross-compile +toolchain (Binutils, GCC and a matching libc). The prefix may vary +depending on the <tt>--target</tt> the toolchain was built for (note the +<tt>CROSS</tt> prefix has a trailing <tt>"-"</tt>). The examples below +use the canonical toolchain triplets for Linux. +</p> +<p> +Since there's often no easy way to detect CPU features at runtime, it's +important to compile with the proper CPU or architecture settings. You +can specify these when building the toolchain yourself. Or add +<tt>-mcpu=...</tt> or <tt>-march=...</tt> to <tt>TARGET_CFLAGS</tt>. For +ARM it's important to have the correct <tt>-mfloat-abi=...</tt> setting, +too. Otherwise LuaJIT may not run at the full performance of your target +CPU. +</p> +<pre class="code"> +# ARM soft-float +make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabi- \ + TARGET_CFLAGS="-mfloat-abi=soft" + +# ARM soft-float ABI with VFP (example for Cortex-A8) +make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabi- \ + TARGET_CFLAGS="-mcpu=cortex-a8 -mfloat-abi=softfp" + +# ARM hard-float ABI with VFP (armhf, requires recent toolchain) +make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabihf- + +# PPC +make HOST_CC="gcc -m32" CROSS=powerpc-linux-gnu- +# PPC/e500v2 (fast interpreter only) +make HOST_CC="gcc -m32" CROSS=powerpc-e500v2-linux-gnuspe- + +# MIPS big-endian +make HOST_CC="gcc -m32" CROSS=mips-linux- +# MIPS little-endian +make HOST_CC="gcc -m32" CROSS=mipsel-linux- +</pre> +<p> +You can cross-compile for <b id="android">Android</b> using the <a href="http://developer.android.com/sdk/ndk/index.html"><span class="ext">»</span> Android NDK</a>. +The environment variables need to match the install locations and the +desired target platform. E.g. Android 4.0 corresponds to ABI level 14. +For details check the folder <tt>docs</tt> in the NDK directory. +</p> +<p> +Only a few common variations for the different CPUs, ABIs and platforms +are listed. Please use your own judgement for which combination you want +to build/deploy or which lowest common denominator you want to pick: +</p> +<pre class="code"> +# Android/ARM, armeabi (ARMv5TE soft-float), Android 2.2+ (Froyo) +NDK=/opt/android/ndk +NDKABI=8 +NDKVER=$NDK/toolchains/arm-linux-androideabi-4.6 +NDKP=$NDKVER/prebuilt/linux-x86/bin/arm-linux-androideabi- +NDKF="--sysroot $NDK/platforms/android-$NDKABI/arch-arm" +make HOST_CC="gcc -m32" CROSS=$NDKP TARGET_FLAGS="$NDKF" + +# Android/ARM, armeabi-v7a (ARMv7 VFP), Android 4.0+ (ICS) +NDK=/opt/android/ndk +NDKABI=14 +NDKVER=$NDK/toolchains/arm-linux-androideabi-4.6 +NDKP=$NDKVER/prebuilt/linux-x86/bin/arm-linux-androideabi- +NDKF="--sysroot $NDK/platforms/android-$NDKABI/arch-arm" +NDKARCH="-march=armv7-a -mfloat-abi=softfp -Wl,--fix-cortex-a8" +make HOST_CC="gcc -m32" CROSS=$NDKP TARGET_FLAGS="$NDKF $NDKARCH" + +# Android/MIPS, mips (MIPS32R1 hard-float), Android 4.0+ (ICS) +NDK=/opt/android/ndk +NDKABI=14 +NDKVER=$NDK/toolchains/mipsel-linux-android-4.6 +NDKP=$NDKVER/prebuilt/linux-x86/bin/mipsel-linux-android- +NDKF="--sysroot $NDK/platforms/android-$NDKABI/arch-mips" +make HOST_CC="gcc -m32" CROSS=$NDKP TARGET_FLAGS="$NDKF" + +# Android/x86, x86 (i686 SSE3), Android 4.0+ (ICS) +NDK=/opt/android/ndk +NDKABI=14 +NDKVER=$NDK/toolchains/x86-4.6 +NDKP=$NDKVER/prebuilt/linux-x86/bin/i686-linux-android- +NDKF="--sysroot $NDK/platforms/android-$NDKABI/arch-x86" +make HOST_CC="gcc -m32" CROSS=$NDKP TARGET_FLAGS="$NDKF" +</pre> +<p> +You can cross-compile for <b id="ios">iOS 3.0+</b> (iPhone/iPad) using the <a href="http://developer.apple.com/devcenter/ios/index.action"><span class="ext">»</span> iOS SDK</a>. +The environment variables need to match the iOS SDK version: +</p> +<p style="font-size: 8pt;"> +Note: <b>the JIT compiler is disabled for iOS</b>, because regular iOS Apps +are not allowed to generate code at runtime. You'll only get the performance +of the LuaJIT interpreter on iOS. This is still faster than plain Lua, but +much slower than the JIT compiler. Please complain to Apple, not me. +Or use Android. :-p +</p> +<pre class="code"> +IXCODE=`xcode-select -print-path` +ISDK=$IXCODE/Platforms/iPhoneOS.platform/Developer +ISDKVER=iPhoneOS6.0.sdk +ISDKP=$ISDK/usr/bin/ +ISDKF="-arch armv7 -isysroot $ISDK/SDKs/$ISDKVER" +make HOST_CC="gcc -m32 -arch i386" CROSS=$ISDKP TARGET_FLAGS="$ISDKF" \ + TARGET_SYS=iOS +</pre> +<p> +You can cross-compile for <b id="ps3">PS3</b> using the PS3 SDK from +a Linux host or a Windows host (requires 32 bit MinGW (GCC) on the host, +too). Due to restrictions on consoles, the JIT compiler is disabled and +only the fast interpreter is built: +</p> +<pre class="code"> +make HOST_CC="gcc -m32" CROSS=ppu-lv2- +</pre> +<p> +You can cross-compile for <b id="ps4">PS4</b> from a Windows host using +the PS4 SDK (ORBIS) plus 64 bit MSVC. Due to restrictions on +consoles, the JIT compiler is disabled and only the fast interpreter +is built. +</p> +<p> +Open a "Visual Studio .NET Command Prompt" (64 bit host compiler), +<tt>cd</tt> to the directory where you've unpacked the sources and run +the following commands. This builds a static library <tt>libluajit.a</tt>, +which can be linked against your game, just like the Lua library. +</p> +<pre class="code"> +cd src +ps4build +</pre> +<p> +You can cross-compile for <b id="xbox360">Xbox 360</b> using the +Xbox 360 SDK (MSVC + XEDK). Due to restrictions on consoles, the +JIT compiler is disabled and only the fast interpreter is built. +</p> +<p> +Open a "Visual Studio .NET Command Prompt" (32 bit host compiler), +<tt>cd</tt> to the directory where you've unpacked the sources and run +the following commands. This builds a static library <tt>luajit20.lib</tt>, +which can be linked against your game, just like the Lua library. +</p> +<pre class="code"> +cd src +xedkbuild +</pre> + +<h2 id="embed">Embedding LuaJIT</h2> +<p> +LuaJIT is API-compatible with Lua 5.1. If you've already embedded Lua +into your application, you probably don't need to do anything to switch +to LuaJIT, except link with a different library: +</p> +<ul> +<li>It's strongly suggested to build LuaJIT separately using the supplied +build system. Please do <em>not</em> attempt to integrate the individual +source files into your build tree. You'll most likely get the internal build +dependencies wrong or mess up the compiler flags. Treat LuaJIT like any +other external library and link your application with either the dynamic +or static library, depending on your needs.</li> +<li>If you want to load C modules compiled for plain Lua +with <tt>require()</tt>, you need to make sure the public symbols +(e.g. <tt>lua_pushnumber</tt>) are exported, too: +<ul><li>On POSIX systems you can either link to the shared library +or link the static library into your application. In the latter case +you'll need to export all public symbols from your main executable +(e.g. <tt>-Wl,-E</tt> on Linux) and add the external dependencies +(e.g. <tt>-lm -ldl</tt> on Linux).</li> +<li>Since Windows symbols are bound to a specific DLL name, you need to +link to the <tt>lua51.dll</tt> created by the LuaJIT build (do not rename +the DLL). You may link LuaJIT statically on Windows only if you don't +intend to load Lua/C modules at runtime. +</li></ul> +</li> +<li> +If you're building a 64 bit application on OSX which links directly or +indirectly against LuaJIT, you need to link your main executable +with these flags: +<pre class="code"> +-pagezero_size 10000 -image_base 100000000 +</pre> +Also, it's recommended to <tt>rebase</tt> all (self-compiled) shared libraries +which are loaded at runtime on OSX/x64 (e.g. C extension modules for Lua). +See: <tt>man rebase</tt> +</li> +</ul> +<p>Additional hints for initializing LuaJIT using the C API functions:</p> +<ul> +<li>Here's a +<a href="http://lua-users.org/wiki/SimpleLuaApiExample"><span class="ext">»</span> simple example</a> +for embedding Lua or LuaJIT into your application.</li> +<li>Make sure you use <tt>luaL_newstate</tt>. Avoid using +<tt>lua_newstate</tt>, since this uses the (slower) default memory +allocator from your system (no support for this on x64).</li> +<li>Make sure you use <tt>luaL_openlibs</tt> and not the old Lua 5.0 style +of calling <tt>luaopen_base</tt> etc. directly.</li> +<li>To change or extend the list of standard libraries to load, copy +<tt>src/lib_init.c</tt> to your project and modify it accordingly. +Make sure the <tt>jit</tt> library is loaded or the JIT compiler +will not be activated.</li> +<li>The <tt>bit.*</tt> module for bitwise operations +is already built-in. There's no need to statically link +<a href="http://bitop.luajit.org/"><span class="ext">»</span> Lua BitOp</a> to your application.</li> +</ul> + +<h2 id="distro">Hints for Distribution Maintainers</h2> +<p> +The LuaJIT build system has extra provisions for the needs of most +POSIX-based distributions. If you're a package maintainer for +a distribution, <em>please</em> make use of these features and +avoid patching, subverting, autotoolizing or messing up the build system +in unspeakable ways. +</p> +<p> +There should be absolutely no need to patch <tt>luaconf.h</tt> or any +of the Makefiles. And please do not hand-pick files for your packages — +simply use whatever <tt>make install</tt> creates. There's a reason +for all of the files <em>and</em> directories it creates. +</p> +<p> +The build system uses GNU make and auto-detects most settings based on +the host you're building it on. This should work fine for native builds, +even when sandboxed. You may need to pass some of the following flags to +<em>both</em> the <tt>make</tt> and the <tt>make install</tt> command lines +for a regular distribution build: +</p> +<ul> +<li><tt>PREFIX</tt> overrides the installation path and should usually +be set to <tt>/usr</tt>. Setting this also changes the module paths and +the paths needed to locate the shared library.</li> +<li><tt>DESTDIR</tt> is an absolute path which allows you to install +to a shadow tree instead of the root tree of the build system.</li> +<li><tt>MULTILIB</tt> sets the architecture-specific library path component +for multilib systems. The default is <tt>lib</tt>.</li> +<li>Have a look at the top-level <tt>Makefile</tt> and <tt>src/Makefile</tt> +for additional variables to tweak. The following variables <em>may</em> be +overridden, but it's <em>not</em> recommended, except for special needs +like cross-builds: +<tt>BUILDMODE, CC, HOST_CC, STATIC_CC, DYNAMIC_CC, CFLAGS, HOST_CFLAGS, +TARGET_CFLAGS, LDFLAGS, HOST_LDFLAGS, TARGET_LDFLAGS, TARGET_SHLDFLAGS, +TARGET_FLAGS, LIBS, HOST_LIBS, TARGET_LIBS, CROSS, HOST_SYS, TARGET_SYS +</tt></li> +</ul> +<p> +The build system has a special target for an amalgamated build, i.e. +<tt>make amalg</tt>. This compiles the LuaJIT core as one huge C file +and allows GCC to generate faster and shorter code. Alas, this requires +lots of memory during the build. This may be a problem for some users, +that's why it's not enabled by default. But it shouldn't be a problem for +most build farms. It's recommended that binary distributions use this +target for their LuaJIT builds. +</p> +<p> +The tl;dr version of the above: +</p> +<pre class="code"> +make amalg PREFIX=/usr && \ +make install PREFIX=/usr DESTDIR=/tmp/buildroot +</pre> +<p> +Finally, if you encounter any difficulties, please +<a href="contact.html">contact me</a> first, instead of releasing a broken +package onto unsuspecting users. Because they'll usually gonna complain +to me (the upstream) and not you (the package maintainer), anyway. +</p> +<br class="flush"> +</div> +<div id="foot"> +<hr class="hide"> +Copyright © 2005-2014 Mike Pall +<span class="noprint"> +· +<a href="contact.html">Contact</a> +</span> +</div> +</body> +</html> diff --git a/Build/source/libs/luajit/LuaJIT-2.0.3/doc/luajit.html b/Build/source/libs/luajit/LuaJIT-2.0.3/doc/luajit.html new file mode 100644 index 00000000000..43af69c9202 --- /dev/null +++ b/Build/source/libs/luajit/LuaJIT-2.0.3/doc/luajit.html @@ -0,0 +1,228 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> +<html> +<head> +<title>LuaJIT</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-2014, 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"> +<meta name="description" content="LuaJIT is a Just-In-Time (JIT) compiler for the Lua language."> +<style type="text/css"> +table.feature { + width: inherit; + line-height: 1.2; + margin: 0; +} +table.feature td { + width: 80px; + height: 40px; + vertical-align: middle; + text-align: center; + font-weight: bold; + border: 4px solid #e6ecff; + border-radius: 12px; +} +table.os td { + background: #7080d0; + background-image: linear-gradient(#4060c0 10%, #b0b0ff 95%); + background-image: -moz-linear-gradient(#4060c0 10%, #b0b0ff 95%); + background-image: -webkit-linear-gradient(#4060c0 10%, #b0b0ff 95%); + background-image: -o-linear-gradient(#4060c0 10%, #b0b0ff 95%); + background-image: -ms-linear-gradient(#4060c0 10%, #b0b0ff 95%); +} +table.os1 td { + color: #ffff80; +} +table.os2 td { + color: #ffa040; +} +table.compiler td { + color: #2080ff; + background: #62bf41; + background-image: linear-gradient(#62bf41 10%, #b0ffb0 95%); + background-image: -moz-linear-gradient(#62bf41 10%, #b0ffb0 95%); + background-image: -webkit-linear-gradient(#62bf41 10%, #b0ffb0 95%); + background-image: -o-linear-gradient(#62bf41 10%, #b0ffb0 95%); + background-image: -ms-linear-gradient(#62bf41 10%, #b0ffb0 95%); +} +table.cpu td { + color: #ffff00; + background: #cf7251; + background-image: linear-gradient(#bf6241 10%, #ffb0b0 95%); + background-image: -moz-linear-gradient(#bf6241 10%, #ffb0b0 95%); + background-image: -webkit-linear-gradient(#bf6241 10%, #ffb0b0 95%); + background-image: -o-linear-gradient(#bf6241 10%, #ffb0b0 95%); + background-image: -ms-linear-gradient(#bf6241 10%, #ffb0b0 95%); +} +table.fcompat td { + color: #2060e0; + background: #61cfcf; + background-image: linear-gradient(#41bfbf 10%, #b0ffff 95%); + background-image: -moz-linear-gradient(#41bfbf 10%, #b0ffff 95%); + background-image: -webkit-linear-gradient(#41bfbf 10%, #b0ffff 95%); + background-image: -o-linear-gradient(#41bfbf 10%, #b0ffff 95%); + background-image: -ms-linear-gradient(#41bfbf 10%, #b0ffff 95%); +} +table.stats td { + color: #ffffff; + background: #a0a0a0; + background-image: linear-gradient(#808080 10%, #d0d0d0 95%); + background-image: -moz-linear-gradient(#808080 10%, #d0d0d0 95%); + background-image: -webkit-linear-gradient(#808080 10%, #d0d0d0 95%); + background-image: -o-linear-gradient(#808080 10%, #d0d0d0 95%); + background-image: -ms-linear-gradient(#808080 10%, #d0d0d0 95%); +} +table.stats td.speed { + color: #ff4020; +} +table.stats td.kb { + color: #ffff80; + background: #808080; + background-image: linear-gradient(#606060 10%, #c0c0c0 95%); + background-image: -moz-linear-gradient(#606060 10%, #c0c0c0 95%); + background-image: -webkit-linear-gradient(#606060 10%, #c0c0c0 95%); + background-image: -o-linear-gradient(#606060 10%, #c0c0c0 95%); + background-image: -ms-linear-gradient(#606060 10%, #c0c0c0 95%); +} +table.feature small { + font-size: 50%; +} +</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>LuaJIT</h1> +</div> +<div id="nav"> +<ul><li> +<a class="current" href="luajit.html">LuaJIT</a> +<ul><li> +<a href="http://luajit.org/download.html">Download <span class="ext">»</span></a> +</li><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_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_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://wiki.luajit.org/">Wiki <span class="ext">»</span></a> +</li><li> +<a href="http://luajit.org/list.html">Mailing List <span class="ext">»</span></a> +</li></ul> +</div> +<div id="main"> +<p> +LuaJIT is a <b>Just-In-Time Compiler</b> (JIT) for the +<a href="http://www.lua.org/"><span class="ext">»</span> Lua</a> programming language. +Lua is a powerful, dynamic and light-weight programming language. +It may be embedded or used as a general-purpose, stand-alone language. +</p> +<p> +LuaJIT is Copyright © 2005-2014 Mike Pall, released under the +<a href="http://www.opensource.org/licenses/mit-license.php"><span class="ext">»</span> MIT open source license</a>. +</p> +<p> +</p> + +<h2>Compatibility</h2> +<table class="feature os os1"> +<tr><td>Windows</td><td>Linux</td><td>BSD</td><td>OSX</td><td>POSIX</td></tr> +</table> +<table class="feature os os2"> +<tr><td><span style="font-size:90%;">Embedded</span></td><td>Android</td><td>iOS</td><td>PS3</td><td>PS4</td><td>Xbox 360</td></tr> +</table> +<table class="feature compiler"> +<tr><td>GCC</td><td>CLANG<br>LLVM</td><td>MSVC</td></tr> +</table> +<table class="feature cpu"> +<tr><td>x86</td><td>x64</td><td>ARM</td><td>PPC</td><td>e500</td><td>MIPS</td></tr> +</table> +<table class="feature fcompat"> +<tr><td>Lua 5.1<br>API+ABI</td><td>+ JIT</td><td>+ BitOp</td><td>+ FFI</td><td>Drop-in<br>DLL/.so</td></tr> +</table> + +<h2>Overview</h2> +<table class="feature stats"> +<tr> +<td class="speed">3x<br>- 100x</td> +<td class="kb">115 <small>KB</small><br>VM</td> +<td class="kb">90 <small>KB</small><br>JIT</td> +<td class="kloc">63 <small>KLOC</small><br>C</td> +<td class="kloc">24 <small>KLOC</small><br>ASM</td> +<td class="kloc">11 <small>KLOC</small><br>Lua</td> +</tr> +</table> +<p style="margin-top: 1em;"> +LuaJIT has been successfully used as a <b>scripting middleware</b> in +games, appliances, network and graphics apps, numerical simulations, +trading platforms and many other specialty applications. It scales from +embedded devices, smartphones, desktops up to server farms. It combines +high flexibility with <a href="http://luajit.org/performance.html"><span class="ext">»</span> high performance</a> +and an unmatched <b>low memory footprint</b>. +</p> +<p> +LuaJIT has been in continuous development since 2005. It's widely +considered to be <b>one of the fastest dynamic language +implementations</b>. It has outperformed other dynamic languages on many +cross-language benchmarks since its first release — often by a +substantial margin. +</p> +<p> +For <b>LuaJIT 2.0</b>, the whole VM has been rewritten from the ground up +and relentlessly optimized for performance. It combines a <b>high-speed +interpreter</b>, written in assembler, with a <b>state-of-the-art JIT +compiler</b>. +</p> +<p> +An innovative <b>trace compiler</b> is integrated with advanced, +SSA-based optimizations and highly tuned code generation backends. +A substantial reduction of the overhead associated with dynamic languages +allows it to break into the performance range traditionally reserved for +offline, static language compilers. +</p> + +<h2>More ...</h2> +<p> +Please select a sub-topic in the navigation bar to learn more about LuaJIT. +</p> +<br class="flush"> +</div> +<div id="foot"> +<hr class="hide"> +Copyright © 2005-2014 Mike Pall +<span class="noprint"> +· +<a href="contact.html">Contact</a> +</span> +</div> +</body> +</html> diff --git a/Build/source/libs/luajit/LuaJIT-2.0.3/doc/running.html b/Build/source/libs/luajit/LuaJIT-2.0.3/doc/running.html new file mode 100644 index 00000000000..c01c52d5ad0 --- /dev/null +++ b/Build/source/libs/luajit/LuaJIT-2.0.3/doc/running.html @@ -0,0 +1,306 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> +<html> +<head> +<title>Running LuaJIT</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-2014, 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.opt { + line-height: 1.2; +} +tr.opthead td { + font-weight: bold; +} +td.flag_name { + width: 4em; +} +td.flag_level { + width: 2em; + text-align: center; +} +td.param_name { + width: 6em; +} +td.param_default { + width: 4em; + text-align: right; +} +</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>Running LuaJIT</h1> +</div> +<div id="nav"> +<ul><li> +<a href="luajit.html">LuaJIT</a> +<ul><li> +<a href="http://luajit.org/download.html">Download <span class="ext">»</span></a> +</li><li> +<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_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_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://wiki.luajit.org/">Wiki <span class="ext">»</span></a> +</li><li> +<a href="http://luajit.org/list.html">Mailing List <span class="ext">»</span></a> +</li></ul> +</div> +<div id="main"> +<p> +LuaJIT has only a single stand-alone executable, called <tt>luajit</tt> on +POSIX systems or <tt>luajit.exe</tt> on Windows. It can be used to run simple +Lua statements or whole Lua applications from the command line. It has an +interactive mode, too. +</p> + +<h2 id="options">Command Line Options</h2> +<p> +The <tt>luajit</tt> stand-alone executable is just a slightly modified +version of the regular <tt>lua</tt> stand-alone executable. +It supports the same basic options, too. <tt>luajit -h</tt> +prints a short list of the available options. Please have a look at the +<a href="http://www.lua.org/manual/5.1/manual.html#6"><span class="ext">»</span> Lua manual</a> +for details. +</p> +<p> +LuaJIT has some additional options: +</p> + +<h3 id="opt_b"><tt>-b[options] input output</tt></h3> +<p> +This option saves or lists bytecode. The following additional options +are accepted: +</p> +<ul> +<li><tt>-l</tt> — Only list bytecode.</li> +<li><tt>-s</tt> — Strip debug info (this is the default).</li> +<li><tt>-g</tt> — Keep debug info.</li> +<li><tt>-n name</tt> — Set module name (default: auto-detect from input name)</li> +<li><tt>-t type</tt> — Set output file type (default: auto-detect from output name).</li> +<li><tt>-a arch</tt> — Override architecture for object files (default: native).</li> +<li><tt>-o os</tt> — Override OS for object files (default: native).</li> +<li><tt>-e chunk</tt> — Use chunk string as input.</li> +<li><tt>-</tt> (a single minus sign) — Use stdin as input and/or stdout as output.</li> +</ul> +<p> +The output file type is auto-detected from the extension of the output +file name: +</p> +<ul> +<li><tt>c</tt> — C source file, exported bytecode data.</li> +<li><tt>h</tt> — C header file, static bytecode data.</li> +<li><tt>obj</tt> or <tt>o</tt> — Object file, exported bytecode data +(OS- and architecture-specific).</li> +<li><tt>raw</tt> or any other extension — Raw bytecode file (portable). +</ul> +<p> +Notes: +</p> +<ul> +<li>See also <a href="extensions.html#string_dump">string.dump()</a> +for information on bytecode portability and compatibility.</li> +<li>A file in raw bytecode format is auto-detected and can be loaded like +any Lua source file. E.g. directly from the command line or with +<tt>loadfile()</tt>, <tt>dofile()</tt> etc.</li> +<li>To statically embed the bytecode of a module in your application, +generate an object file and just link it with your application.</li> +<li>On most ELF-based systems (e.g. Linux) you need to explicitly export the +global symbols when linking your application, e.g. with: <tt>-Wl,-E</tt></li> +<li><tt>require()</tt> tries to load embedded bytecode data from exported +symbols (in <tt>*.exe</tt> or <tt>lua51.dll</tt> on Windows) and from +shared libraries in <tt>package.cpath</tt>.</li> +</ul> +<p> +Typical usage examples: +</p> +<pre class="code"> +luajit -b test.lua test.out # Save bytecode to test.out +luajit -bg test.lua test.out # Keep debug info +luajit -be "print('hello world')" test.out # Save cmdline script + +luajit -bl test.lua # List to stdout +luajit -bl test.lua test.txt # List to test.txt +luajit -ble "print('hello world')" # List cmdline script + +luajit -b test.lua test.obj # Generate object file +# Link test.obj with your application and load it with require("test") +</pre> + +<h3 id="opt_j"><tt>-j cmd[=arg[,arg...]]</tt></h3> +<p> +This option performs a LuaJIT control command or activates one of the +loadable extension modules. The command is first looked up in the +<tt>jit.*</tt> library. If no matching function is found, a module +named <tt>jit.<cmd></tt> is loaded and the <tt>start()</tt> +function of the module is called with the specified arguments (if +any). The space between <tt>-j</tt> and <tt>cmd</tt> is optional. +</p> +<p> +Here are the available LuaJIT control commands: +</p> +<ul> +<li id="j_on"><tt>-jon</tt> — Turns the JIT compiler on (default).</li> +<li id="j_off"><tt>-joff</tt> — Turns the JIT compiler off (only use the interpreter).</li> +<li id="j_flush"><tt>-jflush</tt> — Flushes the whole cache of compiled code.</li> +<li id="j_v"><tt>-jv</tt> — Shows verbose information about the progress of the JIT compiler.</li> +<li id="j_dump"><tt>-jdump</tt> — Dumps the code and structures used in various compiler stages.</li> +</ul> +<p> +The <tt>-jv</tt> and <tt>-jdump</tt> commands are extension modules +written in Lua. They are mainly used for debugging the JIT compiler +itself. For a description of their options and output format, please +read the comment block at the start of their source. +They can be found in the <tt>lib</tt> directory of the source +distribution or installed under the <tt>jit</tt> directory. By default +this is <tt>/usr/local/share/luajit-2.0.3/jit</tt> on POSIX +systems. +</p> + +<h3 id="opt_O"><tt>-O[level]</tt><br> +<tt>-O[+]flag</tt> <tt>-O-flag</tt><br> +<tt>-Oparam=value</tt></h3> +<p> +This options allows fine-tuned control of the optimizations used by +the JIT compiler. This is mainly intended for debugging LuaJIT itself. +Please note that the JIT compiler is extremely fast (we are talking +about the microsecond to millisecond range). Disabling optimizations +doesn't have any visible impact on its overhead, but usually generates +code that runs slower. +</p> +<p> +The first form sets an optimization level — this enables a +specific mix of optimization flags. <tt>-O0</tt> turns off all +optimizations and higher numbers enable more optimizations. Omitting +the level (i.e. just <tt>-O</tt>) sets the default optimization level, +which is <tt>-O3</tt> in the current version. +</p> +<p> +The second form adds or removes individual optimization flags. +The third form sets a parameter for the VM or the JIT compiler +to a specific value. +</p> +<p> +You can either use this option multiple times (like <tt>-Ocse +-O-dce -Ohotloop=10</tt>) or separate several settings with a comma +(like <tt>-O+cse,-dce,hotloop=10</tt>). The settings are applied from +left to right and later settings override earlier ones. You can freely +mix the three forms, but note that setting an optimization level +overrides all earlier flags. +</p> +<p> +Here are the available flags and at what optimization levels they +are enabled: +</p> +<table class="opt"> +<tr class="opthead"> +<td class="flag_name">Flag</td> +<td class="flag_level">-O1</td> +<td class="flag_level">-O2</td> +<td class="flag_level">-O3</td> +<td class="flag_desc"> </td> +</tr> +<tr class="odd separate"> +<td class="flag_name">fold</td><td class="flag_level">•</td><td class="flag_level">•</td><td class="flag_level">•</td><td class="flag_desc">Constant Folding, Simplifications and Reassociation</td></tr> +<tr class="even"> +<td class="flag_name">cse</td><td class="flag_level">•</td><td class="flag_level">•</td><td class="flag_level">•</td><td class="flag_desc">Common-Subexpression Elimination</td></tr> +<tr class="odd"> +<td class="flag_name">dce</td><td class="flag_level">•</td><td class="flag_level">•</td><td class="flag_level">•</td><td class="flag_desc">Dead-Code Elimination</td></tr> +<tr class="even"> +<td class="flag_name">narrow</td><td class="flag_level"> </td><td class="flag_level">•</td><td class="flag_level">•</td><td class="flag_desc">Narrowing of numbers to integers</td></tr> +<tr class="odd"> +<td class="flag_name">loop</td><td class="flag_level"> </td><td class="flag_level">•</td><td class="flag_level">•</td><td class="flag_desc">Loop Optimizations (code hoisting)</td></tr> +<tr class="even"> +<td class="flag_name">fwd</td><td class="flag_level"> </td><td class="flag_level"> </td><td class="flag_level">•</td><td class="flag_desc">Load Forwarding (L2L) and Store Forwarding (S2L)</td></tr> +<tr class="odd"> +<td class="flag_name">dse</td><td class="flag_level"> </td><td class="flag_level"> </td><td class="flag_level">•</td><td class="flag_desc">Dead-Store Elimination</td></tr> +<tr class="even"> +<td class="flag_name">abc</td><td class="flag_level"> </td><td class="flag_level"> </td><td class="flag_level">•</td><td class="flag_desc">Array Bounds Check Elimination</td></tr> +<tr class="odd"> +<td class="flag_name">sink</td><td class="flag_level"> </td><td class="flag_level"> </td><td class="flag_level">•</td><td class="flag_desc">Allocation/Store Sinking</td></tr> +<tr class="even"> +<td class="flag_name">fuse</td><td class="flag_level"> </td><td class="flag_level"> </td><td class="flag_level">•</td><td class="flag_desc">Fusion of operands into instructions</td></tr> +</table> +<p> +Here are the parameters and their default settings: +</p> +<table class="opt"> +<tr class="opthead"> +<td class="param_name">Parameter</td> +<td class="param_default">Default</td> +<td class="param_desc"> </td> +</tr> +<tr class="odd separate"> +<td class="param_name">maxtrace</td><td class="param_default">1000</td><td class="param_desc">Max. number of traces in the cache</td></tr> +<tr class="even"> +<td class="param_name">maxrecord</td><td class="param_default">4000</td><td class="param_desc">Max. number of recorded IR instructions</td></tr> +<tr class="odd"> +<td class="param_name">maxirconst</td><td class="param_default">500</td><td class="param_desc">Max. number of IR constants of a trace</td></tr> +<tr class="even"> +<td class="param_name">maxside</td><td class="param_default">100</td><td class="param_desc">Max. number of side traces of a root trace</td></tr> +<tr class="odd"> +<td class="param_name">maxsnap</td><td class="param_default">500</td><td class="param_desc">Max. number of snapshots for a trace</td></tr> +<tr class="even separate"> +<td class="param_name">hotloop</td><td class="param_default">56</td><td class="param_desc">Number of iterations to detect a hot loop or hot call</td></tr> +<tr class="odd"> +<td class="param_name">hotexit</td><td class="param_default">10</td><td class="param_desc">Number of taken exits to start a side trace</td></tr> +<tr class="even"> +<td class="param_name">tryside</td><td class="param_default">4</td><td class="param_desc">Number of attempts to compile a side trace</td></tr> +<tr class="odd separate"> +<td class="param_name">instunroll</td><td class="param_default">4</td><td class="param_desc">Max. unroll factor for instable loops</td></tr> +<tr class="even"> +<td class="param_name">loopunroll</td><td class="param_default">15</td><td class="param_desc">Max. unroll factor for loop ops in side traces</td></tr> +<tr class="odd"> +<td class="param_name">callunroll</td><td class="param_default">3</td><td class="param_desc">Max. unroll factor for pseudo-recursive calls</td></tr> +<tr class="even"> +<td class="param_name">recunroll</td><td class="param_default">2</td><td class="param_desc">Min. unroll factor for true recursion</td></tr> +<tr class="odd separate"> +<td class="param_name">sizemcode</td><td class="param_default">32</td><td class="param_desc">Size of each machine code area in KBytes (Windows: 64K)</td></tr> +<tr class="even"> +<td class="param_name">maxmcode</td><td class="param_default">512</td><td class="param_desc">Max. total size of all machine code areas in KBytes</td></tr> +</table> +<br class="flush"> +</div> +<div id="foot"> +<hr class="hide"> +Copyright © 2005-2014 Mike Pall +<span class="noprint"> +· +<a href="contact.html">Contact</a> +</span> +</div> +</body> +</html> diff --git a/Build/source/libs/luajit/LuaJIT-2.0.3/doc/status.html b/Build/source/libs/luajit/LuaJIT-2.0.3/doc/status.html new file mode 100644 index 00000000000..ddcaed33261 --- /dev/null +++ b/Build/source/libs/luajit/LuaJIT-2.0.3/doc/status.html @@ -0,0 +1,125 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> +<html> +<head> +<title>Status & Roadmap</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-2014, 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"> +ul li { padding-bottom: 0.3em; } +</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>Status & Roadmap</h1> +</div> +<div id="nav"> +<ul><li> +<a href="luajit.html">LuaJIT</a> +<ul><li> +<a href="http://luajit.org/download.html">Download <span class="ext">»</span></a> +</li><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_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_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 class="current" 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://wiki.luajit.org/">Wiki <span class="ext">»</span></a> +</li><li> +<a href="http://luajit.org/list.html">Mailing List <span class="ext">»</span></a> +</li></ul> +</div> +<div id="main"> +<p> +<span style="color: #0000c0;">LuaJIT 2.0</span> is the current +<span style="color: #0000c0;">stable branch</span>. This branch is in +feature-freeze — new features will only be added to LuaJIT 2.1. +</p> + +<h2>Current Status</h2> +<p> +LuaJIT ought to run all Lua 5.1-compatible source code just fine. +It's considered a serious bug if the VM crashes or produces unexpected +results — please report this. +</p> +<p> +Known incompatibilities and issues in LuaJIT 2.0: +</p> +<ul> +<li> +There are some differences in <b>implementation-defined</b> behavior. +These either have a good reason, are arbitrary design choices +or are due to quirks in the VM. The latter cases may get fixed if a +demonstrable need is shown. +</li> +<li> +The Lua <b>debug API</b> is missing a couple of features (return +hooks for non-Lua functions) and shows slightly different behavior +in LuaJIT (no per-coroutine hooks, no tail call counting). +</li> +<li> +Some checks are missing in the JIT-compiled code for obscure situations +with <b>open upvalues aliasing</b> one of the SSA slots later on (or +vice versa). Bonus points, if you can find a real world test case for +this. +</li> +<li> +Currently some <b>out-of-memory</b> errors from <b>on-trace code</b> are not +handled correctly. The error may fall through an on-trace +<tt>pcall</tt> or it may be passed on to the function set with +<tt>lua_atpanic</tt> on x64. This issue will be fixed with the new +garbage collector. +</li> +</ul> + +<h2>Roadmap</h2> +<p> +Please refer to the +<a href="http://www.freelists.org/post/luajit/LuaJIT-Roadmap-20122013"><span class="ext">»</span> LuaJIT Roadmap 2012/2013</a> and an +<a href="http://www.freelists.org/post/luajit/LuaJIT-Roadmap-20122013-UPDATE"><span class="ext">»</span> update on release planning</a> for details. +</p> +<p> +</p> +<br class="flush"> +</div> +<div id="foot"> +<hr class="hide"> +Copyright © 2005-2014 Mike Pall +<span class="noprint"> +· +<a href="contact.html">Contact</a> +</span> +</div> +</body> +</html> |