diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/contact.html | 8 | ||||
| -rw-r--r-- | doc/ext_buffer.html | 689 | ||||
| -rw-r--r-- | doc/ext_c_api.html | 8 | ||||
| -rw-r--r-- | doc/ext_ffi.html | 8 | ||||
| -rw-r--r-- | doc/ext_ffi_api.html | 20 | ||||
| -rw-r--r-- | doc/ext_ffi_semantics.html | 104 | ||||
| -rw-r--r-- | doc/ext_ffi_tutorial.html | 8 | ||||
| -rw-r--r-- | doc/ext_jit.html | 10 | ||||
| -rw-r--r-- | doc/ext_profiler.html | 359 | ||||
| -rw-r--r-- | doc/extensions.html | 169 | ||||
| -rw-r--r-- | doc/install.html | 190 | ||||
| -rw-r--r-- | doc/luajit.html | 14 | ||||
| -rw-r--r-- | doc/running.html | 28 |
13 files changed, 1474 insertions, 141 deletions
diff --git a/doc/contact.html b/doc/contact.html index 6c733a4a..d5bbb75d 100644 --- a/doc/contact.html +++ b/doc/contact.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>Contact</title> | 4 | <title>Contact</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-2026"> | 6 | <meta name="Copyright" content="Copyright (C) 2005-2026"> |
| 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"> |
| @@ -37,9 +37,13 @@ | |||
| 37 | <a href="ext_ffi_semantics.html">FFI Semantics</a> | 37 | <a href="ext_ffi_semantics.html">FFI Semantics</a> |
| 38 | </li></ul> | 38 | </li></ul> |
| 39 | </li><li> | 39 | </li><li> |
| 40 | <a href="ext_buffer.html">String Buffers</a> | ||
| 41 | </li><li> | ||
| 40 | <a href="ext_jit.html">jit.* Library</a> | 42 | <a href="ext_jit.html">jit.* Library</a> |
| 41 | </li><li> | 43 | </li><li> |
| 42 | <a href="ext_c_api.html">Lua/C API</a> | 44 | <a href="ext_c_api.html">Lua/C API</a> |
| 45 | </li><li> | ||
| 46 | <a href="ext_profiler.html">Profiler</a> | ||
| 43 | </li></ul> | 47 | </li></ul> |
| 44 | </li><li> | 48 | </li><li> |
| 45 | <a href="https://luajit.org/status.html">Status <span class="ext">»</span></a> | 49 | <a href="https://luajit.org/status.html">Status <span class="ext">»</span></a> |
diff --git a/doc/ext_buffer.html b/doc/ext_buffer.html new file mode 100644 index 00000000..4680f2cc --- /dev/null +++ b/doc/ext_buffer.html | |||
| @@ -0,0 +1,689 @@ | |||
| 1 | <!DOCTYPE html> | ||
| 2 | <html> | ||
| 3 | <head> | ||
| 4 | <title>String Buffer Library</title> | ||
| 5 | <meta charset="utf-8"> | ||
| 6 | <meta name="Copyright" content="Copyright (C) 2005-2026"> | ||
| 7 | <meta name="Language" content="en"> | ||
| 8 | <link rel="stylesheet" type="text/css" href="bluequad.css" media="screen"> | ||
| 9 | <link rel="stylesheet" type="text/css" href="bluequad-print.css" media="print"> | ||
| 10 | <style type="text/css"> | ||
| 11 | .lib { | ||
| 12 | vertical-align: middle; | ||
| 13 | margin-left: 5px; | ||
| 14 | padding: 0 5px; | ||
| 15 | font-size: 60%; | ||
| 16 | border-radius: 5px; | ||
| 17 | background: #c5d5ff; | ||
| 18 | color: #000; | ||
| 19 | } | ||
| 20 | </style> | ||
| 21 | </head> | ||
| 22 | <body> | ||
| 23 | <div id="site"> | ||
| 24 | <a href="https://luajit.org"><span>Lua<span id="logo">JIT</span></span></a> | ||
| 25 | </div> | ||
| 26 | <div id="head"> | ||
| 27 | <h1>String Buffer Library</h1> | ||
| 28 | </div> | ||
| 29 | <div id="nav"> | ||
| 30 | <ul><li> | ||
| 31 | <a href="luajit.html">LuaJIT</a> | ||
| 32 | <ul><li> | ||
| 33 | <a href="https://luajit.org/download.html">Download <span class="ext">»</span></a> | ||
| 34 | </li><li> | ||
| 35 | <a href="install.html">Installation</a> | ||
| 36 | </li><li> | ||
| 37 | <a href="running.html">Running</a> | ||
| 38 | </li></ul> | ||
| 39 | </li><li> | ||
| 40 | <a href="extensions.html">Extensions</a> | ||
| 41 | <ul><li> | ||
| 42 | <a href="ext_ffi.html">FFI Library</a> | ||
| 43 | <ul><li> | ||
| 44 | <a href="ext_ffi_tutorial.html">FFI Tutorial</a> | ||
| 45 | </li><li> | ||
| 46 | <a href="ext_ffi_api.html">ffi.* API</a> | ||
| 47 | </li><li> | ||
| 48 | <a href="ext_ffi_semantics.html">FFI Semantics</a> | ||
| 49 | </li></ul> | ||
| 50 | </li><li> | ||
| 51 | <a class="current" href="ext_buffer.html">String Buffers</a> | ||
| 52 | </li><li> | ||
| 53 | <a href="ext_jit.html">jit.* Library</a> | ||
| 54 | </li><li> | ||
| 55 | <a href="ext_c_api.html">Lua/C API</a> | ||
| 56 | </li><li> | ||
| 57 | <a href="ext_profiler.html">Profiler</a> | ||
| 58 | </li></ul> | ||
| 59 | </li><li> | ||
| 60 | <a href="https://luajit.org/status.html">Status <span class="ext">»</span></a> | ||
| 61 | </li><li> | ||
| 62 | <a href="https://luajit.org/faq.html">FAQ <span class="ext">»</span></a> | ||
| 63 | </li><li> | ||
| 64 | <a href="https://luajit.org/list.html">Mailing List <span class="ext">»</span></a> | ||
| 65 | </li></ul> | ||
| 66 | </div> | ||
| 67 | <div id="main"> | ||
| 68 | <p> | ||
| 69 | The string buffer library allows <b>high-performance manipulation of | ||
| 70 | string-like data</b>. | ||
| 71 | </p> | ||
| 72 | <p> | ||
| 73 | Unlike Lua strings, which are constants, string buffers are | ||
| 74 | <b>mutable</b> sequences of 8-bit (binary-transparent) characters. Data | ||
| 75 | can be stored, formatted and encoded into a string buffer and later | ||
| 76 | converted, extracted or decoded. | ||
| 77 | </p> | ||
| 78 | <p> | ||
| 79 | The convenient string buffer API simplifies common string manipulation | ||
| 80 | tasks, that would otherwise require creating many intermediate strings. | ||
| 81 | String buffers improve performance by eliminating redundant memory | ||
| 82 | copies, object creation, string interning and garbage collection | ||
| 83 | overhead. In conjunction with the FFI library, they allow zero-copy | ||
| 84 | operations. | ||
| 85 | </p> | ||
| 86 | <p> | ||
| 87 | The string buffer library also includes a high-performance | ||
| 88 | <a href="#serialize">serializer</a> for Lua objects. | ||
| 89 | </p> | ||
| 90 | |||
| 91 | <h2 id="use">Using the String Buffer Library</h2> | ||
| 92 | <p> | ||
| 93 | The string buffer library is built into LuaJIT by default, but it's not | ||
| 94 | loaded by default. Add this to the start of every Lua file that needs | ||
| 95 | one of its functions: | ||
| 96 | </p> | ||
| 97 | <pre class="code"> | ||
| 98 | local buffer = require("string.buffer") | ||
| 99 | </pre> | ||
| 100 | <p> | ||
| 101 | The convention for the syntax shown on this page is that <tt>buffer</tt> | ||
| 102 | refers to the buffer library and <tt>buf</tt> refers to an individual | ||
| 103 | buffer object. | ||
| 104 | </p> | ||
| 105 | <p> | ||
| 106 | Please note the difference between a Lua function call, e.g. | ||
| 107 | <tt>buffer.new()</tt> (with a dot) and a Lua method call, e.g. | ||
| 108 | <tt>buf:reset()</tt> (with a colon). | ||
| 109 | </p> | ||
| 110 | |||
| 111 | <h3 id="buffer_object">Buffer Objects</h3> | ||
| 112 | <p> | ||
| 113 | A buffer object is a garbage-collected Lua object. After creation with | ||
| 114 | <tt>buffer.new()</tt>, it can (and should) be reused for many operations. | ||
| 115 | When the last reference to a buffer object is gone, it will eventually | ||
| 116 | be freed by the garbage collector, along with the allocated buffer | ||
| 117 | space. | ||
| 118 | </p> | ||
| 119 | <p> | ||
| 120 | Buffers operate like a FIFO (first-in first-out) data structure. Data | ||
| 121 | can be appended (written) to the end of the buffer and consumed (read) | ||
| 122 | from the front of the buffer. These operations may be freely mixed. | ||
| 123 | </p> | ||
| 124 | <p> | ||
| 125 | The buffer space that holds the characters is managed automatically | ||
| 126 | — it grows as needed and already consumed space is recycled. Use | ||
| 127 | <tt>buffer.new(size)</tt> and <tt>buf:free()</tt>, if you need more | ||
| 128 | control. | ||
| 129 | </p> | ||
| 130 | <p> | ||
| 131 | The maximum size of a single buffer is the same as the maximum size of a | ||
| 132 | Lua string, which is slightly below two gigabytes. For huge data sizes, | ||
| 133 | neither strings nor buffers are the right data structure — use the | ||
| 134 | FFI library to directly map memory or files up to the virtual memory | ||
| 135 | limit of your OS. | ||
| 136 | </p> | ||
| 137 | |||
| 138 | <h3 id="buffer_overview">Buffer Method Overview</h3> | ||
| 139 | <ul> | ||
| 140 | <li> | ||
| 141 | The <tt>buf:put*()</tt>-like methods append (write) characters to the | ||
| 142 | end of the buffer. | ||
| 143 | </li> | ||
| 144 | <li> | ||
| 145 | The <tt>buf:get*()</tt>-like methods consume (read) characters from the | ||
| 146 | front of the buffer. | ||
| 147 | </li> | ||
| 148 | <li> | ||
| 149 | Other methods, like <tt>buf:tostring()</tt> only read the buffer | ||
| 150 | contents, but don't change the buffer. | ||
| 151 | </li> | ||
| 152 | <li> | ||
| 153 | The <tt>buf:set()</tt> method allows zero-copy consumption of a string | ||
| 154 | or an FFI cdata object as a buffer. | ||
| 155 | </li> | ||
| 156 | <li> | ||
| 157 | The FFI-specific methods allow zero-copy read/write-style operations or | ||
| 158 | modifying the buffer contents in-place. Please check the | ||
| 159 | <a href="#ffi_caveats">FFI caveats</a> below, too. | ||
| 160 | </li> | ||
| 161 | <li> | ||
| 162 | Methods that don't need to return anything specific, return the buffer | ||
| 163 | object itself as a convenience. This allows method chaining, e.g.: | ||
| 164 | <tt>buf:reset():encode(obj)</tt> or <tt>buf:skip(len):get()</tt> | ||
| 165 | </li> | ||
| 166 | </ul> | ||
| 167 | |||
| 168 | <h2 id="create">Buffer Creation and Management</h2> | ||
| 169 | |||
| 170 | <h3 id="buffer_new"><tt>local buf = buffer.new([size [,options]])<br> | ||
| 171 | local buf = buffer.new([options])</tt></h3> | ||
| 172 | <p> | ||
| 173 | Creates a new buffer object. | ||
| 174 | </p> | ||
| 175 | <p> | ||
| 176 | The optional <tt>size</tt> argument ensures a minimum initial buffer | ||
| 177 | size. This is strictly an optimization when the required buffer size is | ||
| 178 | known beforehand. The buffer space will grow as needed, in any case. | ||
| 179 | </p> | ||
| 180 | <p> | ||
| 181 | The optional table <tt>options</tt> sets various | ||
| 182 | <a href="#serialize_options">serialization options</a>. | ||
| 183 | </p> | ||
| 184 | |||
| 185 | <h3 id="buffer_reset"><tt>buf = buf:reset()</tt></h3> | ||
| 186 | <p> | ||
| 187 | Reset (empty) the buffer. The allocated buffer space is not freed and | ||
| 188 | may be reused. | ||
| 189 | </p> | ||
| 190 | |||
| 191 | <h3 id="buffer_free"><tt>buf = buf:free()</tt></h3> | ||
| 192 | <p> | ||
| 193 | The buffer space of the buffer object is freed. The object itself | ||
| 194 | remains intact, empty and may be reused. | ||
| 195 | </p> | ||
| 196 | <p> | ||
| 197 | Note: you normally don't need to use this method. The garbage collector | ||
| 198 | automatically frees the buffer space, when the buffer object is | ||
| 199 | collected. Use this method, if you need to free the associated memory | ||
| 200 | immediately. | ||
| 201 | </p> | ||
| 202 | |||
| 203 | <h2 id="write">Buffer Writers</h2> | ||
| 204 | |||
| 205 | <h3 id="buffer_put"><tt>buf = buf:put([str|num|obj] [,…])</tt></h3> | ||
| 206 | <p> | ||
| 207 | Appends a string <tt>str</tt>, a number <tt>num</tt> or any object | ||
| 208 | <tt>obj</tt> with a <tt>__tostring</tt> metamethod to the buffer. | ||
| 209 | Multiple arguments are appended in the given order. | ||
| 210 | </p> | ||
| 211 | <p> | ||
| 212 | Appending a buffer to a buffer is possible and short-circuited | ||
| 213 | internally. But it still involves a copy. Better combine the buffer | ||
| 214 | writes to use a single buffer. | ||
| 215 | </p> | ||
| 216 | |||
| 217 | <h3 id="buffer_putf"><tt>buf = buf:putf(format, …)</tt></h3> | ||
| 218 | <p> | ||
| 219 | Appends the formatted arguments to the buffer. The <tt>format</tt> | ||
| 220 | string supports the same options as <tt>string.format()</tt>. | ||
| 221 | </p> | ||
| 222 | |||
| 223 | <h3 id="buffer_putcdata"><tt>buf = buf:putcdata(cdata, len)</tt><span class="lib">FFI</span></h3> | ||
| 224 | <p> | ||
| 225 | Appends the given <tt>len</tt> number of bytes from the memory pointed | ||
| 226 | to by the FFI <tt>cdata</tt> object to the buffer. The object needs to | ||
| 227 | be convertible to a (constant) pointer. | ||
| 228 | </p> | ||
| 229 | |||
| 230 | <h3 id="buffer_set"><tt>buf = buf:set(str)<br> | ||
| 231 | buf = buf:set(cdata, len)</tt><span class="lib">FFI</span></h3> | ||
| 232 | <p> | ||
| 233 | This method allows zero-copy consumption of a string or an FFI cdata | ||
| 234 | object as a buffer. It stores a reference to the passed string | ||
| 235 | <tt>str</tt> or the FFI <tt>cdata</tt> object in the buffer. Any buffer | ||
| 236 | space originally allocated is freed. This is <i>not</i> an append | ||
| 237 | operation, unlike the <tt>buf:put*()</tt> methods. | ||
| 238 | </p> | ||
| 239 | <p> | ||
| 240 | After calling this method, the buffer behaves as if | ||
| 241 | <tt>buf:free():put(str)</tt> or <tt>buf:free():put(cdata, len)</tt> | ||
| 242 | had been called. However, the data is only referenced and not copied, as | ||
| 243 | long as the buffer is only consumed. | ||
| 244 | </p> | ||
| 245 | <p> | ||
| 246 | In case the buffer is written to later on, the referenced data is copied | ||
| 247 | and the object reference is removed (copy-on-write semantics). | ||
| 248 | </p> | ||
| 249 | <p> | ||
| 250 | The stored reference is an anchor for the garbage collector and keeps the | ||
| 251 | originally passed string or FFI cdata object alive. | ||
| 252 | </p> | ||
| 253 | |||
| 254 | <h3 id="buffer_reserve"><tt>ptr, len = buf:reserve(size)</tt><span class="lib">FFI</span><br> | ||
| 255 | <tt>buf = buf:commit(used)</tt><span class="lib">FFI</span></h3> | ||
| 256 | <p> | ||
| 257 | The <tt>reserve</tt> method reserves at least <tt>size</tt> bytes of | ||
| 258 | write space in the buffer. It returns an <tt>uint8_t *</tt> FFI | ||
| 259 | cdata pointer <tt>ptr</tt> that points to this space. | ||
| 260 | </p> | ||
| 261 | <p> | ||
| 262 | The available length in bytes is returned in <tt>len</tt>. This is at | ||
| 263 | least <tt>size</tt> bytes, but may be more to facilitate efficient | ||
| 264 | buffer growth. You can either make use of the additional space or ignore | ||
| 265 | <tt>len</tt> and only use <tt>size</tt> bytes. | ||
| 266 | </p> | ||
| 267 | <p> | ||
| 268 | The <tt>commit</tt> method appends the <tt>used</tt> bytes of the | ||
| 269 | previously returned write space to the buffer data. | ||
| 270 | </p> | ||
| 271 | <p> | ||
| 272 | This pair of methods allows zero-copy use of C read-style APIs: | ||
| 273 | </p> | ||
| 274 | <pre class="code"> | ||
| 275 | local MIN_SIZE = 65536 | ||
| 276 | repeat | ||
| 277 | local ptr, len = buf:reserve(MIN_SIZE) | ||
| 278 | local n = C.read(fd, ptr, len) | ||
| 279 | if n == 0 then break end -- EOF. | ||
| 280 | if n < 0 then error("read error") end | ||
| 281 | buf:commit(n) | ||
| 282 | until false | ||
| 283 | </pre> | ||
| 284 | <p> | ||
| 285 | The reserved write space is <i>not</i> initialized. At least the | ||
| 286 | <tt>used</tt> bytes <b>must</b> be written to before calling the | ||
| 287 | <tt>commit</tt> method. There's no need to call the <tt>commit</tt> | ||
| 288 | method, if nothing is added to the buffer (e.g. on error). | ||
| 289 | </p> | ||
| 290 | |||
| 291 | <h2 id="read">Buffer Readers</h2> | ||
| 292 | |||
| 293 | <h3 id="buffer_length"><tt>len = #buf</tt></h3> | ||
| 294 | <p> | ||
| 295 | Returns the current length of the buffer data in bytes. | ||
| 296 | </p> | ||
| 297 | |||
| 298 | <h3 id="buffer_concat"><tt>res = str|num|buf .. str|num|buf […]</tt></h3> | ||
| 299 | <p> | ||
| 300 | The Lua concatenation operator <tt>..</tt> also accepts buffers, just | ||
| 301 | like strings or numbers. It always returns a string and not a buffer. | ||
| 302 | </p> | ||
| 303 | <p> | ||
| 304 | Note that although this is supported for convenience, this thwarts one | ||
| 305 | of the main reasons to use buffers, which is to avoid string | ||
| 306 | allocations. Rewrite it with <tt>buf:put()</tt> and <tt>buf:get()</tt>. | ||
| 307 | </p> | ||
| 308 | <p> | ||
| 309 | Mixing this with unrelated objects that have a <tt>__concat</tt> | ||
| 310 | metamethod may not work, since these probably only expect strings. | ||
| 311 | </p> | ||
| 312 | |||
| 313 | <h3 id="buffer_skip"><tt>buf = buf:skip(len)</tt></h3> | ||
| 314 | <p> | ||
| 315 | Skips (consumes) <tt>len</tt> bytes from the buffer up to the current | ||
| 316 | length of the buffer data. | ||
| 317 | </p> | ||
| 318 | |||
| 319 | <h3 id="buffer_get"><tt>str, … = buf:get([len|nil] [,…])</tt></h3> | ||
| 320 | <p> | ||
| 321 | Consumes the buffer data and returns one or more strings. If called | ||
| 322 | without arguments, the whole buffer data is consumed. If called with a | ||
| 323 | number, up to <tt>len</tt> bytes are consumed. A <tt>nil</tt> argument | ||
| 324 | consumes the remaining buffer space (this only makes sense as the last | ||
| 325 | argument). Multiple arguments consume the buffer data in the given | ||
| 326 | order. | ||
| 327 | </p> | ||
| 328 | <p> | ||
| 329 | Note: a zero length or no remaining buffer data returns an empty string | ||
| 330 | and not <tt>nil</tt>. | ||
| 331 | </p> | ||
| 332 | |||
| 333 | <h3 id="buffer_tostring"><tt>str = buf:tostring()<br> | ||
| 334 | str = tostring(buf)</tt></h3> | ||
| 335 | <p> | ||
| 336 | Creates a string from the buffer data, but doesn't consume it. The | ||
| 337 | buffer remains unchanged. | ||
| 338 | </p> | ||
| 339 | <p> | ||
| 340 | Buffer objects also define a <tt>__tostring</tt> metamethod. This means | ||
| 341 | buffers can be passed to the global <tt>tostring()</tt> function and | ||
| 342 | many other functions that accept this in place of strings. The important | ||
| 343 | internal uses in functions like <tt>io.write()</tt> are short-circuited | ||
| 344 | to avoid the creation of an intermediate string object. | ||
| 345 | </p> | ||
| 346 | |||
| 347 | <h3 id="buffer_ref"><tt>ptr, len = buf:ref()</tt><span class="lib">FFI</span></h3> | ||
| 348 | <p> | ||
| 349 | Returns an <tt>uint8_t *</tt> FFI cdata pointer <tt>ptr</tt> that | ||
| 350 | points to the buffer data. The length of the buffer data in bytes is | ||
| 351 | returned in <tt>len</tt>. | ||
| 352 | </p> | ||
| 353 | <p> | ||
| 354 | The returned pointer can be directly passed to C functions that expect a | ||
| 355 | buffer and a length. You can also do bytewise reads | ||
| 356 | (<tt>local x = ptr[i]</tt>) or writes | ||
| 357 | (<tt>ptr[i] = 0x40</tt>) of the buffer data. | ||
| 358 | </p> | ||
| 359 | <p> | ||
| 360 | In conjunction with the <tt>skip</tt> method, this allows zero-copy use | ||
| 361 | of C write-style APIs: | ||
| 362 | </p> | ||
| 363 | <pre class="code"> | ||
| 364 | repeat | ||
| 365 | local ptr, len = buf:ref() | ||
| 366 | if len == 0 then break end | ||
| 367 | local n = C.write(fd, ptr, len) | ||
| 368 | if n < 0 then error("write error") end | ||
| 369 | buf:skip(n) | ||
| 370 | until n >= len | ||
| 371 | </pre> | ||
| 372 | <p> | ||
| 373 | Unlike Lua strings, buffer data is <i>not</i> implicitly | ||
| 374 | zero-terminated. It's not safe to pass <tt>ptr</tt> to C functions that | ||
| 375 | expect zero-terminated strings. If you're not using <tt>len</tt>, then | ||
| 376 | you're doing something wrong. | ||
| 377 | </p> | ||
| 378 | |||
| 379 | <h2 id="serialize">Serialization of Lua Objects</h2> | ||
| 380 | <p> | ||
| 381 | The following functions and methods allow <b>high-speed serialization</b> | ||
| 382 | (encoding) of a Lua object into a string and decoding it back to a Lua | ||
| 383 | object. This allows convenient storage and transport of <b>structured | ||
| 384 | data</b>. | ||
| 385 | </p> | ||
| 386 | <p> | ||
| 387 | The encoded data is in an <a href="#serialize_format">internal binary | ||
| 388 | format</a>. The data can be stored in files, binary-transparent | ||
| 389 | databases or transmitted to other LuaJIT instances across threads, | ||
| 390 | processes or networks. | ||
| 391 | </p> | ||
| 392 | <p> | ||
| 393 | Encoding speed can reach up to 1 Gigabyte/second on a modern desktop- or | ||
| 394 | server-class system, even when serializing many small objects. Decoding | ||
| 395 | speed is mostly constrained by object creation cost. | ||
| 396 | </p> | ||
| 397 | <p> | ||
| 398 | The serializer handles most Lua types, common FFI number types and | ||
| 399 | nested structures. Functions, thread objects, other FFI cdata and full | ||
| 400 | userdata cannot be serialized (yet). | ||
| 401 | </p> | ||
| 402 | <p> | ||
| 403 | The encoder serializes nested structures as trees. Multiple references | ||
| 404 | to a single object will be stored separately and create distinct objects | ||
| 405 | after decoding. Circular references cause an error. | ||
| 406 | </p> | ||
| 407 | |||
| 408 | <h3 id="serialize_methods">Serialization Functions and Methods</h3> | ||
| 409 | |||
| 410 | <h3 id="buffer_encode"><tt>str = buffer.encode(obj)<br> | ||
| 411 | buf = buf:encode(obj)</tt></h3> | ||
| 412 | <p> | ||
| 413 | Serializes (encodes) the Lua object <tt>obj</tt>. The stand-alone | ||
| 414 | function returns a string <tt>str</tt>. The buffer method appends the | ||
| 415 | encoding to the buffer. | ||
| 416 | </p> | ||
| 417 | <p> | ||
| 418 | <tt>obj</tt> can be any of the supported Lua types — it doesn't | ||
| 419 | need to be a Lua table. | ||
| 420 | </p> | ||
| 421 | <p> | ||
| 422 | This function may throw an error when attempting to serialize | ||
| 423 | unsupported object types, circular references or deeply nested tables. | ||
| 424 | </p> | ||
| 425 | |||
| 426 | <h3 id="buffer_decode"><tt>obj = buffer.decode(str)<br> | ||
| 427 | obj = buf:decode()</tt></h3> | ||
| 428 | <p> | ||
| 429 | The stand-alone function deserializes (decodes) the string | ||
| 430 | <tt>str</tt>, the buffer method deserializes one object from the | ||
| 431 | buffer. Both return a Lua object <tt>obj</tt>. | ||
| 432 | </p> | ||
| 433 | <p> | ||
| 434 | The returned object may be any of the supported Lua types — | ||
| 435 | even <tt>nil</tt>. | ||
| 436 | </p> | ||
| 437 | <p> | ||
| 438 | This function may throw an error when fed with malformed or incomplete | ||
| 439 | encoded data. The stand-alone function throws when there's left-over | ||
| 440 | data after decoding a single top-level object. The buffer method leaves | ||
| 441 | any left-over data in the buffer. | ||
| 442 | </p> | ||
| 443 | <p> | ||
| 444 | Attempting to deserialize an FFI type will throw an error, if the FFI | ||
| 445 | library is not built-in or has not been loaded, yet. | ||
| 446 | </p> | ||
| 447 | |||
| 448 | <h3 id="serialize_options">Serialization Options</h3> | ||
| 449 | <p> | ||
| 450 | The <tt>options</tt> table passed to <tt>buffer.new()</tt> may contain | ||
| 451 | the following members (all optional): | ||
| 452 | </p> | ||
| 453 | <ul> | ||
| 454 | <li> | ||
| 455 | <tt>dict</tt> is a Lua table holding a <b>dictionary of strings</b> that | ||
| 456 | commonly occur as table keys of objects you are serializing. These keys | ||
| 457 | are compactly encoded as indexes during serialization. A well-chosen | ||
| 458 | dictionary saves space and improves serialization performance. | ||
| 459 | </li> | ||
| 460 | <li> | ||
| 461 | <tt>metatable</tt> is a Lua table holding a <b>dictionary of metatables</b> | ||
| 462 | for the table objects you are serializing. | ||
| 463 | </li> | ||
| 464 | </ul> | ||
| 465 | <p> | ||
| 466 | <tt>dict</tt> needs to be an array of strings and <tt>metatable</tt> needs | ||
| 467 | to be an array of tables. Both starting at index 1 and without holes (no | ||
| 468 | <tt>nil</tt> in between). The tables are anchored in the buffer object and | ||
| 469 | internally modified into a two-way index (don't do this yourself, just pass | ||
| 470 | a plain array). The tables must not be modified after they have been passed | ||
| 471 | to <tt>buffer.new()</tt>. | ||
| 472 | </p> | ||
| 473 | <p> | ||
| 474 | The <tt>dict</tt> and <tt>metatable</tt> tables used by the encoder and | ||
| 475 | decoder must be the same. Put the most common entries at the front. Extend | ||
| 476 | at the end to ensure backwards-compatibility — older encodings can | ||
| 477 | then still be read. You may also set some indexes to <tt>false</tt> to | ||
| 478 | explicitly drop backwards-compatibility. Old encodings that use these | ||
| 479 | indexes will throw an error when decoded. | ||
| 480 | </p> | ||
| 481 | <p> | ||
| 482 | Metatables that are not found in the <tt>metatable</tt> dictionary are | ||
| 483 | ignored when encoding. Decoding returns a table with a <tt>nil</tt> | ||
| 484 | metatable. | ||
| 485 | </p> | ||
| 486 | <p> | ||
| 487 | Note: parsing and preparation of the options table is somewhat | ||
| 488 | expensive. Create a buffer object only once and recycle it for multiple | ||
| 489 | uses. Avoid mixing encoder and decoder buffers, since the | ||
| 490 | <tt>buf:set()</tt> method frees the already allocated buffer space: | ||
| 491 | </p> | ||
| 492 | <pre class="code"> | ||
| 493 | local options = { | ||
| 494 | dict = { "commonly", "used", "string", "keys" }, | ||
| 495 | } | ||
| 496 | local buf_enc = buffer.new(options) | ||
| 497 | local buf_dec = buffer.new(options) | ||
| 498 | |||
| 499 | local function encode(obj) | ||
| 500 | return buf_enc:reset():encode(obj):get() | ||
| 501 | end | ||
| 502 | |||
| 503 | local function decode(str) | ||
| 504 | return buf_dec:set(str):decode() | ||
| 505 | end | ||
| 506 | </pre> | ||
| 507 | |||
| 508 | <h3 id="serialize_stream">Streaming Serialization</h3> | ||
| 509 | <p> | ||
| 510 | In some contexts, it's desirable to do piecewise serialization of large | ||
| 511 | datasets, also known as <i>streaming</i>. | ||
| 512 | </p> | ||
| 513 | <p> | ||
| 514 | This serialization format can be safely concatenated and supports streaming. | ||
| 515 | Multiple encodings can simply be appended to a buffer and later decoded | ||
| 516 | individually: | ||
| 517 | </p> | ||
| 518 | <pre class="code"> | ||
| 519 | local buf = buffer.new() | ||
| 520 | buf:encode(obj1) | ||
| 521 | buf:encode(obj2) | ||
| 522 | local copy1 = buf:decode() | ||
| 523 | local copy2 = buf:decode() | ||
| 524 | </pre> | ||
| 525 | <p> | ||
| 526 | Here's how to iterate over a stream: | ||
| 527 | </p> | ||
| 528 | <pre class="code"> | ||
| 529 | while #buf ~= 0 do | ||
| 530 | local obj = buf:decode() | ||
| 531 | -- Do something with obj. | ||
| 532 | end | ||
| 533 | </pre> | ||
| 534 | <p> | ||
| 535 | Since the serialization format doesn't prepend a length to its encoding, | ||
| 536 | network applications may need to transmit the length, too. | ||
| 537 | </p> | ||
| 538 | |||
| 539 | <h3 id="serialize_format">Serialization Format Specification</h3> | ||
| 540 | <p> | ||
| 541 | This serialization format is designed for <b>internal use</b> by LuaJIT | ||
| 542 | applications. Serialized data is upwards-compatible and portable across | ||
| 543 | all supported LuaJIT platforms. | ||
| 544 | </p> | ||
| 545 | <p> | ||
| 546 | It's an <b>8-bit binary format</b> and not human-readable. It uses e.g. | ||
| 547 | embedded zeroes and stores embedded Lua string objects unmodified, which | ||
| 548 | are 8-bit-clean, too. Encoded data can be safely concatenated for | ||
| 549 | streaming and later decoded one top-level object at a time. | ||
| 550 | </p> | ||
| 551 | <p> | ||
| 552 | The encoding is reasonably compact, but tuned for maximum performance, | ||
| 553 | not for minimum space usage. It compresses well with any of the common | ||
| 554 | byte-oriented data compression algorithms. | ||
| 555 | </p> | ||
| 556 | <p> | ||
| 557 | Although documented here for reference, this format is explicitly | ||
| 558 | <b>not</b> intended to be a 'public standard' for structured data | ||
| 559 | interchange across computer languages (like JSON or MessagePack). Please | ||
| 560 | do not use it as such. | ||
| 561 | </p> | ||
| 562 | <p> | ||
| 563 | The specification is given below as a context-free grammar with a | ||
| 564 | top-level <tt>object</tt> as the starting point. Alternatives are | ||
| 565 | separated by the <tt>|</tt> symbol and <tt>*</tt> indicates repeats. | ||
| 566 | Grouping is implicit or indicated by <tt>{…}</tt>. Terminals are | ||
| 567 | either plain hex numbers, encoded as bytes, or have a <tt>.format</tt> | ||
| 568 | suffix. | ||
| 569 | </p> | ||
| 570 | <pre> | ||
| 571 | object → nil | false | true | ||
| 572 | | null | lightud32 | lightud64 | ||
| 573 | | int | num | tab | tab_mt | ||
| 574 | | int64 | uint64 | complex | ||
| 575 | | string | ||
| 576 | |||
| 577 | nil → 0x00 | ||
| 578 | false → 0x01 | ||
| 579 | true → 0x02 | ||
| 580 | |||
| 581 | null → 0x03 // NULL lightuserdata | ||
| 582 | lightud32 → 0x04 data.I // 32 bit lightuserdata | ||
| 583 | lightud64 → 0x05 data.L // 64 bit lightuserdata | ||
| 584 | |||
| 585 | int → 0x06 int.I // int32_t | ||
| 586 | num → 0x07 double.L | ||
| 587 | |||
| 588 | tab → 0x08 // Empty table | ||
| 589 | | 0x09 h.U h*{object object} // Key/value hash | ||
| 590 | | 0x0a a.U a*object // 0-based array | ||
| 591 | | 0x0b a.U h.U a*object h*{object object} // Mixed | ||
| 592 | | 0x0c a.U (a-1)*object // 1-based array | ||
| 593 | | 0x0d a.U h.U (a-1)*object h*{object object} // Mixed | ||
| 594 | tab_mt → 0x0e (index-1).U tab // Metatable dict entry | ||
| 595 | |||
| 596 | int64 → 0x10 int.L // FFI int64_t | ||
| 597 | uint64 → 0x11 uint.L // FFI uint64_t | ||
| 598 | complex → 0x12 re.L im.L // FFI complex | ||
| 599 | |||
| 600 | string → (0x20+len).U len*char.B | ||
| 601 | | 0x0f (index-1).U // String dict entry | ||
| 602 | |||
| 603 | .B = 8 bit | ||
| 604 | .I = 32 bit little-endian | ||
| 605 | .L = 64 bit little-endian | ||
| 606 | .U = prefix-encoded 32 bit unsigned number n: | ||
| 607 | 0x00..0xdf → n.B | ||
| 608 | 0xe0..0x1fdf → (0xe0|(((n-0xe0)>>8)&0x1f)).B ((n-0xe0)&0xff).B | ||
| 609 | 0x1fe0.. → 0xff n.I | ||
| 610 | </pre> | ||
| 611 | |||
| 612 | <h2 id="error">Error handling</h2> | ||
| 613 | <p> | ||
| 614 | Many of the buffer methods can throw an error. Out-of-memory or usage | ||
| 615 | errors are best caught with an outer wrapper for larger parts of code. | ||
| 616 | There's not much one can do after that, anyway. | ||
| 617 | </p> | ||
| 618 | <p> | ||
| 619 | OTOH, you may want to catch some errors individually. Buffer methods need | ||
| 620 | to receive the buffer object as the first argument. The Lua colon-syntax | ||
| 621 | <tt>obj:method()</tt> does that implicitly. But to wrap a method with | ||
| 622 | <tt>pcall()</tt>, the arguments need to be passed like this: | ||
| 623 | </p> | ||
| 624 | <pre class="code"> | ||
| 625 | local ok, err = pcall(buf.encode, buf, obj) | ||
| 626 | if not ok then | ||
| 627 | -- Handle error in err. | ||
| 628 | end | ||
| 629 | </pre> | ||
| 630 | |||
| 631 | <h2 id="ffi_caveats">FFI caveats</h2> | ||
| 632 | <p> | ||
| 633 | The string buffer library has been designed to work well together with | ||
| 634 | the FFI library. But due to the low-level nature of the FFI library, | ||
| 635 | some care needs to be taken: | ||
| 636 | </p> | ||
| 637 | <p> | ||
| 638 | First, please remember that FFI pointers are zero-indexed. The space | ||
| 639 | returned by <tt>buf:reserve()</tt> and <tt>buf:ref()</tt> starts at the | ||
| 640 | returned pointer and ends before <tt>len</tt> bytes after that. | ||
| 641 | </p> | ||
| 642 | <p> | ||
| 643 | I.e. the first valid index is <tt>ptr[0]</tt> and the last valid index | ||
| 644 | is <tt>ptr[len-1]</tt>. If the returned length is zero, there's no valid | ||
| 645 | index at all. The returned pointer may even be <tt>NULL</tt>. | ||
| 646 | </p> | ||
| 647 | <p> | ||
| 648 | The space pointed to by the returned pointer is only valid as long as | ||
| 649 | the buffer is not modified in any way (neither append, nor consume, nor | ||
| 650 | reset, etc.). The pointer is also not a GC anchor for the buffer object | ||
| 651 | itself. | ||
| 652 | </p> | ||
| 653 | <p> | ||
| 654 | Buffer data is only guaranteed to be byte-aligned. Casting the returned | ||
| 655 | pointer to a data type with higher alignment may cause unaligned | ||
| 656 | accesses. It depends on the CPU architecture whether this is allowed or | ||
| 657 | not (it's always OK on x86/x64 and mostly OK on other modern | ||
| 658 | architectures). | ||
| 659 | </p> | ||
| 660 | <p> | ||
| 661 | FFI pointers or references do not count as GC anchors for an underlying | ||
| 662 | object. E.g. an <tt>array</tt> allocated with <tt>ffi.new()</tt> is | ||
| 663 | anchored by <tt>buf:set(array, len)</tt>, but not by | ||
| 664 | <tt>buf:set(array+offset, len)</tt>. The addition of the offset | ||
| 665 | creates a new pointer, even when the offset is zero. In this case, you | ||
| 666 | need to make sure there's still a reference to the original array as | ||
| 667 | long as its contents are in use by the buffer. | ||
| 668 | </p> | ||
| 669 | <p> | ||
| 670 | Even though each LuaJIT VM instance is single-threaded (but you can | ||
| 671 | create multiple VMs), FFI data structures can be accessed concurrently. | ||
| 672 | Be careful when reading/writing FFI cdata from/to buffers to avoid | ||
| 673 | concurrent accesses or modifications. In particular, the memory | ||
| 674 | referenced by <tt>buf:set(cdata, len)</tt> must not be modified | ||
| 675 | while buffer readers are working on it. Shared, but read-only memory | ||
| 676 | mappings of files are OK, but only if the file does not change. | ||
| 677 | </p> | ||
| 678 | <br class="flush"> | ||
| 679 | </div> | ||
| 680 | <div id="foot"> | ||
| 681 | <hr class="hide"> | ||
| 682 | Copyright © 2005-2026 | ||
| 683 | <span class="noprint"> | ||
| 684 | · | ||
| 685 | <a href="contact.html">Contact</a> | ||
| 686 | </span> | ||
| 687 | </div> | ||
| 688 | </body> | ||
| 689 | </html> | ||
diff --git a/doc/ext_c_api.html b/doc/ext_c_api.html index c895d7d1..dea51105 100644 --- a/doc/ext_c_api.html +++ b/doc/ext_c_api.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>Lua/C API Extensions</title> | 4 | <title>Lua/C API 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-2026"> | 6 | <meta name="Copyright" content="Copyright (C) 2005-2026"> |
| 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"> |
| @@ -37,9 +37,13 @@ | |||
| 37 | <a href="ext_ffi_semantics.html">FFI Semantics</a> | 37 | <a href="ext_ffi_semantics.html">FFI Semantics</a> |
| 38 | </li></ul> | 38 | </li></ul> |
| 39 | </li><li> | 39 | </li><li> |
| 40 | <a href="ext_buffer.html">String Buffers</a> | ||
| 41 | </li><li> | ||
| 40 | <a href="ext_jit.html">jit.* Library</a> | 42 | <a href="ext_jit.html">jit.* Library</a> |
| 41 | </li><li> | 43 | </li><li> |
| 42 | <a class="current" href="ext_c_api.html">Lua/C API</a> | 44 | <a class="current" href="ext_c_api.html">Lua/C API</a> |
| 45 | </li><li> | ||
| 46 | <a href="ext_profiler.html">Profiler</a> | ||
| 43 | </li></ul> | 47 | </li></ul> |
| 44 | </li><li> | 48 | </li><li> |
| 45 | <a href="https://luajit.org/status.html">Status <span class="ext">»</span></a> | 49 | <a href="https://luajit.org/status.html">Status <span class="ext">»</span></a> |
diff --git a/doc/ext_ffi.html b/doc/ext_ffi.html index 9f0e1350..8e70a1b9 100644 --- a/doc/ext_ffi.html +++ b/doc/ext_ffi.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>FFI Library</title> | 4 | <title>FFI Library</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-2026"> | 6 | <meta name="Copyright" content="Copyright (C) 2005-2026"> |
| 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"> |
| @@ -37,9 +37,13 @@ | |||
| 37 | <a href="ext_ffi_semantics.html">FFI Semantics</a> | 37 | <a href="ext_ffi_semantics.html">FFI Semantics</a> |
| 38 | </li></ul> | 38 | </li></ul> |
| 39 | </li><li> | 39 | </li><li> |
| 40 | <a href="ext_buffer.html">String Buffers</a> | ||
| 41 | </li><li> | ||
| 40 | <a href="ext_jit.html">jit.* Library</a> | 42 | <a href="ext_jit.html">jit.* Library</a> |
| 41 | </li><li> | 43 | </li><li> |
| 42 | <a href="ext_c_api.html">Lua/C API</a> | 44 | <a href="ext_c_api.html">Lua/C API</a> |
| 45 | </li><li> | ||
| 46 | <a href="ext_profiler.html">Profiler</a> | ||
| 43 | </li></ul> | 47 | </li></ul> |
| 44 | </li><li> | 48 | </li><li> |
| 45 | <a href="https://luajit.org/status.html">Status <span class="ext">»</span></a> | 49 | <a href="https://luajit.org/status.html">Status <span class="ext">»</span></a> |
diff --git a/doc/ext_ffi_api.html b/doc/ext_ffi_api.html index 5d34ff01..7e89d336 100644 --- a/doc/ext_ffi_api.html +++ b/doc/ext_ffi_api.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>ffi.* API Functions</title> | 4 | <title>ffi.* API Functions</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-2026"> | 6 | <meta name="Copyright" content="Copyright (C) 2005-2026"> |
| 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"> |
| @@ -42,9 +42,13 @@ td.abiparam { font-weight: bold; width: 6em; } | |||
| 42 | <a href="ext_ffi_semantics.html">FFI Semantics</a> | 42 | <a href="ext_ffi_semantics.html">FFI Semantics</a> |
| 43 | </li></ul> | 43 | </li></ul> |
| 44 | </li><li> | 44 | </li><li> |
| 45 | <a href="ext_buffer.html">String Buffers</a> | ||
| 46 | </li><li> | ||
| 45 | <a href="ext_jit.html">jit.* Library</a> | 47 | <a href="ext_jit.html">jit.* Library</a> |
| 46 | </li><li> | 48 | </li><li> |
| 47 | <a href="ext_c_api.html">Lua/C API</a> | 49 | <a href="ext_c_api.html">Lua/C API</a> |
| 50 | </li><li> | ||
| 51 | <a href="ext_profiler.html">Profiler</a> | ||
| 48 | </li></ul> | 52 | </li></ul> |
| 49 | </li><li> | 53 | </li><li> |
| 50 | <a href="https://luajit.org/status.html">Status <span class="ext">»</span></a> | 54 | <a href="https://luajit.org/status.html">Status <span class="ext">»</span></a> |
| @@ -458,6 +462,14 @@ otherwise. The following parameters are currently defined: | |||
| 458 | <td class="abiparam">eabi</td><td class="abidesc">EABI variant of the standard ABI</td></tr> | 462 | <td class="abiparam">eabi</td><td class="abidesc">EABI variant of the standard ABI</td></tr> |
| 459 | <tr class="odd"> | 463 | <tr class="odd"> |
| 460 | <td class="abiparam">win</td><td class="abidesc">Windows variant of the standard ABI</td></tr> | 464 | <td class="abiparam">win</td><td class="abidesc">Windows variant of the standard ABI</td></tr> |
| 465 | <tr class="even"> | ||
| 466 | <td class="abiparam">pauth</td><td class="abidesc">Pointer authentication ABI</td></tr> | ||
| 467 | <tr class="odd"> | ||
| 468 | <td class="abiparam">uwp</td><td class="abidesc">Universal Windows Platform</td></tr> | ||
| 469 | <tr class="even"> | ||
| 470 | <td class="abiparam">gc64</td><td class="abidesc">64 bit GC references</td></tr> | ||
| 471 | <tr class="odd"> | ||
| 472 | <td class="abiparam">dualnum</td><td class="abidesc">Dual-number mode</td></tr> | ||
| 461 | </table> | 473 | </table> |
| 462 | 474 | ||
| 463 | <h3 id="ffi_os"><tt>ffi.os</tt></h3> | 475 | <h3 id="ffi_os"><tt>ffi.os</tt></h3> |
| @@ -534,8 +546,8 @@ corresponding ctype. | |||
| 534 | The parser for Lua source code treats numeric literals with the | 546 | The parser for Lua source code treats numeric literals with the |
| 535 | suffixes <tt>LL</tt> or <tt>ULL</tt> as signed or unsigned 64 bit | 547 | suffixes <tt>LL</tt> or <tt>ULL</tt> as signed or unsigned 64 bit |
| 536 | integers. Case doesn't matter, but uppercase is recommended for | 548 | integers. Case doesn't matter, but uppercase is recommended for |
| 537 | readability. It handles both decimal (<tt>42LL</tt>) and hexadecimal | 549 | readability. It handles decimal (<tt>42LL</tt>), hexadecimal |
| 538 | (<tt>0x2aLL</tt>) literals. | 550 | (<tt>0x2aLL</tt>) and binary (<tt>0b101010LL</tt>) literals. |
| 539 | </p> | 551 | </p> |
| 540 | <p> | 552 | <p> |
| 541 | The imaginary part of complex numbers can be specified by suffixing | 553 | The imaginary part of complex numbers can be specified by suffixing |
diff --git a/doc/ext_ffi_semantics.html b/doc/ext_ffi_semantics.html index 806349ac..bf8d346d 100644 --- a/doc/ext_ffi_semantics.html +++ b/doc/ext_ffi_semantics.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>FFI Semantics</title> | 4 | <title>FFI Semantics</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-2026"> | 6 | <meta name="Copyright" content="Copyright (C) 2005-2026"> |
| 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"> |
| @@ -42,9 +42,13 @@ td.convop { font-style: italic; width: 40%; } | |||
| 42 | <a class="current" href="ext_ffi_semantics.html">FFI Semantics</a> | 42 | <a class="current" href="ext_ffi_semantics.html">FFI Semantics</a> |
| 43 | </li></ul> | 43 | </li></ul> |
| 44 | </li><li> | 44 | </li><li> |
| 45 | <a href="ext_buffer.html">String Buffers</a> | ||
| 46 | </li><li> | ||
| 45 | <a href="ext_jit.html">jit.* Library</a> | 47 | <a href="ext_jit.html">jit.* Library</a> |
| 46 | </li><li> | 48 | </li><li> |
| 47 | <a href="ext_c_api.html">Lua/C API</a> | 49 | <a href="ext_c_api.html">Lua/C API</a> |
| 50 | </li><li> | ||
| 51 | <a href="ext_profiler.html">Profiler</a> | ||
| 48 | </li></ul> | 52 | </li></ul> |
| 49 | </li><li> | 53 | </li><li> |
| 50 | <a href="https://luajit.org/status.html">Status <span class="ext">»</span></a> | 54 | <a href="https://luajit.org/status.html">Status <span class="ext">»</span></a> |
| @@ -175,6 +179,8 @@ a <tt>typedef</tt>, except re-declarations will be ignored): | |||
| 175 | <tt>uint16_t</tt>, <tt>uint32_t</tt>, <tt>uint64_t</tt>, | 179 | <tt>uint16_t</tt>, <tt>uint32_t</tt>, <tt>uint64_t</tt>, |
| 176 | <tt>intptr_t</tt>, <tt>uintptr_t</tt>.</li> | 180 | <tt>intptr_t</tt>, <tt>uintptr_t</tt>.</li> |
| 177 | 181 | ||
| 182 | <li>From <tt><unistd.h></tt> (POSIX): <tt>ssize_t</tt>.</li> | ||
| 183 | |||
| 178 | </ul> | 184 | </ul> |
| 179 | <p> | 185 | <p> |
| 180 | You're encouraged to use these types in preference to | 186 | You're encouraged to use these types in preference to |
| @@ -332,42 +338,44 @@ pointer or type compatibility: | |||
| 332 | <tr class="odd"> | 338 | <tr class="odd"> |
| 333 | <td class="convin">Integer</td><td class="convop">→<sup>round</sup></td><td class="convout"><tt>double</tt>, <tt>float</tt></td></tr> | 339 | <td class="convin">Integer</td><td class="convop">→<sup>round</sup></td><td class="convout"><tt>double</tt>, <tt>float</tt></td></tr> |
| 334 | <tr class="even"> | 340 | <tr class="even"> |
| 335 | <td class="convin"><tt>double</tt>, <tt>float</tt></td><td class="convop">→<sup>trunc</sup> <tt>int32_t</tt> →<sup>narrow</sup></td><td class="convout"><tt>(u)int8_t</tt>, <tt>(u)int16_t</tt></td></tr> | 341 | <td class="convin"><tt>double</tt>, <tt>float</tt></td><td class="convop">→<sup>trunc</sup> <tt>int64_t</tt> →<sup>narrow</sup> <sup>*</sup></td><td class="convout"><tt>(u)int8_t</tt>, <tt>(u)int16_t</tt>, <tt>(u)int32_t</tt></td></tr> |
| 336 | <tr class="odd"> | 342 | <tr class="odd"> |
| 337 | <td class="convin"><tt>double</tt>, <tt>float</tt></td><td class="convop">→<sup>trunc</sup></td><td class="convout"><tt>(u)int32_t</tt>, <tt>(u)int64_t</tt></td></tr> | 343 | <td class="convin"><tt>double</tt>, <tt>float</tt></td><td class="convop">→<sup>trunc</sup></td><td class="convout"><tt>int64_t</tt></td></tr> |
| 338 | <tr class="even"> | 344 | <tr class="even"> |
| 345 | <td class="convin"><tt>double</tt>, <tt>float</tt></td><td class="convop">→<sup>trunc</sup> uint64_t ∪ int64_t →<sup>reinterpret</sup> <sup>*</sup></td><td class="convout"><tt>uint64_t</tt></td></tr> | ||
| 346 | <tr class="odd"> | ||
| 339 | <td class="convin"><tt>double</tt>, <tt>float</tt></td><td class="convop">→<sup>round</sup></td><td class="convout"><tt>float</tt>, <tt>double</tt></td></tr> | 347 | <td class="convin"><tt>double</tt>, <tt>float</tt></td><td class="convop">→<sup>round</sup></td><td class="convout"><tt>float</tt>, <tt>double</tt></td></tr> |
| 340 | <tr class="odd separate"> | 348 | <tr class="even separate"> |
| 341 | <td class="convin">Number</td><td class="convop">n == 0 → 0, otherwise 1</td><td class="convout"><tt>bool</tt></td></tr> | 349 | <td class="convin">Number</td><td class="convop">n == 0 → 0, otherwise 1</td><td class="convout"><tt>bool</tt></td></tr> |
| 342 | <tr class="even"> | 350 | <tr class="odd"> |
| 343 | <td class="convin"><tt>bool</tt></td><td class="convop"><tt>false</tt> → 0, <tt>true</tt> → 1</td><td class="convout">Number</td></tr> | 351 | <td class="convin"><tt>bool</tt></td><td class="convop"><tt>false</tt> → 0, <tt>true</tt> → 1</td><td class="convout">Number</td></tr> |
| 344 | <tr class="odd separate"> | 352 | <tr class="even separate"> |
| 345 | <td class="convin">Complex number</td><td class="convop">convert real part</td><td class="convout">Number</td></tr> | 353 | <td class="convin">Complex number</td><td class="convop">convert real part</td><td class="convout">Number</td></tr> |
| 346 | <tr class="even"> | ||
| 347 | <td class="convin">Number</td><td class="convop">convert real part, imag = 0</td><td class="convout">Complex number</td></tr> | ||
| 348 | <tr class="odd"> | 354 | <tr class="odd"> |
| 355 | <td class="convin">Number</td><td class="convop">convert real part, imag = 0</td><td class="convout">Complex number</td></tr> | ||
| 356 | <tr class="even"> | ||
| 349 | <td class="convin">Complex number</td><td class="convop">convert real and imag part</td><td class="convout">Complex number</td></tr> | 357 | <td class="convin">Complex number</td><td class="convop">convert real and imag part</td><td class="convout">Complex number</td></tr> |
| 350 | <tr class="even separate"> | 358 | <tr class="odd separate"> |
| 351 | <td class="convin">Number</td><td class="convop">convert scalar and replicate</td><td class="convout">Vector</td></tr> | 359 | <td class="convin">Number</td><td class="convop">convert scalar and replicate</td><td class="convout">Vector</td></tr> |
| 352 | <tr class="odd"> | 360 | <tr class="even"> |
| 353 | <td class="convin">Vector</td><td class="convop">copy (same size)</td><td class="convout">Vector</td></tr> | 361 | <td class="convin">Vector</td><td class="convop">copy (same size)</td><td class="convout">Vector</td></tr> |
| 354 | <tr class="even separate"> | 362 | <tr class="odd separate"> |
| 355 | <td class="convin"><tt>struct</tt>/<tt>union</tt></td><td class="convop">take base address (compat)</td><td class="convout">Pointer</td></tr> | 363 | <td class="convin"><tt>struct</tt>/<tt>union</tt></td><td class="convop">take base address (compat)</td><td class="convout">Pointer</td></tr> |
| 356 | <tr class="odd"> | ||
| 357 | <td class="convin">Array</td><td class="convop">take base address (compat)</td><td class="convout">Pointer</td></tr> | ||
| 358 | <tr class="even"> | 364 | <tr class="even"> |
| 365 | <td class="convin">Array</td><td class="convop">take base address (compat)</td><td class="convout">Pointer</td></tr> | ||
| 366 | <tr class="odd"> | ||
| 359 | <td class="convin">Function</td><td class="convop">take function address</td><td class="convout">Function pointer</td></tr> | 367 | <td class="convin">Function</td><td class="convop">take function address</td><td class="convout">Function pointer</td></tr> |
| 360 | <tr class="odd separate"> | 368 | <tr class="even separate"> |
| 361 | <td class="convin">Number</td><td class="convop">convert via <tt>uintptr_t</tt> (cast)</td><td class="convout">Pointer</td></tr> | 369 | <td class="convin">Number</td><td class="convop">convert via <tt>uintptr_t</tt> (cast)</td><td class="convout">Pointer</td></tr> |
| 362 | <tr class="even"> | ||
| 363 | <td class="convin">Pointer</td><td class="convop">convert address (compat/cast)</td><td class="convout">Pointer</td></tr> | ||
| 364 | <tr class="odd"> | 370 | <tr class="odd"> |
| 365 | <td class="convin">Pointer</td><td class="convop">convert address (cast)</td><td class="convout">Integer</td></tr> | 371 | <td class="convin">Pointer</td><td class="convop">convert address (compat/cast)</td><td class="convout">Pointer</td></tr> |
| 366 | <tr class="even"> | 372 | <tr class="even"> |
| 373 | <td class="convin">Pointer</td><td class="convop">convert address (cast)</td><td class="convout">Integer</td></tr> | ||
| 374 | <tr class="odd"> | ||
| 367 | <td class="convin">Array</td><td class="convop">convert base address (cast)</td><td class="convout">Integer</td></tr> | 375 | <td class="convin">Array</td><td class="convop">convert base address (cast)</td><td class="convout">Integer</td></tr> |
| 368 | <tr class="odd separate"> | 376 | <tr class="even separate"> |
| 369 | <td class="convin">Array</td><td class="convop">copy (compat)</td><td class="convout">Array</td></tr> | 377 | <td class="convin">Array</td><td class="convop">copy (compat)</td><td class="convout">Array</td></tr> |
| 370 | <tr class="even"> | 378 | <tr class="odd"> |
| 371 | <td class="convin"><tt>struct</tt>/<tt>union</tt></td><td class="convop">copy (identical type)</td><td class="convout"><tt>struct</tt>/<tt>union</tt></td></tr> | 379 | <td class="convin"><tt>struct</tt>/<tt>union</tt></td><td class="convop">copy (identical type)</td><td class="convout"><tt>struct</tt>/<tt>union</tt></td></tr> |
| 372 | </table> | 380 | </table> |
| 373 | <p> | 381 | <p> |
| @@ -378,6 +386,24 @@ type. | |||
| 378 | Conversions not listed above will raise an error. E.g. it's not | 386 | Conversions not listed above will raise an error. E.g. it's not |
| 379 | possible to convert a pointer to a complex number or vice versa. | 387 | possible to convert a pointer to a complex number or vice versa. |
| 380 | </p> | 388 | </p> |
| 389 | <p> | ||
| 390 | * Some conversions from <tt>double</tt> have a larger defined range to | ||
| 391 | allow for mixed-signedness conversions, which are common in C code. | ||
| 392 | E.g. initializing an <tt>int32_t</tt> field with <tt>0xffffffff</tt> | ||
| 393 | or initializing an <tt>uint32_t</tt> or <tt>uint64_t</tt> field with | ||
| 394 | <tt>-1</tt>. Under strict conversion rules, these assignments would | ||
| 395 | give undefined results, since Lua numbers are doubles. The extended | ||
| 396 | ranges make these conversions defined. Lua numbers that are even | ||
| 397 | outside that range give an architecture-specific result. | ||
| 398 | </p> | ||
| 399 | <p> | ||
| 400 | Please note that doubles do not have the precision to represent the | ||
| 401 | whole signed or unsigned 64 bit integer range. Beware of large hex | ||
| 402 | constants in particular: e.g. <tt>0xffffffffffffffff</tt> is a double | ||
| 403 | rounded up to <tt>0x1p64</tt> during parsing. This will <em>not</em> | ||
| 404 | convert to a defined 64 bit integer value. Use the 64 bit literal | ||
| 405 | syntax instead, i.e. <tt>0xffffffffffffffffULL</tt>. | ||
| 406 | </p> | ||
| 381 | 407 | ||
| 382 | <h3 id="convert_vararg">Conversions for vararg C function arguments</h3> | 408 | <h3 id="convert_vararg">Conversions for vararg C function arguments</h3> |
| 383 | <p> | 409 | <p> |
| @@ -434,6 +460,19 @@ If you don't do this, the default Lua number → <tt>double</tt> | |||
| 434 | conversion rule applies. A vararg C function expecting an integer | 460 | conversion rule applies. A vararg C function expecting an integer |
| 435 | will see a garbled or uninitialized value. | 461 | will see a garbled or uninitialized value. |
| 436 | </p> | 462 | </p> |
| 463 | <p> | ||
| 464 | Note: this is the only place where creating a boxed scalar number type is | ||
| 465 | actually useful. <b>Never use <tt>ffi.new("int")</tt>, <tt>ffi.new("float")</tt> | ||
| 466 | etc. anywhere else!</b> | ||
| 467 | </p> | ||
| 468 | <p style="font-size: 8pt;"> | ||
| 469 | Ditto for <tt>ffi.cast()</tt>. Explicitly boxing scalars <b>does not</b> | ||
| 470 | improve performance or force <tt>int</tt> or <tt>float</tt> arithmetic! It | ||
| 471 | just adds costly boxing, unboxing and conversions steps. And it may lead | ||
| 472 | to surprise results, because | ||
| 473 | <a href="#cdata_arith">cdata arithmetic on scalar numbers</a> | ||
| 474 | is always performed on 64 bit integers. | ||
| 475 | </p> | ||
| 437 | 476 | ||
| 438 | <h2 id="init">Initializers</h2> | 477 | <h2 id="init">Initializers</h2> |
| 439 | <p> | 478 | <p> |
| @@ -722,6 +761,22 @@ You'll have to explicitly convert a 64 bit integer to a Lua | |||
| 722 | number (e.g. for regular floating-point calculations) with | 761 | number (e.g. for regular floating-point calculations) with |
| 723 | <tt>tonumber()</tt>. But note this may incur a precision loss.</li> | 762 | <tt>tonumber()</tt>. But note this may incur a precision loss.</li> |
| 724 | 763 | ||
| 764 | <li><b>64 bit bitwise operations</b>: the rules for 64 bit | ||
| 765 | arithmetic operators apply analogously.<br> | ||
| 766 | |||
| 767 | Unlike the other <tt>bit.*</tt> operations, <tt>bit.tobit()</tt> | ||
| 768 | converts a cdata number via <tt>int64_t</tt> to <tt>int32_t</tt> and | ||
| 769 | returns a Lua number.<br> | ||
| 770 | |||
| 771 | For <tt>bit.band()</tt>, <tt>bit.bor()</tt> and <tt>bit.bxor()</tt>, the | ||
| 772 | conversion to <tt>int64_t</tt> or <tt>uint64_t</tt> applies to | ||
| 773 | <em>all</em> arguments, if <em>any</em> argument is a cdata number.<br> | ||
| 774 | |||
| 775 | For all other operations, only the first argument is used to determine | ||
| 776 | the output type. This implies that a cdata number as a shift count for | ||
| 777 | shifts and rotates is accepted, but that alone does <em>not</em> cause | ||
| 778 | a cdata number output. | ||
| 779 | |||
| 725 | </ul> | 780 | </ul> |
| 726 | 781 | ||
| 727 | <h3 id="cdata_comp">Comparisons of cdata objects</h3> | 782 | <h3 id="cdata_comp">Comparisons of cdata objects</h3> |
| @@ -1193,14 +1248,12 @@ The following operations are currently not compiled and may exhibit | |||
| 1193 | suboptimal performance, especially when used in inner loops: | 1248 | suboptimal performance, especially when used in inner loops: |
| 1194 | </p> | 1249 | </p> |
| 1195 | <ul> | 1250 | <ul> |
| 1196 | <li>Bitfield accesses and initializations.</li> | ||
| 1197 | <li>Vector operations.</li> | 1251 | <li>Vector operations.</li> |
| 1198 | <li>Table initializers.</li> | 1252 | <li>Table initializers.</li> |
| 1199 | <li>Initialization of nested <tt>struct</tt>/<tt>union</tt> types.</li> | 1253 | <li>Initialization of nested <tt>struct</tt>/<tt>union</tt> types.</li> |
| 1200 | <li>Allocations of variable-length arrays or structs.</li> | 1254 | <li>Non-default initialization of VLA/VLS or large C types |
| 1201 | <li>Allocations of C types with a size > 128 bytes or an | 1255 | (> 128 bytes or > 16 array elements).</li> |
| 1202 | alignment > 8 bytes.</li> | 1256 | <li>Bitfield initializations.</li> |
| 1203 | <li>Conversions from lightuserdata to <tt>void *</tt>.</li> | ||
| 1204 | <li>Pointer differences for element sizes that are not a power of | 1257 | <li>Pointer differences for element sizes that are not a power of |
| 1205 | two.</li> | 1258 | two.</li> |
| 1206 | <li>Calls to C functions with aggregates passed or returned by | 1259 | <li>Calls to C functions with aggregates passed or returned by |
| @@ -1216,7 +1269,6 @@ value.</li> | |||
| 1216 | Other missing features: | 1269 | Other missing features: |
| 1217 | </p> | 1270 | </p> |
| 1218 | <ul> | 1271 | <ul> |
| 1219 | <li>Bit operations for 64 bit types.</li> | ||
| 1220 | <li>Arithmetic for <tt>complex</tt> numbers.</li> | 1272 | <li>Arithmetic for <tt>complex</tt> numbers.</li> |
| 1221 | <li>Passing structs by value to vararg C functions.</li> | 1273 | <li>Passing structs by value to vararg C functions.</li> |
| 1222 | <li><a href="extensions.html#exceptions">C++ exception interoperability</a> | 1274 | <li><a href="extensions.html#exceptions">C++ exception interoperability</a> |
diff --git a/doc/ext_ffi_tutorial.html b/doc/ext_ffi_tutorial.html index 14ee7af7..e511dfe5 100644 --- a/doc/ext_ffi_tutorial.html +++ b/doc/ext_ffi_tutorial.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>FFI Tutorial</title> | 4 | <title>FFI Tutorial</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-2026"> | 6 | <meta name="Copyright" content="Copyright (C) 2005-2026"> |
| 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"> |
| @@ -44,9 +44,13 @@ td.idiomlua b { font-weight: normal; color: #2142bf; } | |||
| 44 | <a href="ext_ffi_semantics.html">FFI Semantics</a> | 44 | <a href="ext_ffi_semantics.html">FFI Semantics</a> |
| 45 | </li></ul> | 45 | </li></ul> |
| 46 | </li><li> | 46 | </li><li> |
| 47 | <a href="ext_buffer.html">String Buffers</a> | ||
| 48 | </li><li> | ||
| 47 | <a href="ext_jit.html">jit.* Library</a> | 49 | <a href="ext_jit.html">jit.* Library</a> |
| 48 | </li><li> | 50 | </li><li> |
| 49 | <a href="ext_c_api.html">Lua/C API</a> | 51 | <a href="ext_c_api.html">Lua/C API</a> |
| 52 | </li><li> | ||
| 53 | <a href="ext_profiler.html">Profiler</a> | ||
| 50 | </li></ul> | 54 | </li></ul> |
| 51 | </li><li> | 55 | </li><li> |
| 52 | <a href="https://luajit.org/status.html">Status <span class="ext">»</span></a> | 56 | <a href="https://luajit.org/status.html">Status <span class="ext">»</span></a> |
diff --git a/doc/ext_jit.html b/doc/ext_jit.html index 4f519924..f3ae3180 100644 --- a/doc/ext_jit.html +++ b/doc/ext_jit.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>jit.* Library</title> | 4 | <title>jit.* Library</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-2026"> | 6 | <meta name="Copyright" content="Copyright (C) 2005-2026"> |
| 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"> |
| @@ -37,9 +37,13 @@ | |||
| 37 | <a href="ext_ffi_semantics.html">FFI Semantics</a> | 37 | <a href="ext_ffi_semantics.html">FFI Semantics</a> |
| 38 | </li></ul> | 38 | </li></ul> |
| 39 | </li><li> | 39 | </li><li> |
| 40 | <a href="ext_buffer.html">String Buffers</a> | ||
| 41 | </li><li> | ||
| 40 | <a class="current" href="ext_jit.html">jit.* Library</a> | 42 | <a class="current" href="ext_jit.html">jit.* Library</a> |
| 41 | </li><li> | 43 | </li><li> |
| 42 | <a href="ext_c_api.html">Lua/C API</a> | 44 | <a href="ext_c_api.html">Lua/C API</a> |
| 45 | </li><li> | ||
| 46 | <a href="ext_profiler.html">Profiler</a> | ||
| 43 | </li></ul> | 47 | </li></ul> |
| 44 | </li><li> | 48 | </li><li> |
| 45 | <a href="https://luajit.org/status.html">Status <span class="ext">»</span></a> | 49 | <a href="https://luajit.org/status.html">Status <span class="ext">»</span></a> |
| @@ -145,7 +149,7 @@ Contains the target OS name: | |||
| 145 | <h3 id="jit_arch"><tt>jit.arch</tt></h3> | 149 | <h3 id="jit_arch"><tt>jit.arch</tt></h3> |
| 146 | <p> | 150 | <p> |
| 147 | Contains the target architecture name: | 151 | Contains the target architecture name: |
| 148 | "x86", "x64", "arm", "ppc", "ppcspe", or "mips". | 152 | "x86", "x64", "arm", "arm64", "arm64be", "ppc", "mips", "mipsel", "mips64", "mips64el", "mips64r6", "mips64r6el". |
| 149 | </p> | 153 | </p> |
| 150 | 154 | ||
| 151 | <h2 id="jit_opt"><tt>jit.opt.*</tt> — JIT compiler optimization control</h2> | 155 | <h2 id="jit_opt"><tt>jit.opt.*</tt> — JIT compiler optimization control</h2> |
diff --git a/doc/ext_profiler.html b/doc/ext_profiler.html new file mode 100644 index 00000000..300a9482 --- /dev/null +++ b/doc/ext_profiler.html | |||
| @@ -0,0 +1,359 @@ | |||
| 1 | <!DOCTYPE html> | ||
| 2 | <html> | ||
| 3 | <head> | ||
| 4 | <title>Profiler</title> | ||
| 5 | <meta charset="utf-8"> | ||
| 6 | <meta name="Copyright" content="Copyright (C) 2005-2026"> | ||
| 7 | <meta name="Language" content="en"> | ||
| 8 | <link rel="stylesheet" type="text/css" href="bluequad.css" media="screen"> | ||
| 9 | <link rel="stylesheet" type="text/css" href="bluequad-print.css" media="print"> | ||
| 10 | </head> | ||
| 11 | <body> | ||
| 12 | <div id="site"> | ||
| 13 | <a href="https://luajit.org"><span>Lua<span id="logo">JIT</span></span></a> | ||
| 14 | </div> | ||
| 15 | <div id="head"> | ||
| 16 | <h1>Profiler</h1> | ||
| 17 | </div> | ||
| 18 | <div id="nav"> | ||
| 19 | <ul><li> | ||
| 20 | <a href="luajit.html">LuaJIT</a> | ||
| 21 | <ul><li> | ||
| 22 | <a href="https://luajit.org/download.html">Download <span class="ext">»</span></a> | ||
| 23 | </li><li> | ||
| 24 | <a href="install.html">Installation</a> | ||
| 25 | </li><li> | ||
| 26 | <a href="running.html">Running</a> | ||
| 27 | </li></ul> | ||
| 28 | </li><li> | ||
| 29 | <a href="extensions.html">Extensions</a> | ||
| 30 | <ul><li> | ||
| 31 | <a href="ext_ffi.html">FFI Library</a> | ||
| 32 | <ul><li> | ||
| 33 | <a href="ext_ffi_tutorial.html">FFI Tutorial</a> | ||
| 34 | </li><li> | ||
| 35 | <a href="ext_ffi_api.html">ffi.* API</a> | ||
| 36 | </li><li> | ||
| 37 | <a href="ext_ffi_semantics.html">FFI Semantics</a> | ||
| 38 | </li></ul> | ||
| 39 | </li><li> | ||
| 40 | <a href="ext_buffer.html">String Buffers</a> | ||
| 41 | </li><li> | ||
| 42 | <a href="ext_jit.html">jit.* Library</a> | ||
| 43 | </li><li> | ||
| 44 | <a href="ext_c_api.html">Lua/C API</a> | ||
| 45 | </li><li> | ||
| 46 | <a class="current" href="ext_profiler.html">Profiler</a> | ||
| 47 | </li></ul> | ||
| 48 | </li><li> | ||
| 49 | <a href="https://luajit.org/status.html">Status <span class="ext">»</span></a> | ||
| 50 | </li><li> | ||
| 51 | <a href="https://luajit.org/faq.html">FAQ <span class="ext">»</span></a> | ||
| 52 | </li><li> | ||
| 53 | <a href="https://luajit.org/list.html">Mailing List <span class="ext">»</span></a> | ||
| 54 | </li></ul> | ||
| 55 | </div> | ||
| 56 | <div id="main"> | ||
| 57 | <p> | ||
| 58 | LuaJIT has an integrated statistical profiler with very low overhead. It | ||
| 59 | allows sampling the currently executing stack and other parameters in | ||
| 60 | regular intervals. | ||
| 61 | </p> | ||
| 62 | <p> | ||
| 63 | The integrated profiler can be accessed from three levels: | ||
| 64 | </p> | ||
| 65 | <ul> | ||
| 66 | <li>The <a href="#hl_profiler">bundled high-level profiler</a>, invoked by the | ||
| 67 | <a href="#j_p"><tt>-jp</tt></a> command line option.</li> | ||
| 68 | <li>A <a href="#ll_lua_api">low-level Lua API</a> to control the profiler.</li> | ||
| 69 | <li>A <a href="#ll_c_api">low-level C API</a> to control the profiler.</li> | ||
| 70 | </ul> | ||
| 71 | |||
| 72 | <h2 id="hl_profiler">High-Level Profiler</h2> | ||
| 73 | <p> | ||
| 74 | The bundled high-level profiler offers basic profiling functionality. It | ||
| 75 | generates simple textual summaries or source code annotations. It can be | ||
| 76 | accessed with the <a href="#j_p"><tt>-jp</tt></a> command line option | ||
| 77 | or from Lua code by loading the underlying <tt>jit.p</tt> module. | ||
| 78 | </p> | ||
| 79 | <p> | ||
| 80 | To cut to the chase — run this to get a CPU usage profile by | ||
| 81 | function name: | ||
| 82 | </p> | ||
| 83 | <pre class="code"> | ||
| 84 | luajit -jp myapp.lua | ||
| 85 | </pre> | ||
| 86 | <p> | ||
| 87 | It's <em>not</em> a stated goal of the bundled profiler to add every | ||
| 88 | possible option or to cater for special profiling needs. The low-level | ||
| 89 | profiler APIs are documented below. They may be used by third-party | ||
| 90 | authors to implement advanced functionality, e.g. IDE integration or | ||
| 91 | graphical profilers. | ||
| 92 | </p> | ||
| 93 | <p> | ||
| 94 | Note: Sampling works for both interpreted and JIT-compiled code. The | ||
| 95 | results for JIT-compiled code may sometimes be surprising. LuaJIT | ||
| 96 | heavily optimizes and inlines Lua code — there's no simple | ||
| 97 | one-to-one correspondence between source code lines and the sampled | ||
| 98 | machine code. | ||
| 99 | </p> | ||
| 100 | |||
| 101 | <h3 id="j_p"><tt>-jp=[options[,output]]</tt></h3> | ||
| 102 | <p> | ||
| 103 | The <tt>-jp</tt> command line option starts the high-level profiler. | ||
| 104 | When the application run by the command line terminates, the profiler | ||
| 105 | stops and writes the results to <tt>stdout</tt> or to the specified | ||
| 106 | <tt>output</tt> file. | ||
| 107 | </p> | ||
| 108 | <p> | ||
| 109 | The <tt>options</tt> argument specifies how the profiling is to be | ||
| 110 | performed: | ||
| 111 | </p> | ||
| 112 | <ul> | ||
| 113 | <li><tt>f</tt> — Stack dump: function name, otherwise module:line. | ||
| 114 | This is the default mode.</li> | ||
| 115 | <li><tt>F</tt> — Stack dump: ditto, but dump module:name.</li> | ||
| 116 | <li><tt>l</tt> — Stack dump: module:line.</li> | ||
| 117 | <li><tt><number></tt> — stack dump depth (callee ← | ||
| 118 | caller). Default: 1.</li> | ||
| 119 | <li><tt>-<number></tt> — Inverse stack dump depth (caller | ||
| 120 | → callee).</li> | ||
| 121 | <li><tt>s</tt> — Split stack dump after first stack level. Implies | ||
| 122 | depth ≥ 2 or depth ≤ -2.</li> | ||
| 123 | <li><tt>p</tt> — Show full path for module names.</li> | ||
| 124 | <li><tt>v</tt> — Show VM states.</li> | ||
| 125 | <li><tt>z</tt> — Show <a href="#jit_zone">zones</a>.</li> | ||
| 126 | <li><tt>r</tt> — Show raw sample counts. Default: show percentages.</li> | ||
| 127 | <li><tt>a</tt> — Annotate excerpts from source code files.</li> | ||
| 128 | <li><tt>A</tt> — Annotate complete source code files.</li> | ||
| 129 | <li><tt>G</tt> — Produce raw output suitable for graphical tools.</li> | ||
| 130 | <li><tt>m<number></tt> — Minimum sample percentage to be shown. | ||
| 131 | Default: 3%.</li> | ||
| 132 | <li><tt>i<number></tt> — Sampling interval in milliseconds. | ||
| 133 | Default: 10ms.<br> | ||
| 134 | Note: The actual sampling precision is OS-dependent.</li> | ||
| 135 | </ul> | ||
| 136 | <p> | ||
| 137 | The default output for <tt>-jp</tt> is a list of the most CPU consuming | ||
| 138 | spots in the application. Increasing the stack dump depth with (say) | ||
| 139 | <tt>-jp=2</tt> may help to point out the main callers or callees of | ||
| 140 | hotspots. But sample aggregation is still flat per unique stack dump. | ||
| 141 | </p> | ||
| 142 | <p> | ||
| 143 | To get a two-level view (split view) of callers/callees, use | ||
| 144 | <tt>-jp=s</tt> or <tt>-jp=-s</tt>. The percentages shown for the second | ||
| 145 | level are relative to the first level. | ||
| 146 | </p> | ||
| 147 | <p> | ||
| 148 | To see how much time is spent in each line relative to a function, use | ||
| 149 | <tt>-jp=fl</tt>. | ||
| 150 | </p> | ||
| 151 | <p> | ||
| 152 | To see how much time is spent in different VM states or | ||
| 153 | <a href="#jit_zone">zones</a>, use <tt>-jp=v</tt> or <tt>-jp=z</tt>. | ||
| 154 | </p> | ||
| 155 | <p> | ||
| 156 | Combinations of <tt>v/z</tt> with <tt>f/F/l</tt> produce two-level | ||
| 157 | views, e.g. <tt>-jp=vf</tt> or <tt>-jp=fv</tt>. This shows the time | ||
| 158 | spent in a VM state or zone vs. hotspots. This can be used to answer | ||
| 159 | questions like "Which time-consuming functions are only interpreted?" or | ||
| 160 | "What's the garbage collector overhead for a specific function?". | ||
| 161 | </p> | ||
| 162 | <p> | ||
| 163 | Multiple options can be combined — but not all combinations make | ||
| 164 | sense, see above. E.g. <tt>-jp=3si4m1</tt> samples three stack levels | ||
| 165 | deep in 4ms intervals and shows a split view of the CPU consuming | ||
| 166 | functions and their callers with a 1% threshold. | ||
| 167 | </p> | ||
| 168 | <p> | ||
| 169 | Source code annotations produced by <tt>-jp=a</tt> or <tt>-jp=A</tt> are | ||
| 170 | always flat and at the line level. Obviously, the source code files need | ||
| 171 | to be readable by the profiler script. | ||
| 172 | </p> | ||
| 173 | <p> | ||
| 174 | The high-level profiler can also be started and stopped from Lua code with: | ||
| 175 | </p> | ||
| 176 | <pre class="code"> | ||
| 177 | require("jit.p").start(options, output) | ||
| 178 | ... | ||
| 179 | require("jit.p").stop() | ||
| 180 | </pre> | ||
| 181 | |||
| 182 | <h3 id="jit_zone"><tt>jit.zone</tt> — Zones</h3> | ||
| 183 | <p> | ||
| 184 | Zones can be used to provide information about different parts of an | ||
| 185 | application to the high-level profiler. E.g. a game could make use of an | ||
| 186 | <tt>"AI"</tt> zone, a <tt>"PHYS"</tt> zone, etc. Zones are hierarchical, | ||
| 187 | organized as a stack. | ||
| 188 | </p> | ||
| 189 | <p> | ||
| 190 | The <tt>jit.zone</tt> module needs to be loaded explicitly: | ||
| 191 | </p> | ||
| 192 | <pre class="code"> | ||
| 193 | local zone = require("jit.zone") | ||
| 194 | </pre> | ||
| 195 | <ul> | ||
| 196 | <li><tt>zone("name")</tt> pushes a named zone to the zone stack.</li> | ||
| 197 | <li><tt>zone()</tt> pops the current zone from the zone stack and | ||
| 198 | returns its name.</li> | ||
| 199 | <li><tt>zone:get()</tt> returns the current zone name or <tt>nil</tt>.</li> | ||
| 200 | <li><tt>zone:flush()</tt> flushes the zone stack.</li> | ||
| 201 | </ul> | ||
| 202 | <p> | ||
| 203 | To show the time spent in each zone use <tt>-jp=z</tt>. To show the time | ||
| 204 | spent relative to hotspots use e.g. <tt>-jp=zf</tt> or <tt>-jp=fz</tt>. | ||
| 205 | </p> | ||
| 206 | |||
| 207 | <h2 id="ll_lua_api">Low-level Lua API</h2> | ||
| 208 | <p> | ||
| 209 | The <tt>jit.profile</tt> module gives access to the low-level API of the | ||
| 210 | profiler from Lua code. This module needs to be loaded explicitly: | ||
| 211 | <pre class="code"> | ||
| 212 | local profile = require("jit.profile") | ||
| 213 | </pre> | ||
| 214 | <p> | ||
| 215 | This module can be used to implement your own higher-level profiler. | ||
| 216 | A typical profiling run starts the profiler, captures stack dumps in | ||
| 217 | the profiler callback, adds them to a hash table to aggregate the number | ||
| 218 | of samples, stops the profiler and then analyzes all captured | ||
| 219 | stack dumps. Other parameters can be sampled in the profiler callback, | ||
| 220 | too. But it's important not to spend too much time in the callback, | ||
| 221 | since this may skew the statistics. | ||
| 222 | </p> | ||
| 223 | |||
| 224 | <h3 id="profile_start"><tt>profile.start(mode, cb)</tt> | ||
| 225 | — Start profiler</h3> | ||
| 226 | <p> | ||
| 227 | This function starts the profiler. The <tt>mode</tt> argument is a | ||
| 228 | string holding options: | ||
| 229 | </p> | ||
| 230 | <ul> | ||
| 231 | <li><tt>f</tt> — Profile with precision down to the function level.</li> | ||
| 232 | <li><tt>l</tt> — Profile with precision down to the line level.</li> | ||
| 233 | <li><tt>i<number></tt> — Sampling interval in milliseconds (default | ||
| 234 | 10ms).</br> | ||
| 235 | Note: The actual sampling precision is OS-dependent. | ||
| 236 | </li> | ||
| 237 | </ul> | ||
| 238 | <p> | ||
| 239 | The <tt>cb</tt> argument is a callback function which is called with | ||
| 240 | three arguments: <tt>(thread, samples, vmstate)</tt>. The callback is | ||
| 241 | called on a separate coroutine, the <tt>thread</tt> argument is the | ||
| 242 | state that holds the stack to sample for profiling. Note: do | ||
| 243 | <em>not</em> modify the stack of that state or call functions on it. | ||
| 244 | </p> | ||
| 245 | <p> | ||
| 246 | <tt>samples</tt> gives the number of accumulated samples since the last | ||
| 247 | callback (usually 1). | ||
| 248 | </p> | ||
| 249 | <p> | ||
| 250 | <tt>vmstate</tt> holds the VM state at the time the profiling timer | ||
| 251 | triggered. This may or may not correspond to the state of the VM when | ||
| 252 | the profiling callback is called. The state is either <tt>'N'</tt> | ||
| 253 | native (compiled) code, <tt>'I'</tt> interpreted code, <tt>'C'</tt> | ||
| 254 | C code, <tt>'G'</tt> the garbage collector, or <tt>'J'</tt> the JIT | ||
| 255 | compiler. | ||
| 256 | </p> | ||
| 257 | |||
| 258 | <h3 id="profile_stop"><tt>profile.stop()</tt> | ||
| 259 | — Stop profiler</h3> | ||
| 260 | <p> | ||
| 261 | This function stops the profiler. | ||
| 262 | </p> | ||
| 263 | |||
| 264 | <h3 id="profile_dump"><tt>dump = profile.dumpstack([thread,] fmt, depth)</tt> | ||
| 265 | — Dump stack </h3> | ||
| 266 | <p> | ||
| 267 | This function allows taking stack dumps in an efficient manner. It | ||
| 268 | returns a string with a stack dump for the <tt>thread</tt> (coroutine), | ||
| 269 | formatted according to the <tt>fmt</tt> argument: | ||
| 270 | </p> | ||
| 271 | <ul> | ||
| 272 | <li><tt>p</tt> — Preserve the full path for module names. Otherwise, | ||
| 273 | only the file name is used.</li> | ||
| 274 | <li><tt>f</tt> — Dump the function name if it can be derived. Otherwise, | ||
| 275 | use module:line.</li> | ||
| 276 | <li><tt>F</tt> — Ditto, but dump module:name.</li> | ||
| 277 | <li><tt>l</tt> — Dump module:line.</li> | ||
| 278 | <li><tt>Z</tt> — Zap the following characters for the last dumped | ||
| 279 | frame.</li> | ||
| 280 | <li>All other characters are added verbatim to the output string.</li> | ||
| 281 | </ul> | ||
| 282 | <p> | ||
| 283 | The <tt>depth</tt> argument gives the number of frames to dump, starting | ||
| 284 | at the topmost frame of the thread. A negative number dumps the frames in | ||
| 285 | inverse order. | ||
| 286 | </p> | ||
| 287 | <p> | ||
| 288 | The first example prints a list of the current module names and line | ||
| 289 | numbers of up to 10 frames in separate lines. The second example prints | ||
| 290 | semicolon-separated function names for all frames (up to 100) in inverse | ||
| 291 | order: | ||
| 292 | </p> | ||
| 293 | <pre class="code"> | ||
| 294 | print(profile.dumpstack(thread, "l\n", 10)) | ||
| 295 | print(profile.dumpstack(thread, "lZ;", -100)) | ||
| 296 | </pre> | ||
| 297 | |||
| 298 | <h2 id="ll_c_api">Low-level C API</h2> | ||
| 299 | <p> | ||
| 300 | The profiler can be controlled directly from C code, e.g. for | ||
| 301 | use by IDEs. The declarations are in <tt>"luajit.h"</tt> (see | ||
| 302 | <a href="ext_c_api.html">Lua/C API</a> extensions). | ||
| 303 | </p> | ||
| 304 | |||
| 305 | <h3 id="luaJIT_profile_start"><tt>luaJIT_profile_start(L, mode, cb, data)</tt> | ||
| 306 | — Start profiler</h3> | ||
| 307 | <p> | ||
| 308 | This function starts the profiler. <a href="#profile_start">See | ||
| 309 | above</a> for a description of the <tt>mode</tt> argument. | ||
| 310 | </p> | ||
| 311 | <p> | ||
| 312 | The <tt>cb</tt> argument is a callback function with the following | ||
| 313 | declaration: | ||
| 314 | </p> | ||
| 315 | <pre class="code"> | ||
| 316 | typedef void (*luaJIT_profile_callback)(void *data, lua_State *L, | ||
| 317 | int samples, int vmstate); | ||
| 318 | </pre> | ||
| 319 | <p> | ||
| 320 | <tt>data</tt> is available for use by the callback. <tt>L</tt> is the | ||
| 321 | state that holds the stack to sample for profiling. Note: do | ||
| 322 | <em>not</em> modify this stack or call functions on this stack — | ||
| 323 | use a separate coroutine for this purpose. <a href="#profile_start">See | ||
| 324 | above</a> for a description of <tt>samples</tt> and <tt>vmstate</tt>. | ||
| 325 | </p> | ||
| 326 | |||
| 327 | <h3 id="luaJIT_profile_stop"><tt>luaJIT_profile_stop(L)</tt> | ||
| 328 | — Stop profiler</h3> | ||
| 329 | <p> | ||
| 330 | This function stops the profiler. | ||
| 331 | </p> | ||
| 332 | |||
| 333 | <h3 id="luaJIT_profile_dumpstack"><tt>p = luaJIT_profile_dumpstack(L, fmt, depth, len)</tt> | ||
| 334 | — Dump stack </h3> | ||
| 335 | <p> | ||
| 336 | This function allows taking stack dumps in an efficient manner. | ||
| 337 | <a href="#profile_dump">See above</a> for a description of <tt>fmt</tt> | ||
| 338 | and <tt>depth</tt>. | ||
| 339 | </p> | ||
| 340 | <p> | ||
| 341 | This function returns a <tt>const char *</tt> pointing to a | ||
| 342 | private string buffer of the profiler. The <tt>int *len</tt> | ||
| 343 | argument returns the length of the output string. The buffer is | ||
| 344 | overwritten on the next call and deallocated when the profiler stops. | ||
| 345 | You either need to consume the content immediately or copy it for later | ||
| 346 | use. | ||
| 347 | </p> | ||
| 348 | <br class="flush"> | ||
| 349 | </div> | ||
| 350 | <div id="foot"> | ||
| 351 | <hr class="hide"> | ||
| 352 | Copyright © 2005-2026 | ||
| 353 | <span class="noprint"> | ||
| 354 | · | ||
| 355 | <a href="contact.html">Contact</a> | ||
| 356 | </span> | ||
| 357 | </div> | ||
| 358 | </body> | ||
| 359 | </html> | ||
diff --git a/doc/extensions.html b/doc/extensions.html index 38b2c470..16e88505 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-2026"> | 6 | <meta name="Copyright" content="Copyright (C) 2005-2026"> |
| 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> |
| @@ -148,13 +160,33 @@ passes any arguments after the error function to the function | |||
| 148 | which is called in a protected context. | 160 | which is called in a protected context. |
| 149 | </p> | 161 | </p> |
| 150 | 162 | ||
| 151 | <h3 id="load"><tt>loadfile()</tt> etc. handle UTF-8 source code</h3> | 163 | <h3 id="load"><tt>load*()</tt> handle UTF-8 source code</h3> |
| 152 | <p> | 164 | <p> |
| 153 | Non-ASCII characters are handled transparently by the Lua source code parser. | 165 | Non-ASCII characters are handled transparently by the Lua source code parser. |
| 154 | This allows the use of UTF-8 characters in identifiers and strings. | 166 | This allows the use of UTF-8 characters in identifiers and strings. |
| 155 | A UTF-8 BOM is skipped at the start of the source code. | 167 | A UTF-8 BOM is skipped at the start of the source code. |
| 156 | </p> | 168 | </p> |
| 157 | 169 | ||
| 170 | <h3 id="load_mode"><tt>load*()</tt> add a mode parameter</h3> | ||
| 171 | <p> | ||
| 172 | As an extension from Lua 5.2, the functions <tt>loadstring()</tt>, | ||
| 173 | <tt>loadfile()</tt> and (new) <tt>load()</tt> add an optional | ||
| 174 | <tt>mode</tt> parameter. | ||
| 175 | </p> | ||
| 176 | <p> | ||
| 177 | The default mode string is <tt>"bt"</tt>, which allows loading of both | ||
| 178 | source code and bytecode. Use <tt>"t"</tt> to allow only source code | ||
| 179 | or <tt>"b"</tt> to allow only bytecode to be loaded. | ||
| 180 | </p> | ||
| 181 | <p> | ||
| 182 | By default, the <tt>load*</tt> functions generate the native bytecode format. | ||
| 183 | For cross-compilation purposes, add <tt>W</tt> to the mode string to | ||
| 184 | force the 32 bit format and <tt>X</tt> to force the 64 bit format. | ||
| 185 | Add both to force the opposite format. Note that non-native bytecode | ||
| 186 | generated by <tt>load*</tt> cannot be run, but can still be passed | ||
| 187 | to <tt>string.dump</tt>. | ||
| 188 | </p> | ||
| 189 | |||
| 158 | <h3 id="tostring"><tt>tostring()</tt> etc. canonicalize NaN and ±Inf</h3> | 190 | <h3 id="tostring"><tt>tostring()</tt> etc. canonicalize NaN and ±Inf</h3> |
| 159 | <p> | 191 | <p> |
| 160 | All number-to-string conversions consistently convert non-finite numbers | 192 | All number-to-string conversions consistently convert non-finite numbers |
| @@ -166,7 +198,7 @@ in <tt>"-inf"</tt>. | |||
| 166 | <h3 id="tonumber"><tt>tonumber()</tt> etc. use builtin string to number conversion</h3> | 198 | <h3 id="tonumber"><tt>tonumber()</tt> etc. use builtin string to number conversion</h3> |
| 167 | <p> | 199 | <p> |
| 168 | All string-to-number conversions consistently convert integer and | 200 | All string-to-number conversions consistently convert integer and |
| 169 | floating-point inputs in decimal and hexadecimal on all platforms. | 201 | floating-point inputs in decimal, hexadecimal and binary on all platforms. |
| 170 | <tt>strtod()</tt> is <em>not</em> used anymore, which avoids numerous | 202 | <tt>strtod()</tt> is <em>not</em> used anymore, which avoids numerous |
| 171 | problems with poor C library implementations. The builtin conversion | 203 | problems with poor C library implementations. The builtin conversion |
| 172 | function provides full precision according to the IEEE-754 standard, it | 204 | function provides full precision according to the IEEE-754 standard, it |
| @@ -174,21 +206,58 @@ works independently of the current locale and it supports hex floating-point | |||
| 174 | numbers (e.g. <tt>0x1.5p-3</tt>). | 206 | numbers (e.g. <tt>0x1.5p-3</tt>). |
| 175 | </p> | 207 | </p> |
| 176 | 208 | ||
| 177 | <h3 id="string_dump"><tt>string.dump(f [,strip])</tt> generates portable bytecode</h3> | 209 | <h3 id="string_dump"><tt>string.dump(f [,mode])</tt> generates portable bytecode</h3> |
| 178 | <p> | 210 | <p> |
| 179 | An extra argument has been added to <tt>string.dump()</tt>. If set to | 211 | An extra argument has been added to <tt>string.dump()</tt>. If set to |
| 180 | <tt>true</tt>, 'stripped' bytecode without debug information is | 212 | <tt>true</tt> or to a string which contains the character <tt>s</tt>, |
| 181 | generated. This speeds up later bytecode loading and reduces memory | 213 | 'stripped' bytecode without debug information is generated. This speeds |
| 182 | usage. See also the | 214 | up later bytecode loading and reduces memory usage. See also the |
| 183 | <a href="running.html#opt_b"><tt>-b</tt> command line option</a>. | 215 | <a href="running.html#opt_b"><tt>-b</tt> command line option</a>. |
| 184 | </p> | 216 | </p> |
| 185 | <p> | 217 | <p> |
| 186 | The generated bytecode is portable and can be loaded on any architecture | 218 | The generated bytecode is portable and can be loaded on any architecture |
| 187 | that LuaJIT supports, independent of word size or endianess. However, the | 219 | that LuaJIT supports. However, the bytecode compatibility versions must |
| 188 | bytecode compatibility versions must match. Bytecode stays compatible | 220 | match. Bytecode only stays compatible within a major+minor version |
| 189 | for dot releases (x.y.0 → x.y.1), but may change with major or | 221 | (x.y.aaa → x.y.bbb), except for development branches. Foreign bytecode |
| 190 | minor releases (2.0 → 2.1) or between any beta release. Foreign | 222 | (e.g. from Lua 5.1) is incompatible and cannot be loaded. |
| 191 | bytecode (e.g. from Lua 5.1) is incompatible and cannot be loaded. | 223 | </p> |
| 224 | <p> | ||
| 225 | Note: <tt>LJ_GC64</tt> mode requires a different frame layout, which implies | ||
| 226 | a different, incompatible bytecode format between 32 bit and 64 bit ports. | ||
| 227 | This may be rectified in the future. In the meantime, use the <tt>W</tt> | ||
| 228 | and </tt>X</tt> <a href="#load_mode">modes of the <tt>load*</tt> functions</a> | ||
| 229 | for cross-compilation purposes. | ||
| 230 | </p> | ||
| 231 | <p> | ||
| 232 | Due to VM hardening, bytecode is not deterministic. Add <tt>d</tt> to the | ||
| 233 | mode string to dump it in a deterministic manner: identical source code | ||
| 234 | always gives a byte-for-byte identical bytecode dump. This feature is | ||
| 235 | mainly useful for reproducible builds. | ||
| 236 | </p> | ||
| 237 | |||
| 238 | <h3 id="table_new"><tt>table.new(narray, nhash)</tt> allocates a pre-sized table</h3> | ||
| 239 | <p> | ||
| 240 | An extra library function <tt>table.new()</tt> can be made available via | ||
| 241 | <tt>require("table.new")</tt>. This creates a pre-sized table, just like | ||
| 242 | the C API equivalent <tt>lua_createtable()</tt>. This is useful for big | ||
| 243 | tables if the final table size is known and automatic table resizing is | ||
| 244 | too expensive. | ||
| 245 | </p> | ||
| 246 | |||
| 247 | <h3 id="table_clear"><tt>table.clear(tab)</tt> clears a table</h3> | ||
| 248 | <p> | ||
| 249 | An extra library function <tt>table.clear()</tt> can be made available | ||
| 250 | via <tt>require("table.clear")</tt>. This clears all keys and values | ||
| 251 | from a table, but preserves the allocated array/hash sizes. This is | ||
| 252 | useful when a table, which is linked from multiple places, needs to be | ||
| 253 | cleared and/or when recycling a table for use by the same context. This | ||
| 254 | avoids managing backlinks, saves an allocation and the overhead of | ||
| 255 | incremental array/hash part growth. | ||
| 256 | </p> | ||
| 257 | <p> | ||
| 258 | Please note, this function is meant for very specific situations. In most | ||
| 259 | cases it's better to replace the (usually single) link with a new table | ||
| 260 | and let the GC do its work. | ||
| 192 | </p> | 261 | </p> |
| 193 | 262 | ||
| 194 | <h3 id="math_random">Enhanced PRNG for <tt>math.random()</tt></h3> | 263 | <h3 id="math_random">Enhanced PRNG for <tt>math.random()</tt></h3> |
| @@ -196,7 +265,7 @@ bytecode (e.g. from Lua 5.1) is incompatible and cannot be loaded. | |||
| 196 | LuaJIT uses a Tausworthe PRNG with period 2^223 to implement | 265 | LuaJIT uses a Tausworthe PRNG with period 2^223 to implement |
| 197 | <tt>math.random()</tt> and <tt>math.randomseed()</tt>. The quality of | 266 | <tt>math.random()</tt> and <tt>math.randomseed()</tt>. The quality of |
| 198 | the PRNG results is much superior compared to the standard Lua | 267 | the PRNG results is much superior compared to the standard Lua |
| 199 | implementation, which uses the platform-specific ANSI rand(). | 268 | implementation, which uses the platform-specific ANSI <tt>rand()</tt>. |
| 200 | </p> | 269 | </p> |
| 201 | <p> | 270 | <p> |
| 202 | The PRNG generates the same sequences from the same seeds on all | 271 | The PRNG generates the same sequences from the same seeds on all |
| @@ -207,6 +276,10 @@ It's correctly scaled up and rounded for <tt>math.random(n [,m])</tt> to | |||
| 207 | preserve uniformity. | 276 | preserve uniformity. |
| 208 | </p> | 277 | </p> |
| 209 | <p> | 278 | <p> |
| 279 | Call <tt>math.randomseed()</tt> without any arguments to seed it from | ||
| 280 | system entropy. | ||
| 281 | </p> | ||
| 282 | <p> | ||
| 210 | Important: Neither this nor any other PRNG based on the simplistic | 283 | Important: Neither this nor any other PRNG based on the simplistic |
| 211 | <tt>math.random()</tt> API is suitable for cryptographic use. | 284 | <tt>math.random()</tt> API is suitable for cryptographic use. |
| 212 | </p> | 285 | </p> |
| @@ -268,6 +341,26 @@ indexes for varargs.</li> | |||
| 268 | <li><tt>debug.getupvalue()</tt> and <tt>debug.setupvalue()</tt> handle | 341 | <li><tt>debug.getupvalue()</tt> and <tt>debug.setupvalue()</tt> handle |
| 269 | C functions.</li> | 342 | C functions.</li> |
| 270 | <li><tt>debug.upvalueid()</tt> and <tt>debug.upvaluejoin()</tt>.</li> | 343 | <li><tt>debug.upvalueid()</tt> and <tt>debug.upvaluejoin()</tt>.</li> |
| 344 | <li>Lua/C API extensions: | ||
| 345 | <tt>lua_version()</tt> | ||
| 346 | <tt>lua_upvalueid()</tt> | ||
| 347 | <tt>lua_upvaluejoin()</tt> | ||
| 348 | <tt>lua_loadx()</tt> | ||
| 349 | <tt>lua_copy()</tt> | ||
| 350 | <tt>lua_tonumberx()</tt> | ||
| 351 | <tt>lua_tointegerx()</tt> | ||
| 352 | <tt>luaL_fileresult()</tt> | ||
| 353 | <tt>luaL_execresult()</tt> | ||
| 354 | <tt>luaL_loadfilex()</tt> | ||
| 355 | <tt>luaL_loadbufferx()</tt> | ||
| 356 | <tt>luaL_traceback()</tt> | ||
| 357 | <tt>luaL_setfuncs()</tt> | ||
| 358 | <tt>luaL_pushmodule()</tt> | ||
| 359 | <tt>luaL_newlibtable()</tt> | ||
| 360 | <tt>luaL_newlib()</tt> | ||
| 361 | <tt>luaL_testudata()</tt> | ||
| 362 | <tt>luaL_setmetatable()</tt> | ||
| 363 | </li> | ||
| 271 | <li>Command line option <tt>-E</tt>.</li> | 364 | <li>Command line option <tt>-E</tt>.</li> |
| 272 | <li>Command line checks <tt>__tostring</tt> for errors.</li> | 365 | <li>Command line checks <tt>__tostring</tt> for errors.</li> |
| 273 | </ul> | 366 | </ul> |
| @@ -293,6 +386,8 @@ exit status.</li> | |||
| 293 | <li><tt>debug.setmetatable()</tt> returns object.</li> | 386 | <li><tt>debug.setmetatable()</tt> returns object.</li> |
| 294 | <li><tt>debug.getuservalue()</tt> and <tt>debug.setuservalue()</tt>.</li> | 387 | <li><tt>debug.getuservalue()</tt> and <tt>debug.setuservalue()</tt>.</li> |
| 295 | <li>Remove <tt>math.mod()</tt>, <tt>string.gfind()</tt>.</li> | 388 | <li>Remove <tt>math.mod()</tt>, <tt>string.gfind()</tt>.</li> |
| 389 | <li><tt>package.searchers</tt>.</li> | ||
| 390 | <li><tt>module()</tt> returns the module table.</li> | ||
| 296 | </ul> | 391 | </ul> |
| 297 | <p> | 392 | <p> |
| 298 | Note: this provides only partial compatibility with Lua 5.2 at the | 393 | Note: this provides only partial compatibility with Lua 5.2 at the |
| @@ -301,6 +396,21 @@ Lua 5.1, which prevents implementing features that would otherwise | |||
| 301 | break the Lua/C API and ABI (e.g. <tt>_ENV</tt>). | 396 | break the Lua/C API and ABI (e.g. <tt>_ENV</tt>). |
| 302 | </p> | 397 | </p> |
| 303 | 398 | ||
| 399 | <h2 id="lua53">Extensions from Lua 5.3</h2> | ||
| 400 | <p> | ||
| 401 | LuaJIT supports some extensions from Lua 5.3: | ||
| 402 | <ul> | ||
| 403 | <li>Unicode escape <tt>'\u{XX...}'</tt> embeds the UTF-8 encoding in string literals.</li> | ||
| 404 | <li>The argument table <tt>arg</tt> can be read (and modified) by <tt>LUA_INIT</tt> and <tt>-e</tt> chunks.</li> | ||
| 405 | <li><tt>io.read()</tt> and <tt>file:read()</tt> accept formats with or without a leading <tt>*</tt>.</li> | ||
| 406 | <li><tt>assert()</tt> accepts any type of error object.</li> | ||
| 407 | <li><tt>table.move(a1, f, e, t [,a2])</tt>.</li> | ||
| 408 | <li><tt>coroutine.isyieldable()</tt>.</li> | ||
| 409 | <li>Lua/C API extensions: | ||
| 410 | <tt>lua_isyieldable()</tt> | ||
| 411 | </li> | ||
| 412 | </ul> | ||
| 413 | |||
| 304 | <h2 id="exceptions">C++ Exception Interoperability</h2> | 414 | <h2 id="exceptions">C++ Exception Interoperability</h2> |
| 305 | <p> | 415 | <p> |
| 306 | LuaJIT has built-in support for interoperating with C++ exceptions. | 416 | LuaJIT has built-in support for interoperating with C++ exceptions. |
| @@ -314,26 +424,21 @@ the toolchain used to compile LuaJIT: | |||
| 314 | <td class="excinterop">Interoperability</td> | 424 | <td class="excinterop">Interoperability</td> |
| 315 | </tr> | 425 | </tr> |
| 316 | <tr class="odd separate"> | 426 | <tr class="odd separate"> |
| 317 | <td class="excplatform">POSIX/x64, DWARF2 unwinding</td> | 427 | <td class="excplatform">External frame unwinding</td> |
| 318 | <td class="exccompiler">GCC 4.3+</td> | 428 | <td class="exccompiler">GCC, Clang, MSVC</td> |
| 319 | <td class="excinterop"><b style="color: #00a000;">Full</b></td> | 429 | <td class="excinterop"><b style="color: #00a000;">Full</b></td> |
| 320 | </tr> | 430 | </tr> |
| 321 | <tr class="even"> | 431 | <tr class="even"> |
| 322 | <td class="excplatform">Other platforms, DWARF2 unwinding</td> | 432 | <td class="excplatform">Internal frame unwinding + DWARF2</td> |
| 323 | <td class="exccompiler">GCC</td> | 433 | <td class="exccompiler">GCC, Clang</td> |
| 324 | <td class="excinterop"><b style="color: #c06000;">Limited</b></td> | 434 | <td class="excinterop"><b style="color: #c06000;">Limited</b></td> |
| 325 | </tr> | 435 | </tr> |
| 326 | <tr class="odd"> | 436 | <tr class="odd"> |
| 327 | <td class="excplatform">Windows/x64</td> | 437 | <td class="excplatform">Windows 64 bit</td> |
| 328 | <td class="exccompiler">MSVC</td> | 438 | <td class="exccompiler">non-MSVC</td> |
| 329 | <td class="excinterop"><b style="color: #00a000;">Full</b></td> | 439 | <td class="excinterop"><b style="color: #c06000;">Limited</b></td> |
| 330 | </tr> | 440 | </tr> |
| 331 | <tr class="even"> | 441 | <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> | 442 | <td class="excplatform">Other platforms</td> |
| 338 | <td class="exccompiler">Other compilers</td> | 443 | <td class="exccompiler">Other compilers</td> |
| 339 | <td class="excinterop"><b style="color: #a00000;">No</b></td> | 444 | <td class="excinterop"><b style="color: #a00000;">No</b></td> |
| @@ -352,9 +457,7 @@ the toolchain used to compile LuaJIT: | |||
| 352 | on the C stack. The contents of the C++ exception object | 457 | on the C stack. The contents of the C++ exception object |
| 353 | pass through unmodified.</li> | 458 | pass through unmodified.</li> |
| 354 | <li>Lua errors can be caught on the C++ side with <tt>catch(...)</tt>. | 459 | <li>Lua errors can be caught on the C++ side with <tt>catch(...)</tt>. |
| 355 | The corresponding Lua error message can be retrieved from the Lua stack.<br> | 460 | The corresponding Lua error message can be retrieved from the Lua stack.</li> |
| 356 | For MSVC for Windows 64 bit this requires compilation of your C++ code | ||
| 357 | with <tt>/EHa</tt>.</li> | ||
| 358 | <li>Throwing Lua errors across C++ frames is safe. C++ destructors | 461 | <li>Throwing Lua errors across C++ frames is safe. C++ destructors |
| 359 | will be called.</li> | 462 | will be called.</li> |
| 360 | </ul> | 463 | </ul> |
| @@ -384,14 +487,6 @@ C++ destructors.</li> | |||
| 384 | <li>Lua errors <b>cannot</b> be caught on the C++ side.</li> | 487 | <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 | 488 | <li>Throwing Lua errors across C++ frames will <b>not</b> call |
| 386 | C++ destructors.</li> | 489 | 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> | 490 | </ul> |
| 396 | <br class="flush"> | 491 | <br class="flush"> |
| 397 | </div> | 492 | </div> |
diff --git a/doc/install.html b/doc/install.html index f9c326d8..0fdde485 100644 --- a/doc/install.html +++ b/doc/install.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>Installation</title> | 4 | <title>Installation</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-2026"> | 6 | <meta name="Copyright" content="Copyright (C) 2005-2026"> |
| 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"> |
| @@ -60,9 +60,13 @@ td.compatx { | |||
| 60 | <a href="ext_ffi_semantics.html">FFI Semantics</a> | 60 | <a href="ext_ffi_semantics.html">FFI Semantics</a> |
| 61 | </li></ul> | 61 | </li></ul> |
| 62 | </li><li> | 62 | </li><li> |
| 63 | <a href="ext_buffer.html">String Buffers</a> | ||
| 64 | </li><li> | ||
| 63 | <a href="ext_jit.html">jit.* Library</a> | 65 | <a href="ext_jit.html">jit.* Library</a> |
| 64 | </li><li> | 66 | </li><li> |
| 65 | <a href="ext_c_api.html">Lua/C API</a> | 67 | <a href="ext_c_api.html">Lua/C API</a> |
| 68 | </li><li> | ||
| 69 | <a href="ext_profiler.html">Profiler</a> | ||
| 66 | </li></ul> | 70 | </li></ul> |
| 67 | </li><li> | 71 | </li><li> |
| 68 | <a href="https://luajit.org/status.html">Status <span class="ext">»</span></a> | 72 | <a href="https://luajit.org/status.html">Status <span class="ext">»</span></a> |
| @@ -113,7 +117,7 @@ hold all user-configurable settings: | |||
| 113 | <li><tt>Makefile</tt> has settings for <b>installing</b> LuaJIT (POSIX | 117 | <li><tt>Makefile</tt> has settings for <b>installing</b> LuaJIT (POSIX |
| 114 | only).</li> | 118 | only).</li> |
| 115 | <li><tt>src/Makefile</tt> has settings for <b>compiling</b> LuaJIT | 119 | <li><tt>src/Makefile</tt> has settings for <b>compiling</b> LuaJIT |
| 116 | under POSIX, MinGW or Cygwin.</li> | 120 | under POSIX or MinGW.</li> |
| 117 | <li><tt>src/msvcbuild.bat</tt> has settings for compiling LuaJIT with | 121 | <li><tt>src/msvcbuild.bat</tt> has settings for compiling LuaJIT with |
| 118 | MSVC (Visual Studio).</li> | 122 | MSVC (Visual Studio).</li> |
| 119 | </ul> | 123 | </ul> |
| @@ -121,6 +125,13 @@ MSVC (Visual Studio).</li> | |||
| 121 | Please read the instructions given in these files, before changing | 125 | Please read the instructions given in these files, before changing |
| 122 | any settings. | 126 | any settings. |
| 123 | </p> | 127 | </p> |
| 128 | <p> | ||
| 129 | All LuaJIT 64 bit ports use 64 bit GC objects by default (<tt>LJ_GC64</tt>). | ||
| 130 | For x64, you can select the old 32-on-64 bit mode by adding | ||
| 131 | <tt>XCFLAGS=-DLUAJIT_DISABLE_GC64</tt> to the make command. | ||
| 132 | Please check the note about the | ||
| 133 | <a href="extensions.html#string_dump">bytecode format</a> differences, too. | ||
| 134 | </p> | ||
| 124 | 135 | ||
| 125 | <h2 id="posix">POSIX Systems (Linux, macOS, *BSD etc.)</h2> | 136 | <h2 id="posix">POSIX Systems (Linux, macOS, *BSD etc.)</h2> |
| 126 | <h3>Prerequisites</h3> | 137 | <h3>Prerequisites</h3> |
| @@ -154,9 +165,12 @@ You can add an extra prefix to the search paths by appending the | |||
| 154 | make PREFIX=/home/myself/lj2 | 165 | make PREFIX=/home/myself/lj2 |
| 155 | </pre> | 166 | </pre> |
| 156 | <p> | 167 | <p> |
| 157 | Please use the LuaJIT 2.1 branch to compile for | 168 | Note for macOS: you <b>must</b> set the <tt>MACOSX_DEPLOYMENT_TARGET</tt> |
| 158 | <b id="osx">macOS (OSX)</b>. | 169 | environment variable to a value supported by your toolchain: |
| 159 | </p> | 170 | </p> |
| 171 | <pre class="code"> | ||
| 172 | MACOSX_DEPLOYMENT_TARGET=XX.YY make | ||
| 173 | </pre> | ||
| 160 | <h3>Installing LuaJIT</h3> | 174 | <h3>Installing LuaJIT</h3> |
| 161 | <p> | 175 | <p> |
| 162 | The top-level Makefile installs LuaJIT by default under | 176 | The top-level Makefile installs LuaJIT by default under |
| @@ -181,15 +195,13 @@ Obviously the prefixes given during build and installation need to be the same. | |||
| 181 | <h2 id="windows">Windows Systems</h2> | 195 | <h2 id="windows">Windows Systems</h2> |
| 182 | <h3>Prerequisites</h3> | 196 | <h3>Prerequisites</h3> |
| 183 | <p> | 197 | <p> |
| 184 | Either install one of the open source SDKs | 198 | Either install the open source SDK <a href="http://mingw.org/"><span class="ext">»</span> MinGW</a>, |
| 185 | (<a href="http://mingw.org/"><span class="ext">»</span> MinGW</a> or | 199 | which comes with a modified GCC plus the required development headers. |
| 186 | <a href="https://www.cygwin.com/"><span class="ext">»</span> Cygwin</a>), which come with a modified | ||
| 187 | GCC plus the required development headers. | ||
| 188 | Or install Microsoft's Visual Studio (MSVC). | 200 | Or install Microsoft's Visual Studio (MSVC). |
| 189 | </p> | 201 | </p> |
| 190 | <h3>Building with MSVC</h3> | 202 | <h3>Building with MSVC</h3> |
| 191 | <p> | 203 | <p> |
| 192 | Open a "Visual Studio Command Prompt" (either x86 or x64), <tt>cd</tt> to the | 204 | Open a "Visual Studio Command Prompt" (x86, x64 or ARM64), <tt>cd</tt> to the |
| 193 | directory with the source code and run these commands: | 205 | directory with the source code and run these commands: |
| 194 | </p> | 206 | </p> |
| 195 | <pre class="code"> | 207 | <pre class="code"> |
| @@ -200,9 +212,12 @@ msvcbuild | |||
| 200 | Check the <tt>msvcbuild.bat</tt> file for more options. | 212 | Check the <tt>msvcbuild.bat</tt> file for more options. |
| 201 | Then follow the installation instructions below. | 213 | Then follow the installation instructions below. |
| 202 | </p> | 214 | </p> |
| 203 | <h3>Building with MinGW or Cygwin</h3> | ||
| 204 | <p> | 215 | <p> |
| 205 | Open a command prompt window and make sure the MinGW or Cygwin programs | 216 | For an x64 to ARM64 cross-build run this first: <tt>vcvarsall.bat x64_arm64</tt> |
| 217 | </p> | ||
| 218 | <h3>Building with MinGW</h3> | ||
| 219 | <p> | ||
| 220 | Open a command prompt window and make sure the MinGW programs | ||
| 206 | are in your path. Then <tt>cd</tt> to the directory of the git repository. | 221 | are in your path. Then <tt>cd</tt> to the directory of the git repository. |
| 207 | Then run this command for MinGW: | 222 | Then run this command for MinGW: |
| 208 | </p> | 223 | </p> |
| @@ -210,12 +225,6 @@ Then run this command for MinGW: | |||
| 210 | mingw32-make | 225 | mingw32-make |
| 211 | </pre> | 226 | </pre> |
| 212 | <p> | 227 | <p> |
| 213 | Or this command for Cygwin: | ||
| 214 | </p> | ||
| 215 | <pre class="code"> | ||
| 216 | make | ||
| 217 | </pre> | ||
| 218 | <p> | ||
| 219 | Then follow the installation instructions below. | 228 | Then follow the installation instructions below. |
| 220 | </p> | 229 | </p> |
| 221 | <h3>Installing LuaJIT</h3> | 230 | <h3>Installing LuaJIT</h3> |
| @@ -232,31 +241,53 @@ absolute path names — all modules are loaded relative to the | |||
| 232 | directory where <tt>luajit.exe</tt> is installed | 241 | directory where <tt>luajit.exe</tt> is installed |
| 233 | (see <tt>src/luaconf.h</tt>). | 242 | (see <tt>src/luaconf.h</tt>). |
| 234 | </p> | 243 | </p> |
| 244 | <p> | ||
| 245 | The final directory layout should look like this: | ||
| 246 | </p> | ||
| 247 | <pre class="code"> | ||
| 248 | ├── luajit.exe | ||
| 249 | ├── lua51.dll | ||
| 250 | ├── <- put your own classic Lua/C API modules (*.dll) here | ||
| 251 | └── lua | ||
| 252 | ├── <- put your own Lua modules (*.lua) here | ||
| 253 | └── jit | ||
| 254 | ├── bc.lua | ||
| 255 | └── (etc …) | ||
| 256 | </pre> | ||
| 235 | 257 | ||
| 236 | <h2 id="cross">Cross-compiling LuaJIT</h2> | 258 | <h2 id="cross">Cross-compiling LuaJIT</h2> |
| 237 | <p> | 259 | <p> |
| 260 | First, let's clear up some terminology: | ||
| 261 | </p> | ||
| 262 | <ul> | ||
| 263 | <li>Host: This is your development system, usually based on a x64 or x86 CPU.</li> | ||
| 264 | <li>Target: This is the target system you want LuaJIT to run on, e.g. Android/ARM.</li> | ||
| 265 | <li>Toolchain: This comprises a C compiler, linker, assembler and a matching C library.</li> | ||
| 266 | <li>Host (or system) toolchain: This is the toolchain used to build native binaries for your host system.</li> | ||
| 267 | <li>Cross-compile toolchain: This is the toolchain used to build binaries for the target system. They can only be run on the target system.</li> | ||
| 268 | </ul> | ||
| 269 | <p> | ||
| 238 | The GNU Makefile-based build system allows cross-compiling on any host | 270 | The GNU Makefile-based build system allows cross-compiling on any host |
| 239 | for any supported target, as long as both architectures have the same | 271 | for any supported target: |
| 240 | pointer size. If you want to cross-compile to any 32 bit target on an | ||
| 241 | x64 OS, you need to install the multilib development package (e.g. | ||
| 242 | <tt>libc6-dev-i386</tt> on Debian/Ubuntu) and build a 32 bit host part | ||
| 243 | (<tt>HOST_CC="gcc -m32"</tt>). On some distro versions, multilib conflicts | ||
| 244 | with cross-compilers. The workaround is to install the x86 cross-compiler | ||
| 245 | package <tt>gcc-i686-linux-gnu</tt> and use it to build the host part | ||
| 246 | (<tt>HOST_CC=i686-linux-gnu-gcc</tt>). | ||
| 247 | </p> | 272 | </p> |
| 273 | <ul> | ||
| 274 | <li>Yes, you need a toolchain for both your host <em>and</em> your target!</li> | ||
| 275 | <li>Both host and target architectures must have the same pointer size.</li> | ||
| 276 | <li>E.g. if you want to cross-compile to a 32 bit target on a 64 bit host, you need to install the multilib development package (e.g. <tt>libc6-dev-i386</tt> on Debian/Ubuntu) and build a 32 bit host part (<tt>HOST_CC="gcc -m32"</tt>).</li> | ||
| 277 | <li>On some distro versions, multilib conflicts with cross-compilers. The workaround is to install the x86 cross-compiler package <tt>gcc-i686-linux-gnu</tt> and use it to build the host part (<tt>HOST_CC=i686-linux-gnu-gcc</tt>).</li> | ||
| 278 | <li>64 bit targets always require compilation on a 64 bit host.</li> | ||
| 279 | </ul> | ||
| 248 | <p> | 280 | <p> |
| 249 | You need to specify <tt>TARGET_SYS</tt> whenever the host OS and the | 281 | You need to specify <tt>TARGET_SYS</tt> whenever the host OS and the |
| 250 | target OS differ, or you'll get assembler or linker errors. E.g. if | 282 | target OS differ, or you'll get assembler or linker errors: |
| 251 | you're compiling on a Windows or macOS host for embedded Linux or Android, | ||
| 252 | you need to add <tt>TARGET_SYS=Linux</tt> to the examples below. For a | ||
| 253 | minimal target OS, you may need to disable the built-in allocator in | ||
| 254 | <tt>src/Makefile</tt> and use <tt>TARGET_SYS=Other</tt>. Don't forget to | ||
| 255 | specify the same <tt>TARGET_SYS</tt> for the install step, too. | ||
| 256 | </p> | 283 | </p> |
| 284 | <ul> | ||
| 285 | <li>E.g. if you're compiling on a Windows or macOS host for embedded Linux or Android, you need to add <tt>TARGET_SYS=Linux</tt> to the examples below.</li> | ||
| 286 | <li>For a minimal target OS, you may need to disable the built-in allocator in <tt>src/Makefile</tt> and use <tt>TARGET_SYS=Other</tt>.</li> | ||
| 287 | <li>Don't forget to specify the same <tt>TARGET_SYS</tt> for the install step, too.</li> | ||
| 288 | </ul> | ||
| 257 | <p> | 289 | <p> |
| 258 | The examples below only show some popular targets — please check | 290 | Here are some examples where host and target have the same CPU: |
| 259 | the comments in <tt>src/Makefile</tt> for more details. | ||
| 260 | </p> | 291 | </p> |
| 261 | <pre class="code"> | 292 | <pre class="code"> |
| 262 | # Cross-compile to a 32 bit binary on a multilib x64 OS | 293 | # Cross-compile to a 32 bit binary on a multilib x64 OS |
| @@ -274,34 +305,44 @@ use the canonical toolchain triplets for Linux. | |||
| 274 | </p> | 305 | </p> |
| 275 | <p> | 306 | <p> |
| 276 | Since there's often no easy way to detect CPU features at runtime, it's | 307 | Since there's often no easy way to detect CPU features at runtime, it's |
| 277 | important to compile with the proper CPU or architecture settings. You | 308 | important to compile with the proper CPU or architecture settings: |
| 278 | can specify these when building the toolchain yourself. Or add | 309 | </o> |
| 279 | <tt>-mcpu=...</tt> or <tt>-march=...</tt> to <tt>TARGET_CFLAGS</tt>. For | 310 | <ul> |
| 280 | ARM it's important to have the correct <tt>-mfloat-abi=...</tt> setting, | 311 | <li>The best way to get consistent results is to specify the correct settings when building the toolchain yourself.</li> |
| 281 | too. Otherwise, LuaJIT may not run at the full performance of your target | 312 | <li>For a pre-built, generic toolchain add <tt>-mcpu=...</tt> or <tt>-march=...</tt> and other necessary flags to <tt>TARGET_CFLAGS</tt>.</li> |
| 282 | CPU. | 313 | <li>For ARM it's important to have the correct <tt>-mfloat-abi=...</tt> setting, too. Otherwise LuaJIT may not run at the full performance of your target CPU.</li> |
| 314 | <li>For MIPS it's important to select a supported ABI (o32 on MIPS32, n64 on MIPS64) and consistently compile your project either with hard-float or soft-float compiler settings.</li> | ||
| 315 | </ul> | ||
| 316 | <p> | ||
| 317 | Here are some examples for targets with a different CPU than the host: | ||
| 283 | </p> | 318 | </p> |
| 284 | <pre class="code"> | 319 | <pre class="code"> |
| 285 | # ARM soft-float | 320 | # ARM soft-float |
| 286 | make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabi- \ | 321 | make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabi- \ |
| 287 | TARGET_CFLAGS="-mfloat-abi=soft" | 322 | TARGET_CFLAGS="-mfloat-abi=soft" |
| 288 | 323 | ||
| 289 | # ARM soft-float ABI with VFP (example for Cortex-A8) | 324 | # ARM soft-float ABI with VFP (example for Cortex-A9) |
| 290 | make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabi- \ | 325 | make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabi- \ |
| 291 | TARGET_CFLAGS="-mcpu=cortex-a8 -mfloat-abi=softfp" | 326 | TARGET_CFLAGS="-mcpu=cortex-a9 -mfloat-abi=softfp" |
| 292 | 327 | ||
| 293 | # ARM hard-float ABI with VFP (armhf, requires recent toolchain) | 328 | # ARM hard-float ABI with VFP (armhf, most modern toolchains) |
| 294 | make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabihf- | 329 | make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabihf- |
| 295 | 330 | ||
| 331 | # ARM64 | ||
| 332 | make CROSS=aarch64-linux-gnu- | ||
| 333 | |||
| 296 | # PPC | 334 | # PPC |
| 297 | make HOST_CC="gcc -m32" CROSS=powerpc-linux-gnu- | 335 | make HOST_CC="gcc -m32" CROSS=powerpc-linux-gnu- |
| 298 | # PPC/e500v2 (fast interpreter only) | ||
| 299 | make HOST_CC="gcc -m32" CROSS=powerpc-e500v2-linux-gnuspe- | ||
| 300 | 336 | ||
| 301 | # MIPS big-endian | 337 | # MIPS32 big-endian |
| 302 | make HOST_CC="gcc -m32" CROSS=mips-linux- | 338 | make HOST_CC="gcc -m32" CROSS=mips-linux-gnu- |
| 303 | # MIPS little-endian | 339 | # MIPS32 little-endian |
| 304 | make HOST_CC="gcc -m32" CROSS=mipsel-linux- | 340 | make HOST_CC="gcc -m32" CROSS=mipsel-linux-gnu- |
| 341 | |||
| 342 | # MIPS64 big-endian | ||
| 343 | make CROSS=mips-linux- TARGET_CFLAGS="-mips64r2 -mabi=64" | ||
| 344 | # MIPS64 little-endian | ||
| 345 | make CROSS=mipsel-linux- TARGET_CFLAGS="-mips64r2 -mabi=64" | ||
| 305 | </pre> | 346 | </pre> |
| 306 | <p> | 347 | <p> |
| 307 | You can cross-compile for <b id="android">Android</b> using the <a href="https://developer.android.com/ndk/"><span class="ext">»</span> Android NDK</a>. | 348 | You can cross-compile for <b id="android">Android</b> using the <a href="https://developer.android.com/ndk/"><span class="ext">»</span> Android NDK</a>. |
| @@ -309,8 +350,17 @@ Please adapt the environment variables to match the install locations and the | |||
| 309 | desired target platform. E.g. Android 4.1 corresponds to ABI level 16. | 350 | desired target platform. E.g. Android 4.1 corresponds to ABI level 16. |
| 310 | </p> | 351 | </p> |
| 311 | <pre class="code"> | 352 | <pre class="code"> |
| 312 | # Android/ARM, armeabi-v7a (ARMv7 VFP), Android 4.1+ (JB) | 353 | # Android/ARM64, aarch64, Android 5.0+ (L) |
| 354 | NDKDIR=/opt/android/ndk | ||
| 355 | NDKBIN=$NDKDIR/toolchains/llvm/prebuilt/linux-x86_64/bin | ||
| 356 | NDKCROSS=$NDKBIN/aarch64-linux-android- | ||
| 357 | NDKCC=$NDKBIN/aarch64-linux-android21-clang | ||
| 358 | make CROSS=$NDKCROSS \ | ||
| 359 | STATIC_CC=$NDKCC DYNAMIC_CC="$NDKCC -fPIC" \ | ||
| 360 | TARGET_LD=$NDKCC TARGET_AR="$NDKBIN/llvm-ar rcus" \ | ||
| 361 | TARGET_STRIP=$NDKBIN/llvm-strip | ||
| 313 | 362 | ||
| 363 | # Android/ARM, armeabi-v7a (ARMv7 VFP), Android 4.1+ (JB) | ||
| 314 | NDKDIR=/opt/android/ndk | 364 | NDKDIR=/opt/android/ndk |
| 315 | NDKBIN=$NDKDIR/toolchains/llvm/prebuilt/linux-x86_64/bin | 365 | NDKBIN=$NDKDIR/toolchains/llvm/prebuilt/linux-x86_64/bin |
| 316 | NDKCROSS=$NDKBIN/arm-linux-androideabi- | 366 | NDKCROSS=$NDKBIN/arm-linux-androideabi- |
| @@ -321,9 +371,23 @@ make HOST_CC="gcc -m32" CROSS=$NDKCROSS \ | |||
| 321 | TARGET_STRIP=$NDKBIN/llvm-strip | 371 | TARGET_STRIP=$NDKBIN/llvm-strip |
| 322 | </pre> | 372 | </pre> |
| 323 | <p> | 373 | <p> |
| 324 | Please use the LuaJIT 2.1 branch to compile for | 374 | You can cross-compile for <b id="ios">iOS 3.0+</b> (iPhone/iPad) using the <a href="https://developer.apple.com/ios/"><span class="ext">»</span> iOS SDK</a>: |
| 325 | <b id="ios">iOS</b> (iPhone/iPad). | 375 | </p> |
| 376 | <p style="font-size: 8pt;"> | ||
| 377 | Note: <b>the JIT compiler is disabled for iOS</b>, because regular iOS Apps | ||
| 378 | are not allowed to generate code at runtime. You'll only get the performance | ||
| 379 | of the LuaJIT interpreter on iOS. This is still faster than plain Lua, but | ||
| 380 | much slower than the JIT compiler. Please complain to Apple, not me. | ||
| 381 | Or use Android. :-p | ||
| 326 | </p> | 382 | </p> |
| 383 | <pre class="code"> | ||
| 384 | # iOS/ARM64 | ||
| 385 | ISDKP=$(xcrun --sdk iphoneos --show-sdk-path) | ||
| 386 | ICC=$(xcrun --sdk iphoneos --find clang) | ||
| 387 | ISDKF="-arch arm64 -isysroot $ISDKP" | ||
| 388 | make DEFAULT_CC=clang CROSS="$(dirname $ICC)/" \ | ||
| 389 | TARGET_FLAGS="$ISDKF" TARGET_SYS=iOS | ||
| 390 | </pre> | ||
| 327 | 391 | ||
| 328 | <h3 id="consoles">Cross-compiling for consoles</h3> | 392 | <h3 id="consoles">Cross-compiling for consoles</h3> |
| 329 | <p> | 393 | <p> |
| @@ -367,15 +431,35 @@ and run the build command given in the table: | |||
| 367 | <td class="compatx"><tt>ps4build</tt></td> | 431 | <td class="compatx"><tt>ps4build</tt></td> |
| 368 | </tr> | 432 | </tr> |
| 369 | <tr class="even"> | 433 | <tr class="even"> |
| 434 | <td class="compatname"><b id="ps5">PS5</b></td> | ||
| 435 | <td class="compatbits">64</td> | ||
| 436 | <td class="compatx"><tt>ps5build</tt></td> | ||
| 437 | </tr> | ||
| 438 | <tr class="odd"> | ||
| 370 | <td class="compatname"><b id="psvita">PS Vita</b></td> | 439 | <td class="compatname"><b id="psvita">PS Vita</b></td> |
| 371 | <td class="compatbits">32</td> | 440 | <td class="compatbits">32</td> |
| 372 | <td class="compatx"><tt>psvitabuild</tt></td> | 441 | <td class="compatx"><tt>psvitabuild</tt></td> |
| 373 | </tr> | 442 | </tr> |
| 374 | <tr class="odd"> | 443 | <tr class="even"> |
| 375 | <td class="compatname"><b id="xbox360">Xbox 360</b></td> | 444 | <td class="compatname"><b id="xbox360">Xbox 360</b></td> |
| 376 | <td class="compatbits">32</td> | 445 | <td class="compatbits">32</td> |
| 377 | <td class="compatx"><tt>xedkbuild</tt></td> | 446 | <td class="compatx"><tt>xedkbuild</tt></td> |
| 378 | </tr> | 447 | </tr> |
| 448 | <tr class="odd"> | ||
| 449 | <td class="compatname"><b id="xboxone">Xbox One</b></td> | ||
| 450 | <td class="compatbits">64</td> | ||
| 451 | <td class="compatx"><tt>xb1build</tt></td> | ||
| 452 | </tr> | ||
| 453 | <tr class="even"> | ||
| 454 | <td class="compatname"><b id="nx32">Nintendo Switch NX32</b></td> | ||
| 455 | <td class="compatbits">32</td> | ||
| 456 | <td class="compatx"><tt>nxbuild</tt></td> | ||
| 457 | </tr> | ||
| 458 | <tr class="odd"> | ||
| 459 | <td class="compatname"><b id="nx64">Nintendo Switch NX64</b></td> | ||
| 460 | <td class="compatbits">64</td> | ||
| 461 | <td class="compatx"><tt>nxbuild</tt></td> | ||
| 462 | </tr> | ||
| 379 | </table> | 463 | </table> |
| 380 | <p> | 464 | <p> |
| 381 | Please check out the comments in the corresponding <tt>*.bat</tt> | 465 | Please check out the comments in the corresponding <tt>*.bat</tt> |
diff --git a/doc/luajit.html b/doc/luajit.html index 6917c548..b7c06048 100644 --- a/doc/luajit.html +++ b/doc/luajit.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>LuaJIT</title> | 4 | <title>LuaJIT</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-2026"> | 6 | <meta name="Copyright" content="Copyright (C) 2005-2026"> |
| 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"> |
| @@ -98,9 +98,13 @@ table.fcompat td { | |||
| 98 | <a href="ext_ffi_semantics.html">FFI Semantics</a> | 98 | <a href="ext_ffi_semantics.html">FFI Semantics</a> |
| 99 | </li></ul> | 99 | </li></ul> |
| 100 | </li><li> | 100 | </li><li> |
| 101 | <a href="ext_buffer.html">String Buffers</a> | ||
| 102 | </li><li> | ||
| 101 | <a href="ext_jit.html">jit.* Library</a> | 103 | <a href="ext_jit.html">jit.* Library</a> |
| 102 | </li><li> | 104 | </li><li> |
| 103 | <a href="ext_c_api.html">Lua/C API</a> | 105 | <a href="ext_c_api.html">Lua/C API</a> |
| 106 | </li><li> | ||
| 107 | <a href="ext_profiler.html">Profiler</a> | ||
| 104 | </li></ul> | 108 | </li></ul> |
| 105 | </li><li> | 109 | </li><li> |
| 106 | <a href="https://luajit.org/status.html">Status <span class="ext">»</span></a> | 110 | <a href="https://luajit.org/status.html">Status <span class="ext">»</span></a> |
| @@ -132,13 +136,13 @@ LuaJIT is Copyright © 2005-2026 Mike Pall, released under the | |||
| 132 | <tr><td><span style="font-size:90%;">Embedded</span></td><td>Android</td><td>iOS</td></tr> | 136 | <tr><td><span style="font-size:90%;">Embedded</span></td><td>Android</td><td>iOS</td></tr> |
| 133 | </table> | 137 | </table> |
| 134 | <table class="feature os os3"> | 138 | <table class="feature os os3"> |
| 135 | <tr><td>PS3</td><td>PS4</td><td>PS Vita</td><td>Xbox 360</td></tr> | 139 | <tr><td>PS3</td><td>PS4<br>PS5</td><td>PS Vita</td><td>Xbox 360</td><td>Xbox One</td><td>Nintendo<br>Switch</td></tr> |
| 136 | </table> | 140 | </table> |
| 137 | <table class="feature compiler"> | 141 | <table class="feature compiler"> |
| 138 | <tr><td>GCC</td><td>CLANG<br>LLVM</td><td>MSVC</td></tr> | 142 | <tr><td>GCC</td><td>Clang<br>LLVM</td><td>MSVC</td></tr> |
| 139 | </table> | 143 | </table> |
| 140 | <table class="feature cpu"> | 144 | <table class="feature cpu"> |
| 141 | <tr><td>x86</td><td>x64</td><td>ARM</td><td>PPC</td><td>e500</td><td>MIPS</td></tr> | 145 | <tr><td>x86<br>x64</td><td>ARM<br>ARM64</td><td>PPC</td><td>MIPS32<br>MIPS64</td></tr> |
| 142 | </table> | 146 | </table> |
| 143 | <table class="feature fcompat"> | 147 | <table class="feature fcompat"> |
| 144 | <tr><td>Lua 5.1<br>API+ABI</td><td>+ JIT</td><td>+ BitOp</td><td>+ FFI</td><td>Drop-in<br>DLL/.so</td></tr> | 148 | <tr><td>Lua 5.1<br>API+ABI</td><td>+ JIT</td><td>+ BitOp</td><td>+ FFI</td><td>Drop-in<br>DLL/.so</td></tr> |
diff --git a/doc/running.html b/doc/running.html index 293ce429..20965f0a 100644 --- a/doc/running.html +++ b/doc/running.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>Running LuaJIT</title> | 4 | <title>Running LuaJIT</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-2026"> | 6 | <meta name="Copyright" content="Copyright (C) 2005-2026"> |
| 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"> |
| @@ -59,9 +59,13 @@ td.param_default { | |||
| 59 | <a href="ext_ffi_semantics.html">FFI Semantics</a> | 59 | <a href="ext_ffi_semantics.html">FFI Semantics</a> |
| 60 | </li></ul> | 60 | </li></ul> |
| 61 | </li><li> | 61 | </li><li> |
| 62 | <a href="ext_buffer.html">String Buffers</a> | ||
| 63 | </li><li> | ||
| 62 | <a href="ext_jit.html">jit.* Library</a> | 64 | <a href="ext_jit.html">jit.* Library</a> |
| 63 | </li><li> | 65 | </li><li> |
| 64 | <a href="ext_c_api.html">Lua/C API</a> | 66 | <a href="ext_c_api.html">Lua/C API</a> |
| 67 | </li><li> | ||
| 68 | <a href="ext_profiler.html">Profiler</a> | ||
| 65 | </li></ul> | 69 | </li></ul> |
| 66 | </li><li> | 70 | </li><li> |
| 67 | <a href="https://luajit.org/status.html">Status <span class="ext">»</span></a> | 71 | <a href="https://luajit.org/status.html">Status <span class="ext">»</span></a> |
| @@ -102,10 +106,14 @@ are accepted: | |||
| 102 | <li><tt>-l</tt> — Only list bytecode.</li> | 106 | <li><tt>-l</tt> — Only list bytecode.</li> |
| 103 | <li><tt>-s</tt> — Strip debug info (this is the default).</li> | 107 | <li><tt>-s</tt> — Strip debug info (this is the default).</li> |
| 104 | <li><tt>-g</tt> — Keep debug info.</li> | 108 | <li><tt>-g</tt> — Keep debug info.</li> |
| 109 | <li><tt>-W</tt> — Generate 32 bit (non-GC64) bytecode.</li> | ||
| 110 | <li><tt>-X</tt> — Generate 64 bit (GC64) bytecode.</li> | ||
| 111 | <li><tt>-d</tt> — Generate bytecode in deterministic manner.</li> | ||
| 105 | <li><tt>-n name</tt> — Set module name (default: auto-detect from input name)</li> | 112 | <li><tt>-n name</tt> — Set module name (default: auto-detect from input name)</li> |
| 106 | <li><tt>-t type</tt> — Set output file type (default: auto-detect from output name).</li> | 113 | <li><tt>-t type</tt> — Set output file type (default: auto-detect from output name).</li> |
| 107 | <li><tt>-a arch</tt> — Override architecture for object files (default: native).</li> | 114 | <li><tt>-a arch</tt> — Override architecture for object files (default: native).</li> |
| 108 | <li><tt>-o os</tt> — Override OS for object files (default: native).</li> | 115 | <li><tt>-o os</tt> — Override OS for object files (default: native).</li> |
| 116 | <li><tt>-F name</tt> — Override filename (default: input filename).</li> | ||
| 109 | <li><tt>-e chunk</tt> — Use chunk string as input.</li> | 117 | <li><tt>-e chunk</tt> — Use chunk string as input.</li> |
| 110 | <li><tt>-</tt> (a single minus sign) — Use stdin as input and/or stdout as output.</li> | 118 | <li><tt>-</tt> (a single minus sign) — Use stdin as input and/or stdout as output.</li> |
| 111 | </ul> | 119 | </ul> |
| @@ -115,7 +123,8 @@ file name: | |||
| 115 | </p> | 123 | </p> |
| 116 | <ul> | 124 | <ul> |
| 117 | <li><tt>c</tt> — C source file, exported bytecode data.</li> | 125 | <li><tt>c</tt> — C source file, exported bytecode data.</li> |
| 118 | <li><tt>h</tt> — C header file, static bytecode data.</li> | 126 | <li><tt>cc</tt> — C++ source file, exported bytecode data.</li> |
| 127 | <li><tt>h</tt> — C/C++ header file, static bytecode data.</li> | ||
| 119 | <li><tt>obj</tt> or <tt>o</tt> — Object file, exported bytecode data | 128 | <li><tt>obj</tt> or <tt>o</tt> — Object file, exported bytecode data |
| 120 | (OS- and architecture-specific).</li> | 129 | (OS- and architecture-specific).</li> |
| 121 | <li><tt>raw</tt> or any other extension — Raw bytecode file (portable). | 130 | <li><tt>raw</tt> or any other extension — Raw bytecode file (portable). |
| @@ -171,6 +180,7 @@ Here are the available LuaJIT control commands: | |||
| 171 | <li id="j_flush"><tt>-jflush</tt> — Flushes the whole cache of compiled code.</li> | 180 | <li id="j_flush"><tt>-jflush</tt> — Flushes the whole cache of compiled code.</li> |
| 172 | <li id="j_v"><tt>-jv</tt> — Shows verbose information about the progress of the JIT compiler.</li> | 181 | <li id="j_v"><tt>-jv</tt> — Shows verbose information about the progress of the JIT compiler.</li> |
| 173 | <li id="j_dump"><tt>-jdump</tt> — Dumps the code and structures used in various compiler stages.</li> | 182 | <li id="j_dump"><tt>-jdump</tt> — Dumps the code and structures used in various compiler stages.</li> |
| 183 | <li id="j_p"><tt>-jp</tt> — Start the <a href="ext_profiler.html">integrated profiler</a>.</li> | ||
| 174 | </ul> | 184 | </ul> |
| 175 | <p> | 185 | <p> |
| 176 | The <tt>-jv</tt> and <tt>-jdump</tt> commands are extension modules | 186 | The <tt>-jv</tt> and <tt>-jdump</tt> commands are extension modules |
| @@ -215,6 +225,12 @@ mix the three forms, but note that setting an optimization level | |||
| 215 | overrides all earlier flags. | 225 | overrides all earlier flags. |
| 216 | </p> | 226 | </p> |
| 217 | <p> | 227 | <p> |
| 228 | Note that <tt>-Ofma</tt> is not enabled by default at any level, | ||
| 229 | because it affects floating-point result accuracy. Only enable this, | ||
| 230 | if you fully understand the trade-offs of FMA for performance (higher), | ||
| 231 | determinism (lower) and numerical accuracy (higher). | ||
| 232 | </p> | ||
| 233 | <p> | ||
| 218 | Here are the available flags and at what optimization levels they | 234 | Here are the available flags and at what optimization levels they |
| 219 | are enabled: | 235 | are enabled: |
| 220 | </p> | 236 | </p> |
| @@ -246,6 +262,8 @@ are enabled: | |||
| 246 | <td class="flag_name">sink</td><td class="flag_level"> </td><td class="flag_level"> </td><td class="flag_level">•</td><td class="flag_desc">Allocation/Store Sinking</td></tr> | 262 | <td class="flag_name">sink</td><td class="flag_level"> </td><td class="flag_level"> </td><td class="flag_level">•</td><td class="flag_desc">Allocation/Store Sinking</td></tr> |
| 247 | <tr class="even"> | 263 | <tr class="even"> |
| 248 | <td class="flag_name">fuse</td><td class="flag_level"> </td><td class="flag_level"> </td><td class="flag_level">•</td><td class="flag_desc">Fusion of operands into instructions</td></tr> | 264 | <td class="flag_name">fuse</td><td class="flag_level"> </td><td class="flag_level"> </td><td class="flag_level">•</td><td class="flag_desc">Fusion of operands into instructions</td></tr> |
| 265 | <tr class="odd"> | ||
| 266 | <td class="flag_name">fma </td><td class="flag_level"> </td><td class="flag_level"> </td><td class="flag_level"> </td><td class="flag_desc">Fused multiply-add</td></tr> | ||
| 249 | </table> | 267 | </table> |
| 250 | <p> | 268 | <p> |
| 251 | Here are the parameters and their default settings: | 269 | Here are the parameters and their default settings: |
| @@ -281,9 +299,9 @@ Here are the parameters and their default settings: | |||
| 281 | <tr class="even"> | 299 | <tr class="even"> |
| 282 | <td class="param_name">recunroll</td><td class="param_default">2</td><td class="param_desc">Min. unroll factor for true recursion</td></tr> | 300 | <td class="param_name">recunroll</td><td class="param_default">2</td><td class="param_desc">Min. unroll factor for true recursion</td></tr> |
| 283 | <tr class="odd separate"> | 301 | <tr class="odd separate"> |
| 284 | <td class="param_name">sizemcode</td><td class="param_default">32</td><td class="param_desc">Size of each machine code area in KBytes (Windows: 64K)</td></tr> | 302 | <td class="param_name">sizemcode</td><td class="param_default">64</td><td class="param_desc">Size of each machine code area in KBytes</td></tr> |
| 285 | <tr class="even"> | 303 | <tr class="even"> |
| 286 | <td class="param_name">maxmcode</td><td class="param_default">512</td><td class="param_desc">Max. total size of all machine code areas in KBytes</td></tr> | 304 | <td class="param_name">maxmcode</td><td class="param_default">2048</td><td class="param_desc">Max. total size of all machine code areas in KBytes</td></tr> |
| 287 | </table> | 305 | </table> |
| 288 | <br class="flush"> | 306 | <br class="flush"> |
| 289 | </div> | 307 | </div> |