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-2011, 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="install.html">Installation</a>
  41 </li><li>
  42 <a href="running.html">Running</a>
  43 </li></ul>
  44 </li><li>
  45 <a class="current" href="extensions.html">Extensions</a>
  46 <ul><li>
  47 <a href="ext_ffi.html">FFI Library</a>
  48 <ul><li>
  49 <a href="ext_ffi_tutorial.html">FFI Tutorial</a>
  50 </li><li>
  51 <a href="ext_ffi_api.html">ffi.* API</a>
  52 </li><li>
  53 <a href="ext_ffi_semantics.html">FFI Semantics</a>
  54 </li></ul>
  55 </li><li>
  56 <a href="ext_jit.html">jit.* Library</a>
  57 </li><li>
  58 <a href="ext_c_api.html">Lua/C API</a>
  59 </li></ul>
  60 </li><li>
  61 <a href="status.html">Status</a>
  62 <ul><li>
  63 <a href="changes.html">Changes</a>
  64 </li></ul>
  65 </li><li>
  66 <a href="faq.html">FAQ</a>
  67 </li><li>
  68 <a href="http://luajit.org/performance.html">Performance <span class="ext">&raquo;</span></a>
  69 </li><li>
  70 <a href="http://luajit.org/download.html">Download <span class="ext">&raquo;</span></a>
  71 </li></ul>
  72 </div>
  73 <div id="main">
  74 <p>
  75 LuaJIT is fully upwards-compatible with Lua 5.1. It supports all
  76 <a href="http://www.lua.org/manual/5.1/manual.html#5"><span class="ext">&raquo;</span>&nbsp;standard Lua
  77 library functions</a> and the full set of
  78 <a href="http://www.lua.org/manual/5.1/manual.html#3"><span class="ext">&raquo;</span>&nbsp;Lua/C API
  79 functions</a>.
  80 </p>
  81 <p>
  82 LuaJIT is also fully ABI-compatible to Lua 5.1 at the linker/dynamic
  83 loader level. This means you can compile a C&nbsp;module against the
  84 standard Lua headers and load the same shared library from either Lua
  85 or LuaJIT.
  86 </p>
  87 <p>
  88 LuaJIT extends the standard Lua VM with new functionality and adds
  89 several extension modules. Please note that this page is only about
  90 <em>functional</em> enhancements and not about performance enhancements,
  91 such as the optimized VM, the faster interpreter or the JIT compiler.
  92 </p>
  93
  94 <h2 id="modules">Extensions Modules</h2>
  95 <p>
  96 LuaJIT comes with several built-in extension modules:
  97 </p>
  98
  99 <h3 id="bit"><tt>bit.*</tt> &mdash; Bitwise operations</h3>
 100 <p>
 101 LuaJIT supports all bitwise operations as defined by
 102 <a href="http://bitop.luajit.org"><span class="ext">&raquo;</span>&nbsp;Lua BitOp</a>:
 103 </p>
 104 <pre class="code">
 105 bit.tobit  bit.tohex  bit.bnot    bit.band bit.bor  bit.bxor
 106 bit.lshift bit.rshift bit.arshift bit.rol  bit.ror  bit.bswap
 107 </pre>
 108 <p>
 109 This module is a LuaJIT built-in &mdash; you don't need to download or
 110 install Lua BitOp. The Lua BitOp site has full documentation for all
 111 <a href="http://bitop.luajit.org/api.html"><span class="ext">&raquo;</span>&nbsp;Lua BitOp API functions</a>.
 112 </p>
 113 <p>
 114 Please make sure to <tt>require</tt> the module before using any of
 115 its functions:
 116 </p>
 117 <pre class="code">
 118 local bit = require("bit")
 119 </pre>
 120 <p>
 121 An already installed Lua BitOp module is ignored by LuaJIT.
 122 This way you can use bit operations from both Lua and LuaJIT on a
 123 shared installation.
 124 </p>
 125
 126 <h3 id="ffi"><tt>ffi.*</tt> &mdash; FFI library</h3>
 127 <p>
 128 The <a href="ext_ffi.html">FFI library</a> allows calling external
 129 C&nbsp;functions and the use of C&nbsp;data structures from pure Lua
 130 code.
 131 </p>
 132
 133 <h3 id="jit"><tt>jit.*</tt> &mdash; JIT compiler control</h3>
 134 <p>
 135 The functions in this module
 136 <a href="ext_jit.html">control the behavior of the JIT compiler engine</a>.
 137 </p>
 138
 139 <h3 id="c_api">C API extensions</h3>
 140 <p>
 141 LuaJIT adds some
 142 <a href="ext_c_api.html">extra functions to the Lua/C API</a>.
 143 </p>
 144
 145 <h2 id="library">Enhanced Standard Library Functions</h2>
 146
 147 <h3 id="xpcall"><tt>xpcall(f, err [,args...])</tt> passes arguments</h3>
 148 <p>
 149 Unlike the standard implementation in Lua 5.1, <tt>xpcall()</tt>
 150 passes any arguments after the error function to the function
 151 which is called in a protected context.
 152 </p>
 153
 154 <h3 id="load"><tt>loadfile()</tt> etc. handle UTF-8 source code</h3>
 155 <p>
 156 Non-ASCII characters are handled transparently by the Lua source code parser.
 157 This allows the use of UTF-8 characters in identifiers and strings.
 158 A UTF-8 BOM is skipped at the start of the source code.
 159 </p>
 160
 161 <h3 id="tostring"><tt>tostring()</tt> etc. canonicalize NaN and &plusmn;Inf</h3>
 162 <p>
 163 All number-to-string conversions consistently convert non-finite numbers
 164 to the same strings on all platforms. NaN results in <tt>"nan"</tt>,
 165 positive infinity results in <tt>"inf"</tt> and negative infinity results
 166 in <tt>"-inf"</tt>.
 167 </p>
 168
 169 <h3 id="string_dump"><tt>string.dump(f [,strip])</tt> generates portable bytecode</h3>
 170 <p>
 171 An extra argument has been added to <tt>string.dump()</tt>. If set to
 172 <tt>true</tt>, 'stripped' bytecode without debug information is
 173 generated. This speeds up later bytecode loading and reduces memory
 174 usage. See also the
 175 <a href="running.html#opt_b"><tt>-b</tt> command line option</a>.
 176 </p>
 177 <p>
 178 The generated bytecode is portable and can be loaded on any architecture
 179 that LuaJIT supports, independent of word size or endianess. However the
 180 bytecode compatibility versions must match. Bytecode stays compatible
 181 for dot releases (x.y.0 &rarr; x.y.1), but may change with major or
 182 minor releases (2.0 &rarr; 2.1) or between any beta release. Foreign
 183 bytecode (e.g. from Lua 5.1) is incompatible and cannot be loaded.
 184 </p>
 185
 186 <h3 id="math_random">Enhanced PRNG for <tt>math.random()</tt></h3>
 187 <p>
 188 LuaJIT uses a Tausworthe PRNG with period 2^223 to implement
 189 <tt>math.random()</tt> and <tt>math.randomseed()</tt>. The quality of
 190 the PRNG results is much superior compared to the standard Lua
 191 implementation which uses the platform-specific ANSI rand().
 192 </p>
 193 <p>
 194 The PRNG generates the same sequences from the same seeds on all
 195 platforms and makes use of all bits in the seed argument.
 196 <tt>math.random()</tt> without arguments generates 52 pseudo-random bits
 197 for every call. The result is uniformly distributed between 0 and 1.
 198 It's correctly scaled up and rounded for <tt>math.random(n&nbsp;[,m])</tt> to
 199 preserve uniformity.
 200 </p>
 201
 202 <h3 id="io"><tt>io.*</tt> functions handle 64&nbsp;bit file offsets</h3>
 203 <p>
 204 The file I/O functions in the standard <tt>io.*</tt> library handle
 205 64&nbsp;bit file offsets. In particular this means it's possible
 206 to open files larger than 2&nbsp;Gigabytes and to reposition or obtain
 207 the current file position for offsets beyond 2&nbsp;GB
 208 (<tt>fp:seek()</tt> method).
 209 </p>
 210
 211 <h3 id="debug_meta"><tt>debug.*</tt> functions identify metamethods</h3>
 212 <p>
 213 <tt>debug.getinfo()</tt> and <tt>lua_getinfo()</tt> also return information
 214 about invoked metamethods. The <tt>namewhat</tt> field is set to
 215 <tt>"metamethod"</tt> and the <tt>name</tt> field has the name of
 216 the corresponding metamethod (e.g. <tt>"__index"</tt>).
 217 </p>
 218
 219 <h2 id="resumable">Fully Resumable VM</h2>
 220 <p>
 221 The LuaJIT 2.x VM is fully resumable. This means you can yield from a
 222 coroutine even across contexts, where this would not possible with
 223 the standard Lua&nbsp;5.1 VM: e.g. you can yield across <tt>pcall()</tt>
 224 and <tt>xpcall()</tt>, across iterators and across metamethods.
 225 </p>
 226 <p>
 227 Note however that LuaJIT 2.x doesn't use
 228 <a href="http://coco.luajit.org/"><span class="ext">&raquo;</span>&nbsp;Coco</a> anymore. This means the
 229 overhead for creating coroutines is much smaller and no extra
 230 C&nbsp;stacks need to be allocated. OTOH you can no longer yield
 231 across arbitrary C&nbsp;functions. Keep this in mind when
 232 upgrading from LuaJIT 1.x.
 233 </p>
 234
 235 <h2 id="exceptions">C++ Exception Interoperability</h2>
 236 <p>
 237 LuaJIT has built-in support for interoperating with C++&nbsp;exceptions.
 238 The available range of features depends on the target platform and
 239 the toolchain used to compile LuaJIT:
 240 </p>
 241 <table class="exc">
 242 <tr class="exchead">
 243 <td class="excplatform">Platform</td>
 244 <td class="exccompiler">Compiler</td>
 245 <td class="excinterop">Interoperability</td>
 246 </tr>
 247 <tr class="odd separate">
 248 <td class="excplatform">POSIX/x64, DWARF2 unwinding</td>
 249 <td class="exccompiler">GCC 4.3+</td>
 250 <td class="excinterop"><b style="color: #00a000;">Full</b></td>
 251 </tr>
 252 <tr class="even">
 253 <td class="excplatform">Other platforms, DWARF2 unwinding</td>
 254 <td class="exccompiler">GCC</td>
 255 <td class="excinterop"><b style="color: #c06000;">Limited</b></td>
 256 </tr>
 257 <tr class="odd">
 258 <td class="excplatform">Windows/x64</td>
 259 <td class="exccompiler">MSVC or WinSDK</td>
 260 <td class="excinterop"><b style="color: #00a000;">Full</b></td>
 261 </tr>
 262 <tr class="even">
 263 <td class="excplatform">Windows/x86</td>
 264 <td class="exccompiler">Any</td>
 265 <td class="excinterop"><b style="color: #a00000;">No</b></td>
 266 </tr>
 267 <tr class="odd">
 268 <td class="excplatform">Other platforms</td>
 269 <td class="exccompiler">Other compilers</td>
 270 <td class="excinterop"><b style="color: #a00000;">No</b></td>
 271 </tr>
 272 </table>
 273 <p>
 274 <b style="color: #00a000;">Full interoperability</b> means:
 275 </p>
 276 <ul>
 277 <li>C++&nbsp;exceptions can be caught on the Lua side with <tt>pcall()</tt>,
 278 <tt>lua_pcall()</tt> etc.</li>
 279 <li>C++&nbsp;exceptions will be converted to the generic Lua error
 280 <tt>"C++&nbsp;exception"</tt>, unless you use the
 281 <a href="ext_c_api.html#mode_wrapcfunc">C&nbsp;call wrapper</a> feature.</li>
 282 <li>It's safe to throw C++&nbsp;exceptions across non-protected Lua frames
 283 on the C&nbsp;stack. The contents of the C++&nbsp;exception object
 284 pass through unmodified.</li>
 285 <li>Lua errors can be caught on the C++ side with <tt>catch(...)</tt>.
 286 The corresponding Lua error message can be retrieved from the Lua stack.</li>
 287 <li>Throwing Lua errors across C++ frames is safe. C++ destructors
 288 will be called.</li>
 289 </ul>
 290 <p>
 291 <b style="color: #c06000;">Limited interoperability</b> means:
 292 </p>
 293 <ul>
 294 <li>C++&nbsp;exceptions can be caught on the Lua side with <tt>pcall()</tt>,
 295 <tt>lua_pcall()</tt> etc.</li>
 296 <li>C++&nbsp;exceptions will be converted to the generic Lua error
 297 <tt>"C++&nbsp;exception"</tt>, unless you use the
 298 <a href="ext_c_api.html#mode_wrapcfunc">C&nbsp;call wrapper</a> feature.</li>
 299 <li>C++&nbsp;exceptions will be caught by non-protected Lua frames and
 300 are rethrown as a generic Lua error. The C++&nbsp;exception object will
 301 be destroyed.</li>
 302 <li>Lua errors <b>cannot</b> be caught on the C++ side.</li>
 303 <li>Throwing Lua errors across C++ frames will <b>not</b> call
 304 C++ destructors.</li>
 305 </ul>
 306
 307 <p>
 308 <b style="color: #a00000;">No interoperability</b> means:
 309 </p>
 310 <ul>
 311 <li>It's <b>not</b> safe to throw C++&nbsp;exceptions across Lua frames.</li>
 312 <li>C++&nbsp;exceptions <b>cannot</b> be caught on the Lua side.</li>
 313 <li>Lua errors <b>cannot</b> be caught on the C++ side.</li>
 314 <li>Throwing Lua errors across C++ frames will <b>not</b> call
 315 C++ destructors.</li>
 316 <li>Additionally, on Windows/x86 with SEH-based C++&nbsp;exceptions:
 317 it's <b>not</b> safe to throw a Lua error across any frames containing
 318 a C++ function with any try/catch construct or using variables with
 319 (implicit) destructors. This also applies to any functions which may be
 320 inlined in such a function. It doesn't matter whether <tt>lua_error()</tt>
 321 is called inside or outside of a try/catch or whether any object actually
 322 needs to be destroyed: the SEH chain is corrupted and this will eventually
 323 lead to the termination of the process.</li>
 324 </ul>
 325 <br class="flush">
 326 </div>
 327 <div id="foot">
 328 <hr class="hide">
 329 Copyright &copy; 2005-2011 Mike Pall
 330 <span class="noprint">
 331 &middot;
 332 <a href="contact.html">Contact</a>
 333 </span>
 334 </div>
 335 </body>
 336 </html>