diff options
Diffstat (limited to 'Build/source/libs/luajit/LuaJIT-src/doc')
18 files changed, 0 insertions, 7035 deletions
diff --git a/Build/source/libs/luajit/LuaJIT-src/doc/bluequad-print.css b/Build/source/libs/luajit/LuaJIT-src/doc/bluequad-print.css deleted file mode 100644 index 62e1c165909..00000000000 --- a/Build/source/libs/luajit/LuaJIT-src/doc/bluequad-print.css +++ /dev/null @@ -1,166 +0,0 @@ -/* Copyright (C) 2004-2017 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-src/doc/bluequad.css b/Build/source/libs/luajit/LuaJIT-src/doc/bluequad.css deleted file mode 100644 index be2c4bf2d51..00000000000 --- a/Build/source/libs/luajit/LuaJIT-src/doc/bluequad.css +++ /dev/null @@ -1,325 +0,0 @@ -/* Copyright (C) 2004-2017 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-src/doc/changes.html b/Build/source/libs/luajit/LuaJIT-src/doc/changes.html deleted file mode 100644 index a66a8d95049..00000000000 --- a/Build/source/libs/luajit/LuaJIT-src/doc/changes.html +++ /dev/null @@ -1,883 +0,0 @@ -<!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-2017, 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><li> -<a href="ext_profiler.html">Profiler</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.5</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.1.0-beta3">LuaJIT 2.1.0-beta3 — 2017-05-01</h2> -<ul> -<li>Rewrite memory block allocator.</li> -<li>Add various extension from Lua 5.2/5.3.</li> -<li>Remove old Lua 5.0 compatibility defines.</li> -<li>Set arg table before evaluating <tt>LUA_INIT</tt> and <tt>-e</tt> chunks.</li> -<li>Fix FOLD rules for <tt>math.abs()</tt> and FP negation.</li> -<li>Fix soft-float <tt>math.abs()</tt> and negation.</li> -<li>Fix formatting of some small denormals at low precision.</li> -<li>LJ_GC64: Add JIT compiler support.</li> -<li>x64/LJ_GC64: Add JIT compiler backend.</li> -<li>x86/x64: Generate BMI2 shifts and rotates, if available.</li> -<li>Windows/x86: Add full exception interoperability.</li> -<li>ARM64: Add big-endian support.</li> -<li>ARM64: Add JIT compiler backend.</li> -<li>MIPS: Fix <tt>TSETR</tt> barrier.</li> -<li>MIPS: Support MIPS16 interlinking.</li> -<li>MIPS soft-float: Fix code generation for <tt>HREF</tt>.</li> -<li>MIPS64: Add MIPS64 hard-float JIT compiler backend.</li> -<li>MIPS64: Add MIPS64 hard-float/soft-float support to interpreter.</li> -<li>FFI: Compile bitfield loads/stores.</li> -<li>Various fixes common with the 2.0 branch.</li> -</ul> - -<h2 id="LuaJIT-2.1.0-beta2">LuaJIT 2.1.0-beta2 — 2016-03-03</h2> -<ul> -<li>Enable trace stitching.</li> -<li>Use internal implementation for converting FP numbers to strings.</li> -<li>Parse Unicode escape <tt>'\u{XX...}'</tt> in string literals.</li> -<li>Add MIPS soft-float support.</li> -<li>Switch MIPS port to dual-number mode.</li> -<li>x86/x64: Add support for AES-NI, AVX and AVX2 to DynASM.</li> -<li>FFI: Add <tt>ssize_t</tt> declaration.</li> -<li>FFI: Parse <tt>#line NN</tt> and <tt>#NN</tt>.</li> -<li>Various minor fixes.</li> -</ul> - -<h2 id="LuaJIT-2.1.0-beta1">LuaJIT 2.1.0-beta1 — 2015-08-25</h2> -<p> -This is a brief summary of the major changes in LuaJIT 2.1 compared to 2.0. -Please take a look at the commit history for more details. -</p> -<ul> -<li>Changes to the VM core: -<ul> -<li>Add low-overhead profiler (<tt>-jp</tt>).</li> -<li>Add <tt>LJ_GC64</tt> mode: 64 bit GC object references (really: 47 bit). Interpreter-only for now.</li> -<li>Add <tt>LJ_FR2</tt> mode: Two-slot frame info. Required by <tt>LJ_GC64</tt> mode.</li> -<li>Add <tt>table.new()</tt> and <tt>table.clear()</tt>.</li> -<li>Parse binary number literals (<tt>0bxxx</tt>).</li> -</ul></li> -<li>Improvements to the JIT compiler: -<ul> -<li>Add trace stitching (disabled for now).</li> -<li>Compile various builtins: <tt>string.char()</tt>, <tt>string.reverse()</tt>, <tt>string.lower()</tt>, <tt>string.upper()</tt>, <tt>string.rep()</tt>, <tt>string.format()</tt>, <tt>table.concat()</tt>, <tt>bit.tohex()</tt>, <tt>getfenv(0)</tt>, <tt>debug.getmetatable()</tt>.</li> -<li>Compile <tt>string.find()</tt> for fixed string searches (no patterns).</li> -<li>Compile <tt>BC_TSETM</tt>, e.g. <tt>{1,2,3,f()}</tt>.</li> -<li>Compile string concatenations (<tt>BC_CAT</tt>).</li> -<li>Compile <tt>__concat</tt> metamethod.</li> -<li>Various minor optimizations.</li> -</ul></li> -<li>Internal Changes: -<ul> -<li>Add support for embedding LuaJIT bytecode for builtins.</li> -<li>Replace various builtins with embedded bytecode.</li> -<li>Refactor string buffers and string formatting.</li> -<li>Remove obsolete non-truncating number to integer conversions.</li> -</ul></li> -<li>Ports: -<ul> -<li>Add Xbox One port (<tt>LJ_GC64</tt> mode).</li> -<li>ARM64: Add port of the interpreter (<tt>LJ_GC64</tt> mode).</li> -<li>x64: Add separate port of the interpreter to <tt>LJ_GC64</tt> mode.</li> -<li>x86/x64: Drop internal x87 math functions. Use libm functions.</li> -<li>x86: Remove x87 support from interpreter. SSE2 is mandatory now.</li> -<li>PPC/e500: Drop support for this architecture.</li> -</ul></li> -<li>FFI library: -<ul> -<li>FFI: Add 64 bit bitwise operations.</li> -<li>FFI: Compile VLA/VLS and large cdata allocations with default initialization.</li> -<li>FFI: Compile conversions from functions to function pointers.</li> -<li>FFI: Compile lightuserdata to <tt>void *</tt> conversion.</li> -<li>FFI: Compile <tt>ffi.gc(cdata, nil)</tt>, too.</li> -<li>FFI: Add <tt>ffi.typeinfo()</tt>.</li> -</ul></li> -</ul> -</div> - -<div class="major" style="background: #ffffd0;"> -<h2 id="LuaJIT-2.0.5">LuaJIT 2.0.5 — 2017-05-01</h2> -<ul> -<li>Add workaround for MSVC 2015 stdio changes.</li> -<li>Limit mcode alloc probing, depending on the available pool size.</li> -<li>Fix overly restrictive range calculation in mcode allocation.</li> -<li>Fix out-of-scope goto handling in parser.</li> -<li>Remove internal <tt>__mode = "K"</tt> and replace with safe check.</li> -<li>Add "proto" field to <tt>jit.util.funcinfo()</tt>.</li> -<li>Fix GC step size calculation.</li> -<li>Initialize <tt>uv->immutable</tt> for upvalues of loaded chunks.</li> -<li>Fix for cdata vs. non-cdata arithmetics/comparisons.</li> -<li>Drop leftover regs in 'for' iterator assignment, too.</li> -<li>Fix PHI remarking in SINK pass.</li> -<li>Don't try to record outermost <tt>pcall()</tt> return to lower frame.</li> -<li>Add guard for obscure aliasing between open upvalues and SSA slots.</li> -<li>Remove assumption that <tt>lj_math_random_step()</tt> doesn't clobber FPRs.</li> -<li>Fix handling of non-numeric strings in arithmetic coercions.</li> -<li>Fix recording of <tt>select(n, ...)</tt> with off-trace varargs</li> -<li>Fix install for cross-builds.</li> -<li>Don't allocate unused 2nd result register in JIT compiler backend.</li> -<li>Drop marks from replayed instructions when sinking.</li> -<li>Fix unsinking check.</li> -<li>Properly handle OOM in <tt>trace_save()</tt>.</li> -<li>Limit number of arguments given to <tt>io.lines()</tt> and <tt>fp:lines()</tt>.</li> -<li>Fix narrowing of <tt>TOBIT</tt>.</li> -<li>OSX: Fix build with recent XCode.</li> -<li>x86/x64: Don't spill an explicit <tt>REF_BASE</tt> in the IR.</li> -<li>x86/x64: Fix instruction length decoder.</li> -<li>x86/x64: Search for exit jumps with instruction length decoder.</li> -<li>ARM: Fix <tt>BLX</tt> encoding for Thumb interworking calls.</li> -<li>MIPS: Don't use <tt>RID_GP</tt> as a scratch register.</li> -<li>MIPS: Fix emitted code for U32 to float conversion.</li> -<li>MIPS: Backport workaround for compact unwind tables.</li> -<li>MIPS: Fix cross-endian jit.bcsave.</li> -<li>MIPS: Fix <tt>BC_ISNEXT</tt> fallback path.</li> -<li>MIPS: Fix use of ffgccheck delay slots in interpreter.</li> -<li>FFI: Fix FOLD rules for <tt>int64_t</tt> comparisons.</li> -<li>FFI: Fix SPLIT pass for <tt>CONV i64.u64</tt>.</li> -<li>FFI: Fix <tt>ipairs()</tt> recording.</li> -<li>FFI: Don't propagate qualifiers into subtypes of complex.</li> -</ul> - -<h2 id="LuaJIT-2.0.4">LuaJIT 2.0.4 — 2015-05-14</h2> -<ul> -<li>Fix stack check in narrowing optimization.</li> -<li>Fix Lua/C API typecheck error for special indexes.</li> -<li>Fix string to number conversion.</li> -<li>Fix lexer error for chunks without tokens.</li> -<li>Don't compile <tt>IR_RETF</tt> after <tt>CALLT</tt> to ff with-side effects.</li> -<li>Fix <tt>BC_UCLO</tt>/<tt>BC_JMP</tt> join optimization in Lua parser.</li> -<li>Fix corner case in string to number conversion.</li> -<li>Gracefully handle <tt>lua_error()</tt> for a suspended coroutine.</li> -<li>Avoid error messages when building with Clang.</li> -<li>Fix snapshot #0 handling for traces with a stack check on entry.</li> -<li>Fix fused constant loads under high register pressure.</li> -<li>Invalidate backpropagation cache after DCE.</li> -<li>Fix ABC elimination.</li> -<li>Fix debug info for main chunk of stripped bytecode.</li> -<li>Fix FOLD rule for <tt>string.sub(s, ...) == k</tt>.</li> -<li>Fix FOLD rule for <tt>STRREF</tt> of <tt>SNEW</tt>.</li> -<li>Fix frame traversal while searching for error function.</li> -<li>Prevent GC estimate miscalculation due to buffer growth.</li> -<li>Prevent adding side traces for stack checks.</li> -<li>Fix top slot calculation for snapshots with continuations.</li> -<li>Fix check for reuse of SCEV results in <tt>FORL</tt>.</li> -<li>Add PS Vita port.</li> -<li>Fix compatibility issues with Illumos.</li> -<li>Fix DragonFly build (unsupported).</li> -<li>OpenBSD/x86: Better executable memory allocation for W^X mode.</li> -<li>x86: Fix argument checks for <tt>ipairs()</tt> iterator.</li> -<li>x86: <tt>lj_math_random_step()</tt> clobbers XMM regs on OSX Clang.</li> -<li>x86: Fix code generation for unused result of <tt>math.random()</tt>.</li> -<li>x64: Allow building with <tt>LUAJIT_USE_SYSMALLOC</tt> and <tt>LUAJIT_USE_VALGRIND</tt>.</li> -<li>x86/x64: Fix argument check for bit shifts.</li> -<li>x86/x64: Fix code generation for fused test/arith ops.</li> -<li>ARM: Fix write barrier check in <tt>BC_USETS</tt>.</li> -<li>PPC: Fix red zone overflow in machine code generation.</li> -<li>PPC: Don't use <tt>mcrxr</tt> on PPE.</li> -<li>Various archs: Fix excess stack growth in interpreter.</li> -<li>FFI: Fix FOLD rule for <tt>TOBIT</tt> + <tt>CONV num.u32</tt>.</li> -<li>FFI: Prevent DSE across <tt>ffi.string()</tt>.</li> -<li>FFI: No meta fallback when indexing pointer to incomplete struct.</li> -<li>FFI: Fix initialization of unions of subtypes.</li> -<li>FFI: Fix cdata vs. non-cdata arithmetic and comparisons.</li> -<li>FFI: Fix <tt>__index</tt>/<tt>__newindex</tt> metamethod resolution for ctypes.</li> -<li>FFI: Fix compilation of reference field access.</li> -<li>FFI: Fix frame traversal for backtraces with FFI callbacks.</li> -<li>FFI: Fix recording of indexing a struct pointer ctype object itself.</li> -<li>FFI: Allow non-scalar cdata to be compared for equality by address.</li> -<li>FFI: Fix pseudo type conversions for type punning.</li> -</ul> - -<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> -<br class="flush"> -</div> -<div id="foot"> -<hr class="hide"> -Copyright © 2005-2017 Mike Pall -<span class="noprint"> -· -<a href="contact.html">Contact</a> -</span> -</div> -</body> -</html> diff --git a/Build/source/libs/luajit/LuaJIT-src/doc/contact.html b/Build/source/libs/luajit/LuaJIT-src/doc/contact.html deleted file mode 100644 index fe4751c0ead..00000000000 --- a/Build/source/libs/luajit/LuaJIT-src/doc/contact.html +++ /dev/null @@ -1,111 +0,0 @@ -<!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-2017, 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><li> -<a href="ext_profiler.html">Profiler</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> -If you want to report bugs, propose fixes or suggest enhancements, -please use the -<a href="https://github.com/LuaJIT/LuaJIT/issues">GitHub issue tracker</a>. -</p> -<p> -Please send general questions to the -<a href="http://luajit.org/list.html"><span class="ext">»</span> LuaJIT mailing list</a>. -</p> -<p> -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-2017 Mike Pall. -</p> - - -<br class="flush"> -</div> -<div id="foot"> -<hr class="hide"> -Copyright © 2005-2017 Mike Pall -<span class="noprint"> -· -<a href="contact.html">Contact</a> -</span> -</div> -</body> -</html> diff --git a/Build/source/libs/luajit/LuaJIT-src/doc/ext_c_api.html b/Build/source/libs/luajit/LuaJIT-src/doc/ext_c_api.html deleted file mode 100644 index ad462c63e51..00000000000 --- a/Build/source/libs/luajit/LuaJIT-src/doc/ext_c_api.html +++ /dev/null @@ -1,189 +0,0 @@ -<!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-2017, 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><li> -<a href="ext_profiler.html">Profiler</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-2017 Mike Pall -<span class="noprint"> -· -<a href="contact.html">Contact</a> -</span> -</div> -</body> -</html> diff --git a/Build/source/libs/luajit/LuaJIT-src/doc/ext_ffi.html b/Build/source/libs/luajit/LuaJIT-src/doc/ext_ffi.html deleted file mode 100644 index 5e1daaf54b7..00000000000 --- a/Build/source/libs/luajit/LuaJIT-src/doc/ext_ffi.html +++ /dev/null @@ -1,332 +0,0 @@ -<!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-2017, 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><li> -<a href="ext_profiler.html">Profiler</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-2017 Mike Pall -<span class="noprint"> -· -<a href="contact.html">Contact</a> -</span> -</div> -</body> -</html> diff --git a/Build/source/libs/luajit/LuaJIT-src/doc/ext_ffi_api.html b/Build/source/libs/luajit/LuaJIT-src/doc/ext_ffi_api.html deleted file mode 100644 index 91af2e1d43d..00000000000 --- a/Build/source/libs/luajit/LuaJIT-src/doc/ext_ffi_api.html +++ /dev/null @@ -1,570 +0,0 @@ -<!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-2017, 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><li> -<a href="ext_profiler.html">Profiler</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> -<tr class="even"> -<td class="abiparam">gc64</td><td class="abidesc">64 bit GC references</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 decimal (<tt>42LL</tt>), hexadecimal -(<tt>0x2aLL</tt>) and binary (<tt>0b101010LL</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-2017 Mike Pall -<span class="noprint"> -· -<a href="contact.html">Contact</a> -</span> -</div> -</body> -</html> diff --git a/Build/source/libs/luajit/LuaJIT-src/doc/ext_ffi_semantics.html b/Build/source/libs/luajit/LuaJIT-src/doc/ext_ffi_semantics.html deleted file mode 100644 index 800b6b18a0e..00000000000 --- a/Build/source/libs/luajit/LuaJIT-src/doc/ext_ffi_semantics.html +++ /dev/null @@ -1,1262 +0,0 @@ -<!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-2017, 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><li> -<a href="ext_profiler.html">Profiler</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> - -<li>From <tt><unistd.h></tt> (POSIX): <tt>ssize_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> - -<li><b>64 bit bitwise operations</b>: the rules for 64 bit -arithmetic operators apply analogously.<br> - -Unlike the other <tt>bit.*</tt> operations, <tt>bit.tobit()</tt> -converts a cdata number via <tt>int64_t</tt> to <tt>int32_t</tt> and -returns a Lua number.<br> - -For <tt>bit.band()</tt>, <tt>bit.bor()</tt> and <tt>bit.bxor()</tt>, the -conversion to <tt>int64_t</tt> or <tt>uint64_t</tt> applies to -<em>all</em> arguments, if <em>any</em> argument is a cdata number.<br> - -For all other operations, only the first argument is used to determine -the output type. This implies that a cdata number as a shift count for -shifts and rotates is accepted, but that alone does <em>not</em> cause -a cdata number output. - -</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>Vector operations.</li> -<li>Table initializers.</li> -<li>Initialization of nested <tt>struct</tt>/<tt>union</tt> types.</li> -<li>Non-default initialization of VLA/VLS or large C types -(> 128 bytes or > 16 array elements.</li> -<li>Bitfield initializations.</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>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-2017 Mike Pall -<span class="noprint"> -· -<a href="contact.html">Contact</a> -</span> -</div> -</body> -</html> diff --git a/Build/source/libs/luajit/LuaJIT-src/doc/ext_ffi_tutorial.html b/Build/source/libs/luajit/LuaJIT-src/doc/ext_ffi_tutorial.html deleted file mode 100644 index 3650066440a..00000000000 --- a/Build/source/libs/luajit/LuaJIT-src/doc/ext_ffi_tutorial.html +++ /dev/null @@ -1,603 +0,0 @@ -<!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-2017, 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><li> -<a href="ext_profiler.html">Profiler</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.funca, 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-2017 Mike Pall -<span class="noprint"> -· -<a href="contact.html">Contact</a> -</span> -</div> -</body> -</html> diff --git a/Build/source/libs/luajit/LuaJIT-src/doc/ext_jit.html b/Build/source/libs/luajit/LuaJIT-src/doc/ext_jit.html deleted file mode 100644 index e4088bcbd20..00000000000 --- a/Build/source/libs/luajit/LuaJIT-src/doc/ext_jit.html +++ /dev/null @@ -1,201 +0,0 @@ -<!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-2017, 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><li> -<a href="ext_profiler.html">Profiler</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", "arm", "arm64", "ppc", "mips" or "mips64". -</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-2017 Mike Pall -<span class="noprint"> -· -<a href="contact.html">Contact</a> -</span> -</div> -</body> -</html> diff --git a/Build/source/libs/luajit/LuaJIT-src/doc/ext_profiler.html b/Build/source/libs/luajit/LuaJIT-src/doc/ext_profiler.html deleted file mode 100644 index 71b8c03339e..00000000000 --- a/Build/source/libs/luajit/LuaJIT-src/doc/ext_profiler.html +++ /dev/null @@ -1,365 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> -<html> -<head> -<title>Profiler</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-2017, 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>Profiler</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><li> -<a class="current" href="ext_profiler.html">Profiler</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 an integrated statistical profiler with very low overhead. It -allows sampling the currently executing stack and other parameters in -regular intervals. -</p> -<p> -The integrated profiler can be accessed from three levels: -</p> -<ul> -<li>The <a href="#hl_profiler">bundled high-level profiler</a>, invoked by the -<a href="#j_p"><tt>-jp</tt></a> command line option.</li> -<li>A <a href="#ll_lua_api">low-level Lua API</a> to control the profiler.</li> -<li>A <a href="#ll_c_api">low-level C API</a> to control the profiler.</li> -</ul> - -<h2 id="hl_profiler">High-Level Profiler</h2> -<p> -The bundled high-level profiler offers basic profiling functionality. It -generates simple textual summaries or source code annotations. It can be -accessed with the <a href="#j_p"><tt>-jp</tt></a> command line option -or from Lua code by loading the underlying <tt>jit.p</tt> module. -</p> -<p> -To cut to the chase — run this to get a CPU usage profile by -function name: -</p> -<pre class="code"> -luajit -jp myapp.lua -</pre> -<p> -It's <em>not</em> a stated goal of the bundled profiler to add every -possible option or to cater for special profiling needs. The low-level -profiler APIs are documented below. They may be used by third-party -authors to implement advanced functionality, e.g. IDE integration or -graphical profilers. -</p> -<p> -Note: Sampling works for both interpreted and JIT-compiled code. The -results for JIT-compiled code may sometimes be surprising. LuaJIT -heavily optimizes and inlines Lua code — there's no simple -one-to-one correspondence between source code lines and the sampled -machine code. -</p> - -<h3 id="j_p"><tt>-jp=[options[,output]]</tt></h3> -<p> -The <tt>-jp</tt> command line option starts the high-level profiler. -When the application run by the command line terminates, the profiler -stops and writes the results to <tt>stdout</tt> or to the specified -<tt>output</tt> file. -</p> -<p> -The <tt>options</tt> argument specifies how the profiling is to be -performed: -</p> -<ul> -<li><tt>f</tt> — Stack dump: function name, otherwise module:line. -This is the default mode.</li> -<li><tt>F</tt> — Stack dump: ditto, but dump module:name.</li> -<li><tt>l</tt> — Stack dump: module:line.</li> -<li><tt><number></tt> — stack dump depth (callee ← -caller). Default: 1.</li> -<li><tt>-<number></tt> — Inverse stack dump depth (caller -→ callee).</li> -<li><tt>s</tt> — Split stack dump after first stack level. Implies -depth ≥ 2 or depth ≤ -2.</li> -<li><tt>p</tt> — Show full path for module names.</li> -<li><tt>v</tt> — Show VM states.</li> -<li><tt>z</tt> — Show <a href="#jit_zone">zones</a>.</li> -<li><tt>r</tt> — Show raw sample counts. Default: show percentages.</li> -<li><tt>a</tt> — Annotate excerpts from source code files.</li> -<li><tt>A</tt> — Annotate complete source code files.</li> -<li><tt>G</tt> — Produce raw output suitable for graphical tools.</li> -<li><tt>m<number></tt> — Minimum sample percentage to be shown. -Default: 3%.</li> -<li><tt>i<number></tt> — Sampling interval in milliseconds. -Default: 10ms.<br> -Note: The actual sampling precision is OS-dependent.</li> -</ul> -<p> -The default output for <tt>-jp</tt> is a list of the most CPU consuming -spots in the application. Increasing the stack dump depth with (say) -<tt>-jp=2</tt> may help to point out the main callers or callees of -hotspots. But sample aggregation is still flat per unique stack dump. -</p> -<p> -To get a two-level view (split view) of callers/callees, use -<tt>-jp=s</tt> or <tt>-jp=-s</tt>. The percentages shown for the second -level are relative to the first level. -</p> -<p> -To see how much time is spent in each line relative to a function, use -<tt>-jp=fl</tt>. -</p> -<p> -To see how much time is spent in different VM states or -<a href="#jit_zone">zones</a>, use <tt>-jp=v</tt> or <tt>-jp=z</tt>. -</p> -<p> -Combinations of <tt>v/z</tt> with <tt>f/F/l</tt> produce two-level -views, e.g. <tt>-jp=vf</tt> or <tt>-jp=fv</tt>. This shows the time -spent in a VM state or zone vs. hotspots. This can be used to answer -questions like "Which time consuming functions are only interpreted?" or -"What's the garbage collector overhead for a specific function?". -</p> -<p> -Multiple options can be combined — but not all combinations make -sense, see above. E.g. <tt>-jp=3si4m1</tt> samples three stack levels -deep in 4ms intervals and shows a split view of the CPU consuming -functions and their callers with a 1% threshold. -</p> -<p> -Source code annotations produced by <tt>-jp=a</tt> or <tt>-jp=A</tt> are -always flat and at the line level. Obviously, the source code files need -to be readable by the profiler script. -</p> -<p> -The high-level profiler can also be started and stopped from Lua code with: -</p> -<pre class="code"> -require("jit.p").start(options, output) -... -require("jit.p").stop() -</pre> - -<h3 id="jit_zone"><tt>jit.zone</tt> — Zones</h3> -<p> -Zones can be used to provide information about different parts of an -application to the high-level profiler. E.g. a game could make use of an -<tt>"AI"</tt> zone, a <tt>"PHYS"</tt> zone, etc. Zones are hierarchical, -organized as a stack. -</p> -<p> -The <tt>jit.zone</tt> module needs to be loaded explicitly: -</p> -<pre class="code"> -local zone = require("jit.zone") -</pre> -<ul> -<li><tt>zone("name")</tt> pushes a named zone to the zone stack.</li> -<li><tt>zone()</tt> pops the current zone from the zone stack and -returns its name.</li> -<li><tt>zone:get()</tt> returns the current zone name or <tt>nil</tt>.</li> -<li><tt>zone:flush()</tt> flushes the zone stack.</li> -</ul> -<p> -To show the time spent in each zone use <tt>-jp=z</tt>. To show the time -spent relative to hotspots use e.g. <tt>-jp=zf</tt> or <tt>-jp=fz</tt>. -</p> - -<h2 id="ll_lua_api">Low-level Lua API</h2> -<p> -The <tt>jit.profile</tt> module gives access to the low-level API of the -profiler from Lua code. This module needs to be loaded explicitly: -<pre class="code"> -local profile = require("jit.profile") -</pre> -<p> -This module can be used to implement your own higher-level profiler. -A typical profiling run starts the profiler, captures stack dumps in -the profiler callback, adds them to a hash table to aggregate the number -of samples, stops the profiler and then analyzes all of the captured -stack dumps. Other parameters can be sampled in the profiler callback, -too. But it's important not to spend too much time in the callback, -since this may skew the statistics. -</p> - -<h3 id="profile_start"><tt>profile.start(mode, cb)</tt> -— Start profiler</h3> -<p> -This function starts the profiler. The <tt>mode</tt> argument is a -string holding options: -</p> -<ul> -<li><tt>f</tt> — Profile with precision down to the function level.</li> -<li><tt>l</tt> — Profile with precision down to the line level.</li> -<li><tt>i<number></tt> — Sampling interval in milliseconds (default -10ms).</br> -Note: The actual sampling precision is OS-dependent. -</li> -</ul> -<p> -The <tt>cb</tt> argument is a callback function which is called with -three arguments: <tt>(thread, samples, vmstate)</tt>. The callback is -called on a separate coroutine, the <tt>thread</tt> argument is the -state that holds the stack to sample for profiling. Note: do -<em>not</em> modify the stack of that state or call functions on it. -</p> -<p> -<tt>samples</tt> gives the number of accumulated samples since the last -callback (usually 1). -</p> -<p> -<tt>vmstate</tt> holds the VM state at the time the profiling timer -triggered. This may or may not correspond to the state of the VM when -the profiling callback is called. The state is either <tt>'N'</tt> -native (compiled) code, <tt>'I'</tt> interpreted code, <tt>'C'</tt> -C code, <tt>'G'</tt> the garbage collector, or <tt>'J'</tt> the JIT -compiler. -</p> - -<h3 id="profile_stop"><tt>profile.stop()</tt> -— Stop profiler</h3> -<p> -This function stops the profiler. -</p> - -<h3 id="profile_dump"><tt>dump = profile.dumpstack([thread,] fmt, depth)</tt> -— Dump stack </h3> -<p> -This function allows taking stack dumps in an efficient manner. It -returns a string with a stack dump for the <tt>thread</tt> (coroutine), -formatted according to the <tt>fmt</tt> argument: -</p> -<ul> -<li><tt>p</tt> — Preserve the full path for module names. Otherwise -only the file name is used.</li> -<li><tt>f</tt> — Dump the function name if it can be derived. Otherwise -use module:line.</li> -<li><tt>F</tt> — Ditto, but dump module:name.</li> -<li><tt>l</tt> — Dump module:line.</li> -<li><tt>Z</tt> — Zap the following characters for the last dumped -frame.</li> -<li>All other characters are added verbatim to the output string.</li> -</ul> -<p> -The <tt>depth</tt> argument gives the number of frames to dump, starting -at the topmost frame of the thread. A negative number dumps the frames in -inverse order. -</p> -<p> -The first example prints a list of the current module names and line -numbers of up to 10 frames in separate lines. The second example prints -semicolon-separated function names for all frames (up to 100) in inverse -order: -</p> -<pre class="code"> -print(profile.dumpstack(thread, "l\n", 10)) -print(profile.dumpstack(thread, "lZ;", -100)) -</pre> - -<h2 id="ll_c_api">Low-level C API</h2> -<p> -The profiler can be controlled directly from C code, e.g. for -use by IDEs. The declarations are in <tt>"luajit.h"</tt> (see -<a href="ext_c_api.html">Lua/C API</a> extensions). -</p> - -<h3 id="luaJIT_profile_start"><tt>luaJIT_profile_start(L, mode, cb, data)</tt> -— Start profiler</h3> -<p> -This function starts the profiler. <a href="#profile_start">See -above</a> for a description of the <tt>mode</tt> argument. -</p> -<p> -The <tt>cb</tt> argument is a callback function with the following -declaration: -</p> -<pre class="code"> -typedef void (*luaJIT_profile_callback)(void *data, lua_State *L, - int samples, int vmstate); -</pre> -<p> -<tt>data</tt> is available for use by the callback. <tt>L</tt> is the -state that holds the stack to sample for profiling. Note: do -<em>not</em> modify this stack or call functions on this stack — -use a separate coroutine for this purpose. <a href="#profile_start">See -above</a> for a description of <tt>samples</tt> and <tt>vmstate</tt>. -</p> - -<h3 id="luaJIT_profile_stop"><tt>luaJIT_profile_stop(L)</tt> -— Stop profiler</h3> -<p> -This function stops the profiler. -</p> - -<h3 id="luaJIT_profile_dumpstack"><tt>p = luaJIT_profile_dumpstack(L, fmt, depth, len)</tt> -— Dump stack </h3> -<p> -This function allows taking stack dumps in an efficient manner. -<a href="#profile_dump">See above</a> for a description of <tt>fmt</tt> -and <tt>depth</tt>. -</p> -<p> -This function returns a <tt>const char *</tt> pointing to a -private string buffer of the profiler. The <tt>int *len</tt> -argument returns the length of the output string. The buffer is -overwritten on the next call and deallocated when the profiler stops. -You either need to consume the content immediately or copy it for later -use. -</p> -<br class="flush"> -</div> -<div id="foot"> -<hr class="hide"> -Copyright © 2005-2017 Mike Pall -<span class="noprint"> -· -<a href="contact.html">Contact</a> -</span> -</div> -</body> -</html> diff --git a/Build/source/libs/luajit/LuaJIT-src/doc/extensions.html b/Build/source/libs/luajit/LuaJIT-src/doc/extensions.html deleted file mode 100644 index d7cc9693beb..00000000000 --- a/Build/source/libs/luajit/LuaJIT-src/doc/extensions.html +++ /dev/null @@ -1,482 +0,0 @@ -<!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-2017, 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><li> -<a href="ext_profiler.html">Profiler</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>. -The FFI adds support for -<a href="ext_ffi_semantics.html#cdata_arith">64 bit bitwise operations</a>, -using the same API functions. -</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> - -<h3 id="profiler">Profiler</h3> -<p> -LuaJIT has an <a href="ext_profiler.html">integrated profiler</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, hexadecimal and binary 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> -<p> -Note: <tt>LJ_GC64</tt> mode requires a different frame layout, which implies -a different, incompatible bytecode format for ports that use this mode (e.g. -ARM64 or MIPS64) or when explicitly enabled for x64. This may be rectified -in the future. -</p> - -<h3 id="table_new"><tt>table.new(narray, nhash)</tt> allocates a pre-sized table</h3> -<p> -An extra library function <tt>table.new()</tt> can be made available via -<tt>require("table.new")</tt>. This creates a pre-sized table, just like -the C API equivalent <tt>lua_createtable()</tt>. This is useful for big -tables if the final table size is known and automatic table resizing is -too expensive. -</p> - -<h3 id="table_clear"><tt>table.clear(tab)</tt> clears a table</h3> -<p> -An extra library function <tt>table.clear()</tt> can be made available -via <tt>require("table.clear")</tt>. This clears all keys and values -from a table, but preserves the allocated array/hash sizes. This is -useful when a table, which is linked from multiple places, needs to be -cleared and/or when recycling a table for use by the same context. This -avoids managing backlinks, saves an allocation and the overhead of -incremental array/hash part growth. -</p> -<p> -Please note this function is meant for very specific situations. In most -cases it's better to replace the (usually single) link with a new table -and let the GC do its work. -</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> -<li><tt>string.rep(s, n [,sep])</tt>.</li> -<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>Lua/C API extensions: -<tt>lua_version()</tt> -<tt>lua_upvalueid()</tt> -<tt>lua_upvaluejoin()</tt> -<tt>lua_loadx()</tt> -<tt>lua_copy()</tt> -<tt>lua_tonumberx()</tt> -<tt>lua_tointegerx()</tt> -<tt>luaL_fileresult()</tt> -<tt>luaL_execresult()</tt> -<tt>luaL_loadfilex()</tt> -<tt>luaL_loadbufferx()</tt> -<tt>luaL_traceback()</tt> -<tt>luaL_setfuncs()</tt> -<tt>luaL_pushmodule()</tt> -<tt>luaL_newlibtable()</tt> -<tt>luaL_newlib()</tt> -<tt>luaL_testudata()</tt> -<tt>luaL_setmetatable()</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>.</li> -<li><tt>package.searchers</tt>.</li> -<li><tt>module()</tt> returns the module table.</li> -</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="lua53">Extensions from Lua 5.3</h2> -<p> -LuaJIT supports some extensions from Lua 5.3: -<ul> -<li>Unicode escape <tt>'\u{XX...}'</tt> embeds the UTF-8 encoding in string literals.</li> -<li>The argument table <tt>arg</tt> can be read (and modified) by <tt>LUA_INIT</tt> and <tt>-e</tt> chunks.</li> -<li><tt>io.read()</tt> and <tt>file:read()</tt> accept formats with or without a leading <tt>*</tt>.</li> -<li><tt>table.move(a1, f, e, t [,a2])</tt>.</li> -<li><tt>coroutine.isyieldable()</tt>.</li> -<li>Lua/C API extensions: -<tt>lua_isyieldable()</tt> -</li> -</ul> - -<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+, Clang</td> -<td class="excinterop"><b style="color: #00a000;">Full</b></td> -</tr> -<tr class="even"> -<td class="excplatform">ARM <tt>-DLUAJIT_UNWIND_EXTERNAL</tt></td> -<td class="exccompiler">GCC, Clang</td> -<td class="excinterop"><b style="color: #00a000;">Full</b></td> -</tr> -<tr class="odd"> -<td class="excplatform">Other platforms, DWARF2 unwinding</td> -<td class="exccompiler">GCC, Clang</td> -<td class="excinterop"><b style="color: #c06000;">Limited</b></td> -</tr> -<tr class="even"> -<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="odd"> -<td class="excplatform">Windows/x86</td> -<td class="exccompiler">Any</td> -<td class="excinterop"><b style="color: #00a000;">Full</b></td> -</tr> -<tr class="even"> -<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> -</ul> -<br class="flush"> -</div> -<div id="foot"> -<hr class="hide"> -Copyright © 2005-2017 Mike Pall -<span class="noprint"> -· -<a href="contact.html">Contact</a> -</span> -</div> -</body> -</html> diff --git a/Build/source/libs/luajit/LuaJIT-src/doc/faq.html b/Build/source/libs/luajit/LuaJIT-src/doc/faq.html deleted file mode 100644 index 2c930743ddf..00000000000 --- a/Build/source/libs/luajit/LuaJIT-src/doc/faq.html +++ /dev/null @@ -1,186 +0,0 @@ -<!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-2017, 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><li> -<a href="ext_profiler.html">Profiler</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-2017 Mike Pall -<span class="noprint"> -· -<a href="contact.html">Contact</a> -</span> -</div> -</body> -</html> diff --git a/Build/source/libs/luajit/LuaJIT-src/doc/img/contact.png b/Build/source/libs/luajit/LuaJIT-src/doc/img/contact.png Binary files differdeleted file mode 100644 index 9c73dc594ef..00000000000 --- a/Build/source/libs/luajit/LuaJIT-src/doc/img/contact.png +++ /dev/null diff --git a/Build/source/libs/luajit/LuaJIT-src/doc/install.html b/Build/source/libs/luajit/LuaJIT-src/doc/install.html deleted file mode 100644 index c491c601432..00000000000 --- a/Build/source/libs/luajit/LuaJIT-src/doc/install.html +++ /dev/null @@ -1,692 +0,0 @@ -<!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-2017, 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><li> -<a href="ext_profiler.html">Profiler</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.2+</td> -<td class="compatos">GCC 4.2+</td> -<td class="compatos">XCode 5.0+<br>Clang</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.2+</td> -<td class="compatos">GCC 4.2+<br>ORBIS (<a href="#ps4">PS4</a>)</td> -<td class="compatos">XCode 5.0+<br>Clang</td> -<td class="compatos">MSVC + SDK v7.0<br>WinSDK v7.0<br>Durango (<a href="#xboxone">Xbox One</a>)</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+<br>PSP2 (<a href="#psvita">PS VITA</a>)</td> -<td class="compatos">XCode 5.0+<br>Clang</td> -<td class="compatos compatno"> </td> -</tr> -<tr class="even"> -<td class="compatcpu"><a href="#cross2">ARM64</a></td> -<td class="compatos">GCC 4.8+</td> -<td class="compatos compatno"> </td> -<td class="compatos">XCode 6.0+<br>Clang 3.5+</td> -<td class="compatos compatno"> </td> -</tr> -<tr class="odd"> -<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="even"> -<td class="compatcpu"><a href="#cross2">MIPS32<br>MIPS64</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> -<p> -LuaJIT on x64 currently uses 32 bit GC objects by default. -<tt>LJ_GC64</tt> mode may be explicitly enabled: -add <tt>XCFLAGS=-DLUAJIT_ENABLE_GC64</tt> to the make command or run -<tt>msvcbuild gc64</tt> for MSVC/WinSDK. Please check the note -about the <a href="extensions.html#string_dump">bytecode format</a> -differences, too. -</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.5.tar.gz -cd LuaJIT-2.0.5</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 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> -First, let's clear up some terminology: -</p> -<ul> -<li>Host: This is your development system, usually based on a x64 or x86 CPU.</li> -<li>Target: This is the target system you want LuaJIT to run on, e.g. Android/ARM.</li> -<li>Toolchain: This comprises a C compiler, linker, assembler and a matching C library.</li> -<li>Host (or system) toolchain: This is the toolchain used to build native binaries for your host system.</li> -<li>Cross-compile toolchain: This is the toolchain used to build binaries for the target system. They can only be run on the target system.</li> -</ul> -<p> -The GNU Makefile-based build system allows cross-compiling on any host -for any supported target: -</p> -<ul> -<li>Yes, you need a toolchain for both your host <em>and</em> your target!</li> -<li>Both host and target architectures must have the same pointer size.</li> -<li>E.g. if you want to cross-compile to a 32 bit target on a 64 bit host, 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>).</li> -<li>64 bit targets always require compilation on a 64 bit host.</li> -</ul> -<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: -</p> -<ul> -<li>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.</li> -<li>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>.</li> -<li>Don't forget to specify the same <tt>TARGET_SYS</tt> for the install step, too.</li> -</ul> -<p> -Here are some examples where host and target have the same CPU: -</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: -</o> -<ul> -<li>The best way to get consistent results is to specify the correct settings when building the toolchain yourself.</li> -<li>For a pre-built, generic toolchain add <tt>-mcpu=...</tt> or <tt>-march=...</tt> and other necessary flags to <tt>TARGET_CFLAGS</tt>.</li> -<li>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.</li> -<li>For MIPS it's important to select a supported ABI (o32 on MIPS32, n64 on MIPS64) and consistently compile your project either with hard-float or soft-float compiler settings.</li> -</ul> -<p> -Here are some examples for targets with a different CPU than the host: -</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-A9) -make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabi- \ - TARGET_CFLAGS="-mcpu=cortex-a9 -mfloat-abi=softfp" - -# ARM hard-float ABI with VFP (armhf, most modern toolchains) -make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabihf- - -# ARM64 -make CROSS=aarch64-linux- - -# PPC -make HOST_CC="gcc -m32" CROSS=powerpc-linux-gnu- - -# MIPS32 big-endian -make HOST_CC="gcc -m32" CROSS=mips-linux- -# MIPS32 little-endian -make HOST_CC="gcc -m32" CROSS=mipsel-linux- - -# MIPS64 big-endian -make CROSS=mips-linux- TARGET_CFLAGS="-mips64r2 -mabi=64" -# MIPS64 little-endian -make CROSS=mipsel-linux- TARGET_CFLAGS="-mips64r2 -mabi=64" -</pre> -<p> -You can cross-compile for <b id="android">Android</b> using the <a href="https://developer.android.com/ndk/index.html">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.9 -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.9 -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, mipsel (MIPS32R1 hard-float), Android 4.0+ (ICS) -NDK=/opt/android/ndk -NDKABI=14 -NDKVER=$NDK/toolchains/mipsel-linux-android-4.9 -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.9 -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>: -</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"> -# iOS/ARM (32 bit) -ISDKP=$(xcrun --sdk iphoneos --show-sdk-path) -ICC=$(xcrun --sdk iphoneos --find clang) -ISDKF="-arch armv7 -isysroot $ISDKP" -make DEFAULT_CC=clang HOST_CC="clang -m32 -arch i386" \ - CROSS="$(dirname $ICC)/" TARGET_FLAGS="$ISDKF" TARGET_SYS=iOS - -# iOS/ARM64 -ISDKP=$(xcrun --sdk iphoneos --show-sdk-path) -ICC=$(xcrun --sdk iphoneos --find clang) -ISDKF="-arch arm64 -isysroot $ISDKP" -make DEFAULT_CC=clang CROSS="$(dirname $ICC)/" \ - TARGET_FLAGS="$ISDKF" TARGET_SYS=iOS -</pre> - -<h3 id="consoles">Cross-compiling for consoles</h3> -<p> -Building LuaJIT for consoles requires both a supported host compiler -(x86 or x64) and a cross-compiler (to PPC or ARM) from the official -console SDK. -</p> -<p> -Due to restrictions on consoles, the JIT compiler is disabled and only -the fast interpreter is built. This is still faster than plain Lua, -but much slower than the JIT compiler. The FFI is disabled, too, since -it's not very useful in such an environment. -</p> -<p> -The following commands build a static library <tt>libluajit.a</tt>, -which can be linked against your game, just like the Lua library. -</p> -<p> -To cross-compile for <b id="ps3">PS3</b> from a Linux host (requires -32 bit GCC, i.e. multilib Linux/x64) or a Windows host (requires -32 bit MinGW), run this command: -</p> -<pre class="code"> -make HOST_CC="gcc -m32" CROSS=ppu-lv2- -</pre> -<p> -To cross-compile for <b id="ps4">PS4</b> from a Windows host, -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: -</p> -<pre class="code"> -cd src -ps4build -</pre> -<p> -To cross-compile for <b id="psvita">PS Vita</b> from a Windows host, -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: -</p> -<pre class="code"> -cd src -psvitabuild -</pre> -<p> -To cross-compile for <b id="xbox360">Xbox 360</b> from a Windows host, -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: -</p> -<pre class="code"> -cd src -xedkbuild -</pre> -<p> -To cross-compile for <b id="xboxone">Xbox One</b> from a Windows host, -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: -</p> -<pre class="code"> -cd src -xb1build -</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 which is not built for <tt>LJ_GC64</tt> mode, -you need to link your main executable with these flags: -<pre class="code"> --pagezero_size 10000 -image_base 100000000 -</pre> -</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-2017 Mike Pall -<span class="noprint"> -· -<a href="contact.html">Contact</a> -</span> -</div> -</body> -</html> diff --git a/Build/source/libs/luajit/LuaJIT-src/doc/luajit.html b/Build/source/libs/luajit/LuaJIT-src/doc/luajit.html deleted file mode 100644 index ef5b824c1b3..00000000000 --- a/Build/source/libs/luajit/LuaJIT-src/doc/luajit.html +++ /dev/null @@ -1,236 +0,0 @@ -<!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-2017, 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.os3 td { - color: #40ffff; -} -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><li> -<a href="ext_profiler.html">Profiler</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-2017 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></tr> -</table> -<table class="feature os os3"> -<tr><td>PS3</td><td>PS4</td><td>PS Vita</td><td>Xbox 360</td><td>Xbox One</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<br>x64</td><td>ARM<br>ARM64</td><td>PPC</td><td>MIPS32<br>MIPS64</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-2017 Mike Pall -<span class="noprint"> -· -<a href="contact.html">Contact</a> -</span> -</div> -</body> -</html> diff --git a/Build/source/libs/luajit/LuaJIT-src/doc/running.html b/Build/source/libs/luajit/LuaJIT-src/doc/running.html deleted file mode 100644 index 666b0abca81..00000000000 --- a/Build/source/libs/luajit/LuaJIT-src/doc/running.html +++ /dev/null @@ -1,309 +0,0 @@ -<!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-2017, 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><li> -<a href="ext_profiler.html">Profiler</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> -<li id="j_p"><tt>-jp</tt> — Start the <a href="ext_profiler.html">integrated profiler</a>.</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.5/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-2017 Mike Pall -<span class="noprint"> -· -<a href="contact.html">Contact</a> -</span> -</div> -</body> -</html> diff --git a/Build/source/libs/luajit/LuaJIT-src/doc/status.html b/Build/source/libs/luajit/LuaJIT-src/doc/status.html deleted file mode 100644 index cad6ca65468..00000000000 --- a/Build/source/libs/luajit/LuaJIT-src/doc/status.html +++ /dev/null @@ -1,123 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> -<html> -<head> -<title>Status</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-2017, 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</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><li> -<a href="ext_profiler.html">Profiler</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> -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> -<li> -LuaJIT on 64 bit systems provides a <b>limited range</b> of 47 bits for the -<b>legacy <tt>lightuserdata</tt></b> data type. -This is only relevant on x64 systems which use the negative part of the -virtual address space in user mode, e.g. Solaris/x64, and on ARM64 systems -configured with a 48 bit or 52 bit VA. -Avoid using <tt>lightuserdata</tt> to hold pointers that may point outside -of that range, e.g. variables on the stack. In general, avoid this data -type for new code and replace it with (much more performant) FFI bindings. -FFI cdata pointers can address the full 64 bit range. -</li> -</ul> -<br class="flush"> -</div> -<div id="foot"> -<hr class="hide"> -Copyright © 2005-2017 Mike Pall -<span class="noprint"> -· -<a href="contact.html">Contact</a> -</span> -</div> -</body> -</html> |
