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="math_random">Enhanced PRNG for <tt>math.random()</tt></h3>
 170 <p>
 171 LuaJIT uses a Tausworthe PRNG with period 2^223 to implement
 172 <tt>math.random()</tt> and <tt>math.randomseed()</tt>. The quality of
 173 the PRNG results is much superior compared to the standard Lua
 174 implementation which uses the platform-specific ANSI rand().
 175 </p>
 176 <p>
 177 The PRNG generates the same sequences from the same seeds on all
 178 platforms and makes use of all bits in the seed argument.
 179 <tt>math.random()</tt> without arguments generates 52 pseudo-random bits
 180 for every call. The result is uniformly distributed between 0 and 1.
 181 It's correctly scaled up and rounded for <tt>math.random(n&nbsp;[,m])</tt> to
 182 preserve uniformity.
 183 </p>
 184
 185 <h3 id="io"><tt>io.*</tt> functions handle 64&nbsp;bit file offsets</h3>
 186 <p>
 187 The file I/O functions in the standard <tt>io.*</tt> library handle
 188 64&nbsp;bit file offsets. In particular this means it's possible
 189 to open files larger than 2&nbsp;Gigabytes and to reposition or obtain
 190 the current file position for offsets beyond 2&nbsp;GB
 191 (<tt>fp:seek()</tt> method).
 192 </p>
 193
 194 <h3 id="debug_meta"><tt>debug.*</tt> functions identify metamethods</h3>
 195 <p>
 196 <tt>debug.getinfo()</tt> and <tt>lua_getinfo()</tt> also return information
 197 about invoked metamethods. The <tt>namewhat</tt> field is set to
 198 <tt>"metamethod"</tt> and the <tt>name</tt> field has the name of
 199 the corresponding metamethod (e.g. <tt>"__index"</tt>).
 200 </p>
 201
 202 <h2 id="resumable">Fully Resumable VM</h2>
 203 <p>
 204 The LuaJIT 2.x VM is fully resumable. This means you can yield from a
 205 coroutine even across contexts, where this would not possible with
 206 the standard Lua&nbsp;5.1 VM: e.g. you can yield across <tt>pcall()</tt>
 207 and <tt>xpcall()</tt>, across iterators and across metamethods.
 208 </p>
 209 <p>
 210 Note however that LuaJIT 2.x doesn't use
 211 <a href="http://coco.luajit.org/"><span class="ext">&raquo;</span>&nbsp;Coco</a> anymore. This means the
 212 overhead for creating coroutines is much smaller and no extra
 213 C&nbsp;stacks need to be allocated. OTOH you can no longer yield
 214 across arbitrary C&nbsp;functions. Keep this in mind when
 215 upgrading from LuaJIT 1.x.
 216 </p>
 217
 218 <h2 id="exceptions">C++ Exception Interoperability</h2>
 219 <p>
 220 LuaJIT has built-in support for interoperating with C++&nbsp;exceptions.
 221 The available range of features depends on the target platform and
 222 the toolchain used to compile LuaJIT:
 223 </p>
 224 <table class="exc">
 225 <tr class="exchead">
 226 <td class="excplatform">Platform</td>
 227 <td class="exccompiler">Compiler</td>
 228 <td class="excinterop">Interoperability</td>
 229 </tr>
 230 <tr class="odd separate">
 231 <td class="excplatform">POSIX/x64, DWARF2 unwinding</td>
 232 <td class="exccompiler">GCC 4.3+</td>
 233 <td class="excinterop"><b style="color: #00a000;">Full</b></td>
 234 </tr>
 235 <tr class="even">
 236 <td class="excplatform">Other platforms, DWARF2 unwinding</td>
 237 <td class="exccompiler">GCC</td>
 238 <td class="excinterop"><b style="color: #c06000;">Limited</b></td>
 239 </tr>
 240 <tr class="odd">
 241 <td class="excplatform">Windows/x64</td>
 242 <td class="exccompiler">MSVC or WinSDK</td>
 243 <td class="excinterop"><b style="color: #00a000;">Full</b></td>
 244 </tr>
 245 <tr class="even">
 246 <td class="excplatform">Windows/x86</td>
 247 <td class="exccompiler">Any</td>
 248 <td class="excinterop"><b style="color: #a00000;">No</b></td>
 249 </tr>
 250 <tr class="odd">
 251 <td class="excplatform">Other platforms</td>
 252 <td class="exccompiler">Other compilers</td>
 253 <td class="excinterop"><b style="color: #a00000;">No</b></td>
 254 </tr>
 255 </table>
 256 <p>
 257 <b style="color: #00a000;">Full interoperability</b> means:
 258 </p>
 259 <ul>
 260 <li>C++&nbsp;exceptions can be caught on the Lua side with <tt>pcall()</tt>,
 261 <tt>lua_pcall()</tt> etc.</li>
 262 <li>C++&nbsp;exceptions will be converted to the generic Lua error
 263 <tt>"C++&nbsp;exception"</tt>, unless you use the
 264 <a href="ext_c_api.html#mode_wrapcfunc">C&nbsp;call wrapper</a> feature.</li>
 265 <li>It's safe to throw C++&nbsp;exceptions across non-protected Lua frames
 266 on the C&nbsp;stack. The contents of the C++&nbsp;exception object
 267 pass through unmodified.</li>
 268 <li>Lua errors can be caught on the C++ side with <tt>catch(...)</tt>.
 269 The corresponding Lua error message can be retrieved from the Lua stack.</li>
 270 <li>Throwing Lua errors across C++ frames is safe. C++ destructors
 271 will be called.</li>
 272 </ul>
 273 <p>
 274 <b style="color: #c06000;">Limited 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>C++&nbsp;exceptions will be caught by non-protected Lua frames and
 283 are rethrown as a generic Lua error. The C++&nbsp;exception object will
 284 be destroyed.</li>
 285 <li>Lua errors <b>cannot</b> be caught on the C++ side.</li>
 286 <li>Throwing Lua errors across C++ frames will <b>not</b> call
 287 C++ destructors.</li>
 288 </ul>
 289
 290 <p>
 291 <b style="color: #a00000;">No interoperability</b> means:
 292 </p>
 293 <ul>
 294 <li>It's <b>not</b> safe to throw C++&nbsp;exceptions across Lua frames.</li>
 295 <li>C++&nbsp;exceptions <b>cannot</b> be caught on the Lua side.</li>
 296 <li>Lua errors <b>cannot</b> be caught on the C++ side.</li>
 297 <li>Throwing Lua errors across C++ frames will <b>not</b> call
 298 C++ destructors.</li>
 299 <li>Additionally, on Windows/x86 with SEH-based C++&nbsp;exceptions:
 300 it's <b>not</b> safe to throw a Lua error across any frames containing
 301 a C++ function with any try/catch construct or using variables with
 302 (implicit) destructors. This also applies to any functions which may be
 303 inlined in such a function. It doesn't matter whether <tt>lua_error()</tt>
 304 is called inside or outside of a try/catch or whether any object actually
 305 needs to be destroyed: the SEH chain is corrupted and this will eventually
 306 lead to the termination of the process.</li>
 307 </ul>
 308 <br class="flush">
 309 </div>
 310 <div id="foot">
 311 <hr class="hide">
 312 Copyright &copy; 2005-2011 Mike Pall
 313 <span class="noprint">
 314 &middot;
 315 <a href="contact.html">Contact</a>
 316 </span>
 317 </div>
 318 </body>
 319 </html>