diff options
Diffstat (limited to 'doc/extensions.html')
-rw-r--r-- | doc/extensions.html | 112 |
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">»</span></a> | 66 | <a href="https://luajit.org/status.html">Status <span class="ext">»</span></a> |
@@ -106,6 +110,9 @@ bit.lshift bit.rshift bit.arshift bit.rol bit.ror bit.bswap | |||
106 | This module is a LuaJIT built-in — you don't need to download or | 110 | This module is a LuaJIT built-in — you don't need to download or |
107 | install Lua BitOp. The Lua BitOp site has full documentation for all | 111 | install Lua BitOp. The Lua BitOp site has full documentation for all |
108 | <a href="https://bitop.luajit.org/api.html"><span class="ext">»</span> Lua BitOp API functions</a>. | 112 | <a href="https://bitop.luajit.org/api.html"><span class="ext">»</span> Lua BitOp API functions</a>. |
113 | The FFI adds support for | ||
114 | <a href="ext_ffi_semantics.html#cdata_arith">64 bit bitwise operations</a>, | ||
115 | using the same API functions. | ||
109 | </p> | 116 | </p> |
110 | <p> | 117 | <p> |
111 | Please make sure to <tt>require</tt> the module before using any of | 118 | Please 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> | ||
151 | LuaJIT 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> |
168 | All string-to-number conversions consistently convert integer and | 180 | All string-to-number conversions consistently convert integer and |
169 | floating-point inputs in decimal and hexadecimal on all platforms. | 181 | floating-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 |
171 | problems with poor C library implementations. The builtin conversion | 183 | problems with poor C library implementations. The builtin conversion |
172 | function provides full precision according to the IEEE-754 standard, it | 184 | function provides full precision according to the IEEE-754 standard, it |
@@ -190,6 +202,36 @@ for dot releases (x.y.0 → x.y.1), but may change with major or | |||
190 | minor releases (2.0 → 2.1) or between any beta release. Foreign | 202 | minor releases (2.0 → 2.1) or between any beta release. Foreign |
191 | bytecode (e.g. from Lua 5.1) is incompatible and cannot be loaded. | 203 | bytecode (e.g. from Lua 5.1) is incompatible and cannot be loaded. |
192 | </p> | 204 | </p> |
205 | <p> | ||
206 | Note: <tt>LJ_GC64</tt> mode requires a different frame layout, which implies | ||
207 | a different, incompatible bytecode format for all 64 bit ports. This may be | ||
208 | rectified 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> | ||
213 | An 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 | ||
215 | the C API equivalent <tt>lua_createtable()</tt>. This is useful for big | ||
216 | tables if the final table size is known and automatic table resizing is | ||
217 | too expensive. | ||
218 | </p> | ||
219 | |||
220 | <h3 id="table_clear"><tt>table.clear(tab)</tt> clears a table</h3> | ||
221 | <p> | ||
222 | An extra library function <tt>table.clear()</tt> can be made available | ||
223 | via <tt>require("table.clear")</tt>. This clears all keys and values | ||
224 | from a table, but preserves the allocated array/hash sizes. This is | ||
225 | useful when a table, which is linked from multiple places, needs to be | ||
226 | cleared and/or when recycling a table for use by the same context. This | ||
227 | avoids managing backlinks, saves an allocation and the overhead of | ||
228 | incremental array/hash part growth. | ||
229 | </p> | ||
230 | <p> | ||
231 | Please note, this function is meant for very specific situations. In most | ||
232 | cases it's better to replace the (usually single) link with a new table | ||
233 | and 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 |
269 | C functions.</li> | 311 | C 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> |
298 | Note: this provides only partial compatibility with Lua 5.2 at the | 362 | Note: this provides only partial compatibility with Lua 5.2 at the |
@@ -301,6 +365,21 @@ Lua 5.1, which prevents implementing features that would otherwise | |||
301 | break the Lua/C API and ABI (e.g. <tt>_ENV</tt>). | 365 | break 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> | ||
370 | LuaJIT supports some extensions from Lua 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> |
306 | LuaJIT has built-in support for interoperating with C++ exceptions. | 385 | LuaJIT has built-in support for interoperating with C++ 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 |
386 | C++ destructors.</li> | 460 | C++ destructors.</li> |
387 | <li>Additionally, on Windows/x86 with SEH-based C++ exceptions: | ||
388 | it's <b>not</b> safe to throw a Lua error across any frames containing | ||
389 | a C++ function with any try/catch construct or using variables with | ||
390 | (implicit) destructors. This also applies to any functions which may be | ||
391 | inlined in such a function. It doesn't matter whether <tt>lua_error()</tt> | ||
392 | is called inside or outside of a try/catch or whether any object actually | ||
393 | needs to be destroyed: the SEH chain is corrupted and this will eventually | ||
394 | lead to the termination of the process.</li> | ||
395 | </ul> | 461 | </ul> |
396 | <br class="flush"> | 462 | <br class="flush"> |
397 | </div> | 463 | </div> |