summaryrefslogtreecommitdiff
path: root/doc/extensions.html
diff options
context:
space:
mode:
Diffstat (limited to 'doc/extensions.html')
-rw-r--r--doc/extensions.html112
1 files changed, 89 insertions, 23 deletions
diff --git a/doc/extensions.html b/doc/extensions.html
index f8b45c28..eb591d1e 100644
--- a/doc/extensions.html
+++ b/doc/extensions.html
@@ -1,8 +1,8 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> 1<!DOCTYPE html>
2<html> 2<html>
3<head> 3<head>
4<title>Extensions</title> 4<title>Extensions</title>
5<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> 5<meta charset="utf-8">
6<meta name="Copyright" content="Copyright (C) 2005-2023"> 6<meta name="Copyright" content="Copyright (C) 2005-2023">
7<meta name="Language" content="en"> 7<meta name="Language" content="en">
8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen"> 8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
@@ -54,9 +54,13 @@ td.excinterop {
54<a href="ext_ffi_semantics.html">FFI Semantics</a> 54<a href="ext_ffi_semantics.html">FFI Semantics</a>
55</li></ul> 55</li></ul>
56</li><li> 56</li><li>
57<a href="ext_buffer.html">String Buffers</a>
58</li><li>
57<a href="ext_jit.html">jit.* Library</a> 59<a href="ext_jit.html">jit.* Library</a>
58</li><li> 60</li><li>
59<a href="ext_c_api.html">Lua/C API</a> 61<a href="ext_c_api.html">Lua/C API</a>
62</li><li>
63<a href="ext_profiler.html">Profiler</a>
60</li></ul> 64</li></ul>
61</li><li> 65</li><li>
62<a href="https://luajit.org/status.html">Status <span class="ext">&raquo;</span></a> 66<a href="https://luajit.org/status.html">Status <span class="ext">&raquo;</span></a>
@@ -106,6 +110,9 @@ bit.lshift bit.rshift bit.arshift bit.rol bit.ror bit.bswap
106This module is a LuaJIT built-in &mdash; you don't need to download or 110This module is a LuaJIT built-in &mdash; you don't need to download or
107install Lua BitOp. The Lua BitOp site has full documentation for all 111install Lua BitOp. The Lua BitOp site has full documentation for all
108<a href="https://bitop.luajit.org/api.html"><span class="ext">&raquo;</span>&nbsp;Lua BitOp API functions</a>. 112<a href="https://bitop.luajit.org/api.html"><span class="ext">&raquo;</span>&nbsp;Lua BitOp API functions</a>.
113The FFI adds support for
114<a href="ext_ffi_semantics.html#cdata_arith">64&nbsp;bit bitwise operations</a>,
115using the same API functions.
109</p> 116</p>
110<p> 117<p>
111Please make sure to <tt>require</tt> the module before using any of 118Please make sure to <tt>require</tt> the module before using any of
@@ -139,6 +146,11 @@ LuaJIT adds some
139<a href="ext_c_api.html">extra functions to the Lua/C API</a>. 146<a href="ext_c_api.html">extra functions to the Lua/C API</a>.
140</p> 147</p>
141 148
149<h3 id="profiler">Profiler</h3>
150<p>
151LuaJIT has an <a href="ext_profiler.html">integrated profiler</a>.
152</p>
153
142<h2 id="library">Enhanced Standard Library Functions</h2> 154<h2 id="library">Enhanced Standard Library Functions</h2>
143 155
144<h3 id="xpcall"><tt>xpcall(f, err [,args...])</tt> passes arguments</h3> 156<h3 id="xpcall"><tt>xpcall(f, err [,args...])</tt> passes arguments</h3>
@@ -166,7 +178,7 @@ in <tt>"-inf"</tt>.
166<h3 id="tonumber"><tt>tonumber()</tt> etc. use builtin string to number conversion</h3> 178<h3 id="tonumber"><tt>tonumber()</tt> etc. use builtin string to number conversion</h3>
167<p> 179<p>
168All string-to-number conversions consistently convert integer and 180All string-to-number conversions consistently convert integer and
169floating-point inputs in decimal and hexadecimal on all platforms. 181floating-point inputs in decimal, hexadecimal and binary on all platforms.
170<tt>strtod()</tt> is <em>not</em> used anymore, which avoids numerous 182<tt>strtod()</tt> is <em>not</em> used anymore, which avoids numerous
171problems with poor C library implementations. The builtin conversion 183problems with poor C library implementations. The builtin conversion
172function provides full precision according to the IEEE-754 standard, it 184function provides full precision according to the IEEE-754 standard, it
@@ -190,6 +202,36 @@ for dot releases (x.y.0 &rarr; x.y.1), but may change with major or
190minor releases (2.0 &rarr; 2.1) or between any beta release. Foreign 202minor releases (2.0 &rarr; 2.1) or between any beta release. Foreign
191bytecode (e.g. from Lua 5.1) is incompatible and cannot be loaded. 203bytecode (e.g. from Lua 5.1) is incompatible and cannot be loaded.
192</p> 204</p>
205<p>
206Note: <tt>LJ_GC64</tt> mode requires a different frame layout, which implies
207a different, incompatible bytecode format for all 64 bit ports. This may be
208rectified in the future.
209</p>
210
211<h3 id="table_new"><tt>table.new(narray, nhash)</tt> allocates a pre-sized table</h3>
212<p>
213An extra library function <tt>table.new()</tt> can be made available via
214<tt>require("table.new")</tt>. This creates a pre-sized table, just like
215the C API equivalent <tt>lua_createtable()</tt>. This is useful for big
216tables if the final table size is known and automatic table resizing is
217too expensive.
218</p>
219
220<h3 id="table_clear"><tt>table.clear(tab)</tt> clears a table</h3>
221<p>
222An extra library function <tt>table.clear()</tt> can be made available
223via <tt>require("table.clear")</tt>. This clears all keys and values
224from a table, but preserves the allocated array/hash sizes. This is
225useful when a table, which is linked from multiple places, needs to be
226cleared and/or when recycling a table for use by the same context. This
227avoids managing backlinks, saves an allocation and the overhead of
228incremental array/hash part growth.
229</p>
230<p>
231Please note, this function is meant for very specific situations. In most
232cases it's better to replace the (usually single) link with a new table
233and let the GC do its work.
234</p>
193 235
194<h3 id="math_random">Enhanced PRNG for <tt>math.random()</tt></h3> 236<h3 id="math_random">Enhanced PRNG for <tt>math.random()</tt></h3>
195<p> 237<p>
@@ -268,6 +310,26 @@ indexes for varargs.</li>
268<li><tt>debug.getupvalue()</tt> and <tt>debug.setupvalue()</tt> handle 310<li><tt>debug.getupvalue()</tt> and <tt>debug.setupvalue()</tt> handle
269C&nbsp;functions.</li> 311C&nbsp;functions.</li>
270<li><tt>debug.upvalueid()</tt> and <tt>debug.upvaluejoin()</tt>.</li> 312<li><tt>debug.upvalueid()</tt> and <tt>debug.upvaluejoin()</tt>.</li>
313<li>Lua/C API extensions:
314<tt>lua_version()</tt>
315<tt>lua_upvalueid()</tt>
316<tt>lua_upvaluejoin()</tt>
317<tt>lua_loadx()</tt>
318<tt>lua_copy()</tt>
319<tt>lua_tonumberx()</tt>
320<tt>lua_tointegerx()</tt>
321<tt>luaL_fileresult()</tt>
322<tt>luaL_execresult()</tt>
323<tt>luaL_loadfilex()</tt>
324<tt>luaL_loadbufferx()</tt>
325<tt>luaL_traceback()</tt>
326<tt>luaL_setfuncs()</tt>
327<tt>luaL_pushmodule()</tt>
328<tt>luaL_newlibtable()</tt>
329<tt>luaL_newlib()</tt>
330<tt>luaL_testudata()</tt>
331<tt>luaL_setmetatable()</tt>
332</li>
271<li>Command line option <tt>-E</tt>.</li> 333<li>Command line option <tt>-E</tt>.</li>
272<li>Command line checks <tt>__tostring</tt> for errors.</li> 334<li>Command line checks <tt>__tostring</tt> for errors.</li>
273</ul> 335</ul>
@@ -293,6 +355,8 @@ exit status.</li>
293<li><tt>debug.setmetatable()</tt> returns object.</li> 355<li><tt>debug.setmetatable()</tt> returns object.</li>
294<li><tt>debug.getuservalue()</tt> and <tt>debug.setuservalue()</tt>.</li> 356<li><tt>debug.getuservalue()</tt> and <tt>debug.setuservalue()</tt>.</li>
295<li>Remove <tt>math.mod()</tt>, <tt>string.gfind()</tt>.</li> 357<li>Remove <tt>math.mod()</tt>, <tt>string.gfind()</tt>.</li>
358<li><tt>package.searchers</tt>.</li>
359<li><tt>module()</tt> returns the module table.</li>
296</ul> 360</ul>
297<p> 361<p>
298Note: this provides only partial compatibility with Lua 5.2 at the 362Note: this provides only partial compatibility with Lua 5.2 at the
@@ -301,6 +365,21 @@ Lua&nbsp;5.1, which prevents implementing features that would otherwise
301break the Lua/C API and ABI (e.g. <tt>_ENV</tt>). 365break the Lua/C API and ABI (e.g. <tt>_ENV</tt>).
302</p> 366</p>
303 367
368<h2 id="lua53">Extensions from Lua 5.3</h2>
369<p>
370LuaJIT supports some extensions from Lua&nbsp;5.3:
371<ul>
372<li>Unicode escape <tt>'\u{XX...}'</tt> embeds the UTF-8 encoding in string literals.</li>
373<li>The argument table <tt>arg</tt> can be read (and modified) by <tt>LUA_INIT</tt> and <tt>-e</tt> chunks.</li>
374<li><tt>io.read()</tt> and <tt>file:read()</tt> accept formats with or without a leading <tt>*</tt>.</li>
375<li><tt>assert()</tt> accepts any type of error object.</li>
376<li><tt>table.move(a1, f, e, t [,a2])</tt>.</li>
377<li><tt>coroutine.isyieldable()</tt>.</li>
378<li>Lua/C API extensions:
379<tt>lua_isyieldable()</tt>
380</li>
381</ul>
382
304<h2 id="exceptions">C++ Exception Interoperability</h2> 383<h2 id="exceptions">C++ Exception Interoperability</h2>
305<p> 384<p>
306LuaJIT has built-in support for interoperating with C++&nbsp;exceptions. 385LuaJIT has built-in support for interoperating with C++&nbsp;exceptions.
@@ -314,26 +393,21 @@ the toolchain used to compile LuaJIT:
314<td class="excinterop">Interoperability</td> 393<td class="excinterop">Interoperability</td>
315</tr> 394</tr>
316<tr class="odd separate"> 395<tr class="odd separate">
317<td class="excplatform">POSIX/x64, DWARF2 unwinding</td> 396<td class="excplatform">External frame unwinding</td>
318<td class="exccompiler">GCC 4.3+</td> 397<td class="exccompiler">GCC, Clang, MSVC</td>
319<td class="excinterop"><b style="color: #00a000;">Full</b></td> 398<td class="excinterop"><b style="color: #00a000;">Full</b></td>
320</tr> 399</tr>
321<tr class="even"> 400<tr class="even">
322<td class="excplatform">Other platforms, DWARF2 unwinding</td> 401<td class="excplatform">Internal frame unwinding + DWARF2</td>
323<td class="exccompiler">GCC</td> 402<td class="exccompiler">GCC, Clang</td>
324<td class="excinterop"><b style="color: #c06000;">Limited</b></td> 403<td class="excinterop"><b style="color: #c06000;">Limited</b></td>
325</tr> 404</tr>
326<tr class="odd"> 405<tr class="odd">
327<td class="excplatform">Windows/x64</td> 406<td class="excplatform">Windows 64 bit</td>
328<td class="exccompiler">MSVC</td> 407<td class="exccompiler">non-MSVC</td>
329<td class="excinterop"><b style="color: #00a000;">Full</b></td> 408<td class="excinterop"><b style="color: #c06000;">Limited</b></td>
330</tr> 409</tr>
331<tr class="even"> 410<tr class="even">
332<td class="excplatform">Windows/x86</td>
333<td class="exccompiler">Any</td>
334<td class="excinterop"><b style="color: #a00000;">No</b></td>
335</tr>
336<tr class="odd">
337<td class="excplatform">Other platforms</td> 411<td class="excplatform">Other platforms</td>
338<td class="exccompiler">Other compilers</td> 412<td class="exccompiler">Other compilers</td>
339<td class="excinterop"><b style="color: #a00000;">No</b></td> 413<td class="excinterop"><b style="color: #a00000;">No</b></td>
@@ -384,14 +458,6 @@ C++ destructors.</li>
384<li>Lua errors <b>cannot</b> be caught on the C++ side.</li> 458<li>Lua errors <b>cannot</b> be caught on the C++ side.</li>
385<li>Throwing Lua errors across C++ frames will <b>not</b> call 459<li>Throwing Lua errors across C++ frames will <b>not</b> call
386C++ destructors.</li> 460C++ destructors.</li>
387<li>Additionally, on Windows/x86 with SEH-based C++&nbsp;exceptions:
388it's <b>not</b> safe to throw a Lua error across any frames containing
389a C++ function with any try/catch construct or using variables with
390(implicit) destructors. This also applies to any functions which may be
391inlined in such a function. It doesn't matter whether <tt>lua_error()</tt>
392is called inside or outside of a try/catch or whether any object actually
393needs to be destroyed: the SEH chain is corrupted and this will eventually
394lead to the termination of the process.</li>
395</ul> 461</ul>
396<br class="flush"> 462<br class="flush">
397</div> 463</div>