doc/extensions.html

   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-2012, 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">&raquo;</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></ul>
  62 </li><li>
  63 <a href="status.html">Status</a>
  64 <ul><li>
  65 <a href="changes.html">Changes</a>
  66 </li></ul>
  67 </li><li>
  68 <a href="faq.html">FAQ</a>
  69 </li><li>
  70 <a href="http://luajit.org/performance.html">Performance <span class="ext">&raquo;</span></a>
  71 </li><li>
  72 <a href="http://wiki.luajit.org/">Wiki <span class="ext">&raquo;</span></a>
  73 </li><li>
  74 <a href="http://luajit.org/list.html">Mailing List <span class="ext">&raquo;</span></a>
  75 </li></ul>
  76 </div>
  77 <div id="main">
  78 <p>
  79 LuaJIT is fully upwards-compatible with Lua 5.1. It supports all
  80 <a href="http://www.lua.org/manual/5.1/manual.html#5"><span class="ext">&raquo;</span>&nbsp;standard Lua
  81 library functions</a> and the full set of
  82 <a href="http://www.lua.org/manual/5.1/manual.html#3"><span class="ext">&raquo;</span>&nbsp;Lua/C API
  83 functions</a>.
  84 </p>
  85 <p>
  86 LuaJIT is also fully ABI-compatible to Lua 5.1 at the linker/dynamic
  87 loader level. This means you can compile a C&nbsp;module against the
  88 standard Lua headers and load the same shared library from either Lua
  89 or LuaJIT.
  90 </p>
  91 <p>
  92 LuaJIT extends the standard Lua VM with new functionality and adds
  93 several extension modules. Please note this page is only about
  94 <em>functional</em> enhancements and not about performance enhancements,
  95 such as the optimized VM, the faster interpreter or the JIT compiler.
  96 </p>
  97
  98 <h2 id="modules">Extensions Modules</h2>
  99 <p>
 100 LuaJIT comes with several built-in extension modules:
 101 </p>
 102
 103 <h3 id="bit"><tt>bit.*</tt> &mdash; Bitwise operations</h3>
 104 <p>
 105 LuaJIT supports all bitwise operations as defined by
 106 <a href="http://bitop.luajit.org"><span class="ext">&raquo;</span>&nbsp;Lua BitOp</a>:
 107 </p>
 108 <pre class="code">
 109 bit.tobit  bit.tohex  bit.bnot    bit.band bit.bor  bit.bxor
 110 bit.lshift bit.rshift bit.arshift bit.rol  bit.ror  bit.bswap
 111 </pre>
 112 <p>
 113 This module is a LuaJIT built-in &mdash; you don't need to download or
 114 install Lua BitOp. The Lua BitOp site has full documentation for all
 115 <a href="http://bitop.luajit.org/api.html"><span class="ext">&raquo;</span>&nbsp;Lua BitOp API functions</a>.
 116 </p>
 117 <p>
 118 Please make sure to <tt>require</tt> the module before using any of
 119 its functions:
 120 </p>
 121 <pre class="code">
 122 local bit = require("bit")
 123 </pre>
 124 <p>
 125 An already installed Lua BitOp module is ignored by LuaJIT.
 126 This way you can use bit operations from both Lua and LuaJIT on a
 127 shared installation.
 128 </p>
 129
 130 <h3 id="ffi"><tt>ffi.*</tt> &mdash; FFI library</h3>
 131 <p>
 132 The <a href="ext_ffi.html">FFI library</a> allows calling external
 133 C&nbsp;functions and the use of C&nbsp;data structures from pure Lua
 134 code.
 135 </p>
 136
 137 <h3 id="jit"><tt>jit.*</tt> &mdash; JIT compiler control</h3>
 138 <p>
 139 The functions in this module
 140 <a href="ext_jit.html">control the behavior of the JIT compiler engine</a>.
 141 </p>
 142
 143 <h3 id="c_api">C API extensions</h3>
 144 <p>
 145 LuaJIT adds some
 146 <a href="ext_c_api.html">extra functions to the Lua/C API</a>.
 147 </p>
 148
 149 <h2 id="library">Enhanced Standard Library Functions</h2>
 150
 151 <h3 id="xpcall"><tt>xpcall(f, err [,args...])</tt> passes arguments</h3>
 152 <p>
 153 Unlike the standard implementation in Lua 5.1, <tt>xpcall()</tt>
 154 passes any arguments after the error function to the function
 155 which is called in a protected context.
 156 </p>
 157
 158 <h3 id="load"><tt>loadfile()</tt> etc. handle UTF-8 source code</h3>
 159 <p>
 160 Non-ASCII characters are handled transparently by the Lua source code parser.
 161 This allows the use of UTF-8 characters in identifiers and strings.
 162 A UTF-8 BOM is skipped at the start of the source code.
 163 </p>
 164
 165 <h3 id="tostring"><tt>tostring()</tt> etc. canonicalize NaN and &plusmn;Inf</h3>
 166 <p>
 167 All number-to-string conversions consistently convert non-finite numbers
 168 to the same strings on all platforms. NaN results in <tt>"nan"</tt>,
 169 positive infinity results in <tt>"inf"</tt> and negative infinity results
 170 in <tt>"-inf"</tt>.
 171 </p>
 172
 173 <h3 id="tonumber"><tt>tonumber()</tt> etc. use builtin string to number conversion</h3>
 174 <p>
 175 All string-to-number conversions consistently convert integer and
 176 floating-point inputs in decimal and hexadecimal on all platforms.
 177 <tt>strtod()</tt> is <em>not</em> used anymore, which avoids numerous
 178 problems with poor C library implementations. The builtin conversion
 179 function provides full precision according to the IEEE-754 standard, it
 180 works independently of the current locale and it supports hex floating-point
 181 numbers (e.g. <tt>0x1.5p-3</tt>).
 182 </p>
 183
 184 <h3 id="string_dump"><tt>string.dump(f [,strip])</tt> generates portable bytecode</h3>
 185 <p>
 186 An extra argument has been added to <tt>string.dump()</tt>. If set to
 187 <tt>true</tt>, 'stripped' bytecode without debug information is
 188 generated. This speeds up later bytecode loading and reduces memory
 189 usage. See also the
 190 <a href="running.html#opt_b"><tt>-b</tt> command line option</a>.
 191 </p>
 192 <p>
 193 The generated bytecode is portable and can be loaded on any architecture
 194 that LuaJIT supports, independent of word size or endianess. However the
 195 bytecode compatibility versions must match. Bytecode stays compatible
 196 for dot releases (x.y.0 &rarr; x.y.1), but may change with major or
 197 minor releases (2.0 &rarr; 2.1) or between any beta release. Foreign
 198 bytecode (e.g. from Lua 5.1) is incompatible and cannot be loaded.
 199 </p>
 200
 201 <h3 id="math_random">Enhanced PRNG for <tt>math.random()</tt></h3>
 202 <p>
 203 LuaJIT uses a Tausworthe PRNG with period 2^223 to implement
 204 <tt>math.random()</tt> and <tt>math.randomseed()</tt>. The quality of
 205 the PRNG results is much superior compared to the standard Lua
 206 implementation which uses the platform-specific ANSI rand().
 207 </p>
 208 <p>
 209 The PRNG generates the same sequences from the same seeds on all
 210 platforms and makes use of all bits in the seed argument.
 211 <tt>math.random()</tt> without arguments generates 52 pseudo-random bits
 212 for every call. The result is uniformly distributed between 0.0 and 1.0.
 213 It's correctly scaled up and rounded for <tt>math.random(n&nbsp;[,m])</tt> to
 214 preserve uniformity.
 215 </p>
 216
 217 <h3 id="io"><tt>io.*</tt> functions handle 64&nbsp;bit file offsets</h3>
 218 <p>
 219 The file I/O functions in the standard <tt>io.*</tt> library handle
 220 64&nbsp;bit file offsets. In particular this means it's possible
 221 to open files larger than 2&nbsp;Gigabytes and to reposition or obtain
 222 the current file position for offsets beyond 2&nbsp;GB
 223 (<tt>fp:seek()</tt> method).
 224 </p>
 225
 226 <h3 id="debug_meta"><tt>debug.*</tt> functions identify metamethods</h3>
 227 <p>
 228 <tt>debug.getinfo()</tt> and <tt>lua_getinfo()</tt> also return information
 229 about invoked metamethods. The <tt>namewhat</tt> field is set to
 230 <tt>"metamethod"</tt> and the <tt>name</tt> field has the name of
 231 the corresponding metamethod (e.g. <tt>"__index"</tt>).
 232 </p>
 233
 234 <h2 id="resumable">Fully Resumable VM</h2>
 235 <p>
 236 The LuaJIT 2.x VM is fully resumable. This means you can yield from a
 237 coroutine even across contexts, where this would not possible with
 238 the standard Lua&nbsp;5.1 VM: e.g. you can yield across <tt>pcall()</tt>
 239 and <tt>xpcall()</tt>, across iterators and across metamethods.
 240 </p>
 241 <p>
 242 Note however that LuaJIT 2.x doesn't use
 243 <a href="http://coco.luajit.org/"><span class="ext">&raquo;</span>&nbsp;Coco</a> anymore. This means the
 244 overhead for creating coroutines is much smaller and no extra
 245 C&nbsp;stacks need to be allocated. OTOH you can no longer yield
 246 across arbitrary C&nbsp;functions. Keep this in mind when
 247 upgrading from LuaJIT 1.x.
 248 </p>
 249
 250 <h2 id="lua52">Extensions from Lua 5.2</h2>
 251 <p>
 252 LuaJIT supports some language and library extensions from Lua&nbsp;5.2.
 253 Features that are unlikely to break existing code are unconditionally
 254 enabled:
 255 </p>
 256 <ul>
 257 <li><tt>goto</tt> and <tt>::labels::</tt>.</li>
 258 <li>Hex escapes <tt>'\x3F'</tt> and <tt>'\*'</tt> escape in strings.</li>
 259 <li><tt>load(string|reader, chunkname [,mode [,env]])</tt>.
 260 <tt>loadstring()</tt> is an alias.</li>
 261 <li><tt>math.log(x [,base])</tt>.
 262 <li><tt>string.rep(s, n [,sep])</tt>.
 263 <li><tt>string.format()</tt>: <tt>%q</tt> reversible.
 264 <tt>%s</tt> checks <tt>__tostring</tt>.
 265 <tt>%a</tt> and <tt>"%A</tt> added.</li>
 266 <li>String matching pattern <tt>%g</tt> added.</li>
 267 <li><tt>io.read("*L")</tt>.</li>
 268 <li><tt>io.lines()</tt> and <tt>file:lines()</tt> process
 269 <tt>io.read()</tt> options.</li>
 270 <li><tt>os.exit(status|true|false [,close])</tt>.</li>
 271 <li><tt>package.searchpath(name, path [, sep [, rep]])</tt>.</li>
 272 <li><tt>package.loadlib(name, "*")</tt>.</li>
 273 <li><tt>debug.getinfo()</tt> returns <tt>nparams</tt> and <tt>isvararg</tt>
 274 for option <tt>"u"</tt>.</li>
 275 <li><tt>debug.getlocal()</tt> accepts function instead of level.</li>
 276 <li><tt>debug.getlocal()</tt> and <tt>debug.setlocal()</tt> accept negative
 277 indexes for varargs.</li>
 278 <li><tt>debug.getupvalue()</tt> and <tt>debug.setupvalue()</tt> handle
 279 C&nbsp;functions.</li>
 280 <li><tt>debug.upvalueid()</tt> and <tt>debug.upvaluejoin()</tt>.</li>
 281 <li>Command line option <tt>-E</tt>.</li>
 282 <li>Command line checks <tt>__tostring</tt> for errors.</li>
 283 </ul>
 284 <p>
 285 Other features are only enabled, if LuaJIT is built with
 286 <tt>-DLUAJIT_ENABLE_LUA52COMPAT</tt>:
 287 </p>
 288 <ul>
 289 <li><tt>goto</tt> is a keyword and not a valid variable name anymore.</li>
 290 <li><tt>break</tt> can be placed anywhere. Empty statements (<tt>;;</tt>)
 291 are allowed.</li>
 292 <li><tt>__lt</tt>, <tt>__le</tt> are invoked for mixed types.</li>
 293 <li><tt>__len</tt> for tables. <tt>rawlen()</tt> library function.</li>
 294 <li><tt>pairs()</tt> and <tt>ipairs()</tt> check for <tt>__pairs</tt> and
 295 <tt>__ipairs</tt>.</li>
 296 <li><tt>coroutine.running()</tt> returns two results.</li>
 297 <li><tt>table.pack()</tt> and <tt>table.unpack()</tt>
 298 (same as <tt>unpack()</tt>).</li>
 299 <li><tt>io.write()</tt> and <tt>file:write()</tt> return file handle
 300 instead of <tt>true</tt>.</li>
 301 <li><tt>os.execute()</tt> and <tt>pipe:close()</tt> return detailed
 302 exit status.</li>
 303 <li><tt>debug.setmetatable()</tt> returns object.</li>
 304 <li><tt>debug.getuservalue()</tt> and <tt>debug.setuservalue()</tt>.</li>
 305 <li>Remove <tt>math.mod()</tt>, <tt>string.gfind()</tt>.
 306 </ul>
 307 <p>
 308 Note: this provides only partial compatibility with Lua 5.2 at the
 309 language and Lua library level. LuaJIT is API+ABI-compatible with
 310 Lua&nbsp;5.1, which prevents implementing features that would otherwise
 311 break the Lua/C API and ABI (e.g. <tt>_ENV</tt>).
 312 </p>
 313
 314 <h2 id="exceptions">C++ Exception Interoperability</h2>
 315 <p>
 316 LuaJIT has built-in support for interoperating with C++&nbsp;exceptions.
 317 The available range of features depends on the target platform and
 318 the toolchain used to compile LuaJIT:
 319 </p>
 320 <table class="exc">
 321 <tr class="exchead">
 322 <td class="excplatform">Platform</td>
 323 <td class="exccompiler">Compiler</td>
 324 <td class="excinterop">Interoperability</td>
 325 </tr>
 326 <tr class="odd separate">
 327 <td class="excplatform">POSIX/x64, DWARF2 unwinding</td>
 328 <td class="exccompiler">GCC 4.3+</td>
 329 <td class="excinterop"><b style="color: #00a000;">Full</b></td>
 330 </tr>
 331 <tr class="even">
 332 <td class="excplatform">Other platforms, DWARF2 unwinding</td>
 333 <td class="exccompiler">GCC</td>
 334 <td class="excinterop"><b style="color: #c06000;">Limited</b></td>
 335 </tr>
 336 <tr class="odd">
 337 <td class="excplatform">Windows/x64</td>
 338 <td class="exccompiler">MSVC or WinSDK</td>
 339 <td class="excinterop"><b style="color: #00a000;">Full</b></td>
 340 </tr>
 341 <tr class="even">
 342 <td class="excplatform">Windows/x86</td>
 343 <td class="exccompiler">Any</td>
 344 <td class="excinterop"><b style="color: #a00000;">No</b></td>
 345 </tr>
 346 <tr class="odd">
 347 <td class="excplatform">Other platforms</td>
 348 <td class="exccompiler">Other compilers</td>
 349 <td class="excinterop"><b style="color: #a00000;">No</b></td>
 350 </tr>
 351 </table>
 352 <p>
 353 <b style="color: #00a000;">Full interoperability</b> means:
 354 </p>
 355 <ul>
 356 <li>C++&nbsp;exceptions can be caught on the Lua side with <tt>pcall()</tt>,
 357 <tt>lua_pcall()</tt> etc.</li>
 358 <li>C++&nbsp;exceptions will be converted to the generic Lua error
 359 <tt>"C++&nbsp;exception"</tt>, unless you use the
 360 <a href="ext_c_api.html#mode_wrapcfunc">C&nbsp;call wrapper</a> feature.</li>
 361 <li>It's safe to throw C++&nbsp;exceptions across non-protected Lua frames
 362 on the C&nbsp;stack. The contents of the C++&nbsp;exception object
 363 pass through unmodified.</li>
 364 <li>Lua errors can be caught on the C++ side with <tt>catch(...)</tt>.
 365 The corresponding Lua error message can be retrieved from the Lua stack.</li>
 366 <li>Throwing Lua errors across C++ frames is safe. C++ destructors
 367 will be called.</li>
 368 </ul>
 369 <p>
 370 <b style="color: #c06000;">Limited interoperability</b> means:
 371 </p>
 372 <ul>
 373 <li>C++&nbsp;exceptions can be caught on the Lua side with <tt>pcall()</tt>,
 374 <tt>lua_pcall()</tt> etc.</li>
 375 <li>C++&nbsp;exceptions will be converted to the generic Lua error
 376 <tt>"C++&nbsp;exception"</tt>, unless you use the
 377 <a href="ext_c_api.html#mode_wrapcfunc">C&nbsp;call wrapper</a> feature.</li>
 378 <li>C++&nbsp;exceptions will be caught by non-protected Lua frames and
 379 are rethrown as a generic Lua error. The C++&nbsp;exception object will
 380 be destroyed.</li>
 381 <li>Lua errors <b>cannot</b> be caught on the C++ side.</li>
 382 <li>Throwing Lua errors across C++ frames will <b>not</b> call
 383 C++ destructors.</li>
 384 </ul>
 385
 386 <p>
 387 <b style="color: #a00000;">No interoperability</b> means:
 388 </p>
 389 <ul>
 390 <li>It's <b>not</b> safe to throw C++&nbsp;exceptions across Lua frames.</li>
 391 <li>C++&nbsp;exceptions <b>cannot</b> be caught on the Lua side.</li>
 392 <li>Lua errors <b>cannot</b> be caught on the C++ side.</li>
 393 <li>Throwing Lua errors across C++ frames will <b>not</b> call
 394 C++ destructors.</li>
 395 <li>Additionally, on Windows/x86 with SEH-based C++&nbsp;exceptions:
 396 it's <b>not</b> safe to throw a Lua error across any frames containing
 397 a C++ function with any try/catch construct or using variables with
 398 (implicit) destructors. This also applies to any functions which may be
 399 inlined in such a function. It doesn't matter whether <tt>lua_error()</tt>
 400 is called inside or outside of a try/catch or whether any object actually
 401 needs to be destroyed: the SEH chain is corrupted and this will eventually
 402 lead to the termination of the process.</li>
 403 </ul>
 404 <br class="flush">
 405 </div>
 406 <div id="foot">
 407 <hr class="hide">
 408 Copyright &copy; 2005-2012 Mike Pall
 409 <span class="noprint">
 410 &middot;
 411 <a href="contact.html">Contact</a>
 412 </span>
 413 </div>
 414 </body>
 415 </html>