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