extensions.html (16722B)
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> 2 <html> 3 <head> 4 <title>Extensions</title> 5 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> 6 <meta name="Author" content="Mike Pall"> 7 <meta name="Copyright" content="Copyright (C) 2005-2016, Mike Pall"> 8 <meta name="Language" content="en"> 9 <link rel="stylesheet" type="text/css" href="bluequad.css" media="screen"> 10 <link rel="stylesheet" type="text/css" href="bluequad-print.css" media="print"> 11 <style type="text/css"> 12 table.exc { 13 line-height: 1.2; 14 } 15 tr.exchead td { 16 font-weight: bold; 17 } 18 td.excplatform { 19 width: 48%; 20 } 21 td.exccompiler { 22 width: 29%; 23 } 24 td.excinterop { 25 width: 23%; 26 } 27 </style> 28 </head> 29 <body> 30 <div id="site"> 31 <a href="http://luajit.org"><span>Lua<span id="logo">JIT</span></span></a> 32 </div> 33 <div id="head"> 34 <h1>Extensions</h1> 35 </div> 36 <div id="nav"> 37 <ul><li> 38 <a href="luajit.html">LuaJIT</a> 39 <ul><li> 40 <a href="http://luajit.org/download.html">Download <span class="ext">»</span></a> 41 </li><li> 42 <a href="install.html">Installation</a> 43 </li><li> 44 <a href="running.html">Running</a> 45 </li></ul> 46 </li><li> 47 <a class="current" href="extensions.html">Extensions</a> 48 <ul><li> 49 <a href="ext_ffi.html">FFI Library</a> 50 <ul><li> 51 <a href="ext_ffi_tutorial.html">FFI Tutorial</a> 52 </li><li> 53 <a href="ext_ffi_api.html">ffi.* API</a> 54 </li><li> 55 <a href="ext_ffi_semantics.html">FFI Semantics</a> 56 </li></ul> 57 </li><li> 58 <a href="ext_jit.html">jit.* Library</a> 59 </li><li> 60 <a href="ext_c_api.html">Lua/C API</a> 61 </li><li> 62 <a href="ext_profiler.html">Profiler</a> 63 </li></ul> 64 </li><li> 65 <a href="status.html">Status</a> 66 <ul><li> 67 <a href="changes.html">Changes</a> 68 </li></ul> 69 </li><li> 70 <a href="faq.html">FAQ</a> 71 </li><li> 72 <a href="http://luajit.org/performance.html">Performance <span class="ext">»</span></a> 73 </li><li> 74 <a href="http://wiki.luajit.org/">Wiki <span class="ext">»</span></a> 75 </li><li> 76 <a href="http://luajit.org/list.html">Mailing List <span class="ext">»</span></a> 77 </li></ul> 78 </div> 79 <div id="main"> 80 <p> 81 LuaJIT is fully upwards-compatible with Lua 5.1. It supports all 82 <a href="http://www.lua.org/manual/5.1/manual.html#5"><span class="ext">»</span> standard Lua 83 library functions</a> and the full set of 84 <a href="http://www.lua.org/manual/5.1/manual.html#3"><span class="ext">»</span> Lua/C API 85 functions</a>. 86 </p> 87 <p> 88 LuaJIT is also fully ABI-compatible to Lua 5.1 at the linker/dynamic 89 loader level. This means you can compile a C module against the 90 standard Lua headers and load the same shared library from either Lua 91 or LuaJIT. 92 </p> 93 <p> 94 LuaJIT extends the standard Lua VM with new functionality and adds 95 several extension modules. Please note this page is only about 96 <em>functional</em> enhancements and not about performance enhancements, 97 such as the optimized VM, the faster interpreter or the JIT compiler. 98 </p> 99 100 <h2 id="modules">Extensions Modules</h2> 101 <p> 102 LuaJIT comes with several built-in extension modules: 103 </p> 104 105 <h3 id="bit"><tt>bit.*</tt> — Bitwise operations</h3> 106 <p> 107 LuaJIT supports all bitwise operations as defined by 108 <a href="http://bitop.luajit.org"><span class="ext">»</span> Lua BitOp</a>: 109 </p> 110 <pre class="code"> 111 bit.tobit bit.tohex bit.bnot bit.band bit.bor bit.bxor 112 bit.lshift bit.rshift bit.arshift bit.rol bit.ror bit.bswap 113 </pre> 114 <p> 115 This module is a LuaJIT built-in — you don't need to download or 116 install Lua BitOp. The Lua BitOp site has full documentation for all 117 <a href="http://bitop.luajit.org/api.html"><span class="ext">»</span> Lua BitOp API functions</a>. 118 The FFI adds support for 119 <a href="ext_ffi_semantics.html#cdata_arith">64 bit bitwise operations</a>, 120 using the same API functions. 121 </p> 122 <p> 123 Please make sure to <tt>require</tt> the module before using any of 124 its functions: 125 </p> 126 <pre class="code"> 127 local bit = require("bit") 128 </pre> 129 <p> 130 An already installed Lua BitOp module is ignored by LuaJIT. 131 This way you can use bit operations from both Lua and LuaJIT on a 132 shared installation. 133 </p> 134 135 <h3 id="ffi"><tt>ffi.*</tt> — FFI library</h3> 136 <p> 137 The <a href="ext_ffi.html">FFI library</a> allows calling external 138 C functions and the use of C data structures from pure Lua 139 code. 140 </p> 141 142 <h3 id="jit"><tt>jit.*</tt> — JIT compiler control</h3> 143 <p> 144 The functions in this module 145 <a href="ext_jit.html">control the behavior of the JIT compiler engine</a>. 146 </p> 147 148 <h3 id="c_api">C API extensions</h3> 149 <p> 150 LuaJIT adds some 151 <a href="ext_c_api.html">extra functions to the Lua/C API</a>. 152 </p> 153 154 <h3 id="profiler">Profiler</h3> 155 <p> 156 LuaJIT has an <a href="ext_profiler.html">integrated profiler</a>. 157 </p> 158 159 <h2 id="library">Enhanced Standard Library Functions</h2> 160 161 <h3 id="xpcall"><tt>xpcall(f, err [,args...])</tt> passes arguments</h3> 162 <p> 163 Unlike the standard implementation in Lua 5.1, <tt>xpcall()</tt> 164 passes any arguments after the error function to the function 165 which is called in a protected context. 166 </p> 167 168 <h3 id="load"><tt>loadfile()</tt> etc. handle UTF-8 source code</h3> 169 <p> 170 Non-ASCII characters are handled transparently by the Lua source code parser. 171 This allows the use of UTF-8 characters in identifiers and strings. 172 A UTF-8 BOM is skipped at the start of the source code. 173 </p> 174 175 <h3 id="tostring"><tt>tostring()</tt> etc. canonicalize NaN and ±Inf</h3> 176 <p> 177 All number-to-string conversions consistently convert non-finite numbers 178 to the same strings on all platforms. NaN results in <tt>"nan"</tt>, 179 positive infinity results in <tt>"inf"</tt> and negative infinity results 180 in <tt>"-inf"</tt>. 181 </p> 182 183 <h3 id="tonumber"><tt>tonumber()</tt> etc. use builtin string to number conversion</h3> 184 <p> 185 All string-to-number conversions consistently convert integer and 186 floating-point inputs in decimal, hexadecimal and binary on all platforms. 187 <tt>strtod()</tt> is <em>not</em> used anymore, which avoids numerous 188 problems with poor C library implementations. The builtin conversion 189 function provides full precision according to the IEEE-754 standard, it 190 works independently of the current locale and it supports hex floating-point 191 numbers (e.g. <tt>0x1.5p-3</tt>). 192 </p> 193 194 <h3 id="string_dump"><tt>string.dump(f [,strip])</tt> generates portable bytecode</h3> 195 <p> 196 An extra argument has been added to <tt>string.dump()</tt>. If set to 197 <tt>true</tt>, 'stripped' bytecode without debug information is 198 generated. This speeds up later bytecode loading and reduces memory 199 usage. See also the 200 <a href="running.html#opt_b"><tt>-b</tt> command line option</a>. 201 </p> 202 <p> 203 The generated bytecode is portable and can be loaded on any architecture 204 that LuaJIT supports, independent of word size or endianess. However the 205 bytecode compatibility versions must match. Bytecode stays compatible 206 for dot releases (x.y.0 → x.y.1), but may change with major or 207 minor releases (2.0 → 2.1) or between any beta release. Foreign 208 bytecode (e.g. from Lua 5.1) is incompatible and cannot be loaded. 209 </p> 210 <p> 211 Note: <tt>LJ_GC64</tt> mode requires a different frame layout, which implies 212 a different, incompatible bytecode format for ports that use this mode (e.g. 213 ARM64). This may be rectified in the future. 214 </p> 215 216 <h3 id="table_new"><tt>table.new(narray, nhash)</tt> allocates a pre-sized table</h3> 217 <p> 218 An extra library function <tt>table.new()</tt> can be made available via 219 <tt>require("table.new")</tt>. This creates a pre-sized table, just like 220 the C API equivalent <tt>lua_createtable()</tt>. This is useful for big 221 tables if the final table size is known and automatic table resizing is 222 too expensive. 223 </p> 224 225 <h3 id="table_clear"><tt>table.clear(tab)</tt> clears a table</h3> 226 <p> 227 An extra library function <tt>table.clear()</tt> can be made available 228 via <tt>require("table.clear")</tt>. This clears all keys and values 229 from a table, but preserves the allocated array/hash sizes. This is 230 useful when a table, which is linked from multiple places, needs to be 231 cleared and/or when recycling a table for use by the same context. This 232 avoids managing backlinks, saves an allocation and the overhead of 233 incremental array/hash part growth. 234 </p> 235 <p> 236 Please note this function is meant for very specific situations. In most 237 cases it's better to replace the (usually single) link with a new table 238 and let the GC do its work. 239 </p> 240 241 <h3 id="math_random">Enhanced PRNG for <tt>math.random()</tt></h3> 242 <p> 243 LuaJIT uses a Tausworthe PRNG with period 2^223 to implement 244 <tt>math.random()</tt> and <tt>math.randomseed()</tt>. The quality of 245 the PRNG results is much superior compared to the standard Lua 246 implementation which uses the platform-specific ANSI rand(). 247 </p> 248 <p> 249 The PRNG generates the same sequences from the same seeds on all 250 platforms and makes use of all bits in the seed argument. 251 <tt>math.random()</tt> without arguments generates 52 pseudo-random bits 252 for every call. The result is uniformly distributed between 0.0 and 1.0. 253 It's correctly scaled up and rounded for <tt>math.random(n [,m])</tt> to 254 preserve uniformity. 255 </p> 256 257 <h3 id="io"><tt>io.*</tt> functions handle 64 bit file offsets</h3> 258 <p> 259 The file I/O functions in the standard <tt>io.*</tt> library handle 260 64 bit file offsets. In particular this means it's possible 261 to open files larger than 2 Gigabytes and to reposition or obtain 262 the current file position for offsets beyond 2 GB 263 (<tt>fp:seek()</tt> method). 264 </p> 265 266 <h3 id="debug_meta"><tt>debug.*</tt> functions identify metamethods</h3> 267 <p> 268 <tt>debug.getinfo()</tt> and <tt>lua_getinfo()</tt> also return information 269 about invoked metamethods. The <tt>namewhat</tt> field is set to 270 <tt>"metamethod"</tt> and the <tt>name</tt> field has the name of 271 the corresponding metamethod (e.g. <tt>"__index"</tt>). 272 </p> 273 274 <h2 id="resumable">Fully Resumable VM</h2> 275 <p> 276 The LuaJIT VM is fully resumable. This means you can yield from a 277 coroutine even across contexts, where this would not possible with 278 the standard Lua 5.1 VM: e.g. you can yield across <tt>pcall()</tt> 279 and <tt>xpcall()</tt>, across iterators and across metamethods. 280 </p> 281 282 <h2 id="lua52">Extensions from Lua 5.2</h2> 283 <p> 284 LuaJIT supports some language and library extensions from Lua 5.2. 285 Features that are unlikely to break existing code are unconditionally 286 enabled: 287 </p> 288 <ul> 289 <li><tt>goto</tt> and <tt>::labels::</tt>.</li> 290 <li>Hex escapes <tt>'\x3F'</tt> and <tt>'\*'</tt> escape in strings.</li> 291 <li><tt>load(string|reader [, chunkname [,mode [,env]]])</tt>.</li> 292 <li><tt>loadstring()</tt> is an alias for <tt>load()</tt>.</li> 293 <li><tt>loadfile(filename [,mode [,env]])</tt>.</li> 294 <li><tt>math.log(x [,base])</tt>. 295 <li><tt>string.rep(s, n [,sep])</tt>. 296 <li><tt>string.format()</tt>: <tt>%q</tt> reversible. 297 <tt>%s</tt> checks <tt>__tostring</tt>. 298 <tt>%a</tt> and <tt>"%A</tt> added.</li> 299 <li>String matching pattern <tt>%g</tt> added.</li> 300 <li><tt>io.read("*L")</tt>.</li> 301 <li><tt>io.lines()</tt> and <tt>file:lines()</tt> process 302 <tt>io.read()</tt> options.</li> 303 <li><tt>os.exit(status|true|false [,close])</tt>.</li> 304 <li><tt>package.searchpath(name, path [, sep [, rep]])</tt>.</li> 305 <li><tt>package.loadlib(name, "*")</tt>.</li> 306 <li><tt>debug.getinfo()</tt> returns <tt>nparams</tt> and <tt>isvararg</tt> 307 for option <tt>"u"</tt>.</li> 308 <li><tt>debug.getlocal()</tt> accepts function instead of level.</li> 309 <li><tt>debug.getlocal()</tt> and <tt>debug.setlocal()</tt> accept negative 310 indexes for varargs.</li> 311 <li><tt>debug.getupvalue()</tt> and <tt>debug.setupvalue()</tt> handle 312 C functions.</li> 313 <li><tt>debug.upvalueid()</tt> and <tt>debug.upvaluejoin()</tt>.</li> 314 <li>Command line option <tt>-E</tt>.</li> 315 <li>Command line checks <tt>__tostring</tt> for errors.</li> 316 </ul> 317 <p> 318 Other features are only enabled, if LuaJIT is built with 319 <tt>-DLUAJIT_ENABLE_LUA52COMPAT</tt>: 320 </p> 321 <ul> 322 <li><tt>goto</tt> is a keyword and not a valid variable name anymore.</li> 323 <li><tt>break</tt> can be placed anywhere. Empty statements (<tt>;;</tt>) 324 are allowed.</li> 325 <li><tt>__lt</tt>, <tt>__le</tt> are invoked for mixed types.</li> 326 <li><tt>__len</tt> for tables. <tt>rawlen()</tt> library function.</li> 327 <li><tt>pairs()</tt> and <tt>ipairs()</tt> check for <tt>__pairs</tt> and 328 <tt>__ipairs</tt>.</li> 329 <li><tt>coroutine.running()</tt> returns two results.</li> 330 <li><tt>table.pack()</tt> and <tt>table.unpack()</tt> 331 (same as <tt>unpack()</tt>).</li> 332 <li><tt>io.write()</tt> and <tt>file:write()</tt> return file handle 333 instead of <tt>true</tt>.</li> 334 <li><tt>os.execute()</tt> and <tt>pipe:close()</tt> return detailed 335 exit status.</li> 336 <li><tt>debug.setmetatable()</tt> returns object.</li> 337 <li><tt>debug.getuservalue()</tt> and <tt>debug.setuservalue()</tt>.</li> 338 <li>Remove <tt>math.mod()</tt>, <tt>string.gfind()</tt>. 339 </ul> 340 <p> 341 Note: this provides only partial compatibility with Lua 5.2 at the 342 language and Lua library level. LuaJIT is API+ABI-compatible with 343 Lua 5.1, which prevents implementing features that would otherwise 344 break the Lua/C API and ABI (e.g. <tt>_ENV</tt>). 345 </p> 346 347 <h2 id="lua53">Extensions from Lua 5.3</h2> 348 <p> 349 LuaJIT supports some extensions from Lua 5.3: 350 <ul> 351 <li>Unicode escape <tt>'\u{XX...}'</tt> embeds the UTF-8 encoding in string literals.</li> 352 </ul> 353 354 <h2 id="exceptions">C++ Exception Interoperability</h2> 355 <p> 356 LuaJIT has built-in support for interoperating with C++ exceptions. 357 The available range of features depends on the target platform and 358 the toolchain used to compile LuaJIT: 359 </p> 360 <table class="exc"> 361 <tr class="exchead"> 362 <td class="excplatform">Platform</td> 363 <td class="exccompiler">Compiler</td> 364 <td class="excinterop">Interoperability</td> 365 </tr> 366 <tr class="odd separate"> 367 <td class="excplatform">POSIX/x64, DWARF2 unwinding</td> 368 <td class="exccompiler">GCC 4.3+, Clang</td> 369 <td class="excinterop"><b style="color: #00a000;">Full</b></td> 370 </tr> 371 <tr class="even"> 372 <td class="excplatform">ARM <tt>-DLUAJIT_UNWIND_EXTERNAL</tt></td> 373 <td class="exccompiler">GCC, Clang</td> 374 <td class="excinterop"><b style="color: #00a000;">Full</b></td> 375 </tr> 376 <tr class="odd"> 377 <td class="excplatform">Other platforms, DWARF2 unwinding</td> 378 <td class="exccompiler">GCC, Clang</td> 379 <td class="excinterop"><b style="color: #c06000;">Limited</b></td> 380 </tr> 381 <tr class="even"> 382 <td class="excplatform">Windows/x64</td> 383 <td class="exccompiler">MSVC or WinSDK</td> 384 <td class="excinterop"><b style="color: #00a000;">Full</b></td> 385 </tr> 386 <tr class="odd"> 387 <td class="excplatform">Windows/x86</td> 388 <td class="exccompiler">Any</td> 389 <td class="excinterop"><b style="color: #00a000;">Full</b></td> 390 </tr> 391 <tr class="even"> 392 <td class="excplatform">Other platforms</td> 393 <td class="exccompiler">Other compilers</td> 394 <td class="excinterop"><b style="color: #a00000;">No</b></td> 395 </tr> 396 </table> 397 <p> 398 <b style="color: #00a000;">Full interoperability</b> means: 399 </p> 400 <ul> 401 <li>C++ exceptions can be caught on the Lua side with <tt>pcall()</tt>, 402 <tt>lua_pcall()</tt> etc.</li> 403 <li>C++ exceptions will be converted to the generic Lua error 404 <tt>"C++ exception"</tt>, unless you use the 405 <a href="ext_c_api.html#mode_wrapcfunc">C call wrapper</a> feature.</li> 406 <li>It's safe to throw C++ exceptions across non-protected Lua frames 407 on the C stack. The contents of the C++ exception object 408 pass through unmodified.</li> 409 <li>Lua errors can be caught on the C++ side with <tt>catch(...)</tt>. 410 The corresponding Lua error message can be retrieved from the Lua stack.</li> 411 <li>Throwing Lua errors across C++ frames is safe. C++ destructors 412 will be called.</li> 413 </ul> 414 <p> 415 <b style="color: #c06000;">Limited interoperability</b> means: 416 </p> 417 <ul> 418 <li>C++ exceptions can be caught on the Lua side with <tt>pcall()</tt>, 419 <tt>lua_pcall()</tt> etc.</li> 420 <li>C++ exceptions will be converted to the generic Lua error 421 <tt>"C++ exception"</tt>, unless you use the 422 <a href="ext_c_api.html#mode_wrapcfunc">C call wrapper</a> feature.</li> 423 <li>C++ exceptions will be caught by non-protected Lua frames and 424 are rethrown as a generic Lua error. The C++ exception object will 425 be destroyed.</li> 426 <li>Lua errors <b>cannot</b> be caught on the C++ side.</li> 427 <li>Throwing Lua errors across C++ frames will <b>not</b> call 428 C++ destructors.</li> 429 </ul> 430 431 <p> 432 <b style="color: #a00000;">No interoperability</b> means: 433 </p> 434 <ul> 435 <li>It's <b>not</b> safe to throw C++ exceptions across Lua frames.</li> 436 <li>C++ exceptions <b>cannot</b> be caught on the Lua side.</li> 437 <li>Lua errors <b>cannot</b> be caught on the C++ side.</li> 438 <li>Throwing Lua errors across C++ frames will <b>not</b> call 439 C++ destructors.</li> 440 </ul> 441 <br class="flush"> 442 </div> 443 <div id="foot"> 444 <hr class="hide"> 445 Copyright © 2005-2016 Mike Pall 446 <span class="noprint"> 447 · 448 <a href="contact.html">Contact</a> 449 </span> 450 </div> 451 </body> 452 </html>