aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/contact.html8
-rw-r--r--doc/ext_buffer.html689
-rw-r--r--doc/ext_c_api.html8
-rw-r--r--doc/ext_ffi.html8
-rw-r--r--doc/ext_ffi_api.html18
-rw-r--r--doc/ext_ffi_semantics.html35
-rw-r--r--doc/ext_ffi_tutorial.html8
-rw-r--r--doc/ext_jit.html10
-rw-r--r--doc/ext_profiler.html359
-rw-r--r--doc/extensions.html112
-rw-r--r--doc/install.html150
-rw-r--r--doc/luajit.html14
-rw-r--r--doc/running.html18
13 files changed, 1348 insertions, 89 deletions
diff --git a/doc/contact.html b/doc/contact.html
index c32bc9dc..cc4d8c72 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-2023"> 6<meta name="Copyright" content="Copyright (C) 2005-2023">
7<meta name="Language" content="en"> 7<meta name="Language" content="en">
8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen"> 8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
@@ -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">&raquo;</span></a> 49<a href="https://luajit.org/status.html">Status <span class="ext">&raquo;</span></a>
diff --git a/doc/ext_buffer.html b/doc/ext_buffer.html
new file mode 100644
index 00000000..bfaa24cb
--- /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-2023">
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">&raquo;</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">&raquo;</span></a>
61</li><li>
62<a href="https://luajit.org/faq.html">FAQ <span class="ext">&raquo;</span></a>
63</li><li>
64<a href="https://luajit.org/list.html">Mailing List <span class="ext">&raquo;</span></a>
65</li></ul>
66</div>
67<div id="main">
68<p>
69The string buffer library allows <b>high-performance manipulation of
70string-like data</b>.
71</p>
72<p>
73Unlike Lua strings, which are constants, string buffers are
74<b>mutable</b> sequences of 8-bit (binary-transparent) characters. Data
75can be stored, formatted and encoded into a string buffer and later
76converted, extracted or decoded.
77</p>
78<p>
79The convenient string buffer API simplifies common string manipulation
80tasks, that would otherwise require creating many intermediate strings.
81String buffers improve performance by eliminating redundant memory
82copies, object creation, string interning and garbage collection
83overhead. In conjunction with the FFI library, they allow zero-copy
84operations.
85</p>
86<p>
87The 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>
93The string buffer library is built into LuaJIT by default, but it's not
94loaded by default. Add this to the start of every Lua file that needs
95one of its functions:
96</p>
97<pre class="code">
98local buffer = require("string.buffer")
99</pre>
100<p>
101The convention for the syntax shown on this page is that <tt>buffer</tt>
102refers to the buffer library and <tt>buf</tt> refers to an individual
103buffer object.
104</p>
105<p>
106Please 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>
113A 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.
115When the last reference to a buffer object is gone, it will eventually
116be freed by the garbage collector, along with the allocated buffer
117space.
118</p>
119<p>
120Buffers operate like a FIFO (first-in first-out) data structure. Data
121can be appended (written) to the end of the buffer and consumed (read)
122from the front of the buffer. These operations may be freely mixed.
123</p>
124<p>
125The buffer space that holds the characters is managed automatically
126&mdash; 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
128control.
129</p>
130<p>
131The maximum size of a single buffer is the same as the maximum size of a
132Lua string, which is slightly below two gigabytes. For huge data sizes,
133neither strings nor buffers are the right data structure &mdash; use the
134FFI library to directly map memory or files up to the virtual memory
135limit of your OS.
136</p>
137
138<h3 id="buffer_overview">Buffer Method Overview</h3>
139<ul>
140<li>
141The <tt>buf:put*()</tt>-like methods append (write) characters to the
142end of the buffer.
143</li>
144<li>
145The <tt>buf:get*()</tt>-like methods consume (read) characters from the
146front of the buffer.
147</li>
148<li>
149Other methods, like <tt>buf:tostring()</tt> only read the buffer
150contents, but don't change the buffer.
151</li>
152<li>
153The <tt>buf:set()</tt> method allows zero-copy consumption of a string
154or an FFI cdata object as a buffer.
155</li>
156<li>
157The FFI-specific methods allow zero-copy read/write-style operations or
158modifying the buffer contents in-place. Please check the
159<a href="#ffi_caveats">FFI caveats</a> below, too.
160</li>
161<li>
162Methods that don't need to return anything specific, return the buffer
163object 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>
171local buf = buffer.new([options])</tt></h3>
172<p>
173Creates a new buffer object.
174</p>
175<p>
176The optional <tt>size</tt> argument ensures a minimum initial buffer
177size. This is strictly an optimization when the required buffer size is
178known beforehand. The buffer space will grow as needed, in any case.
179</p>
180<p>
181The 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>
187Reset (empty) the buffer. The allocated buffer space is not freed and
188may be reused.
189</p>
190
191<h3 id="buffer_free"><tt>buf = buf:free()</tt></h3>
192<p>
193The buffer space of the buffer object is freed. The object itself
194remains intact, empty and may be reused.
195</p>
196<p>
197Note: you normally don't need to use this method. The garbage collector
198automatically frees the buffer space, when the buffer object is
199collected. Use this method, if you need to free the associated memory
200immediately.
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>
207Appends 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.
209Multiple arguments are appended in the given order.
210</p>
211<p>
212Appending a buffer to a buffer is possible and short-circuited
213internally. But it still involves a copy. Better combine the buffer
214writes to use a single buffer.
215</p>
216
217<h3 id="buffer_putf"><tt>buf = buf:putf(format, …)</tt></h3>
218<p>
219Appends the formatted arguments to the buffer. The <tt>format</tt>
220string 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>
225Appends the given <tt>len</tt> number of bytes from the memory pointed
226to by the FFI <tt>cdata</tt> object to the buffer. The object needs to
227be convertible to a (constant) pointer.
228</p>
229
230<h3 id="buffer_set"><tt>buf = buf:set(str)<br>
231buf = buf:set(cdata, len)</tt><span class="lib">FFI</span></h3>
232<p>
233This method allows zero-copy consumption of a string or an FFI cdata
234object 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
236space originally allocated is freed. This is <i>not</i> an append
237operation, unlike the <tt>buf:put*()</tt> methods.
238</p>
239<p>
240After calling this method, the buffer behaves as if
241<tt>buf:free():put(str)</tt> or <tt>buf:free():put(cdata,&nbsp;len)</tt>
242had been called. However, the data is only referenced and not copied, as
243long as the buffer is only consumed.
244</p>
245<p>
246In case the buffer is written to later on, the referenced data is copied
247and the object reference is removed (copy-on-write semantics).
248</p>
249<p>
250The stored reference is an anchor for the garbage collector and keeps the
251originally 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>
257The <tt>reserve</tt> method reserves at least <tt>size</tt> bytes of
258write space in the buffer. It returns an <tt>uint8_t&nbsp;*</tt> FFI
259cdata pointer <tt>ptr</tt> that points to this space.
260</p>
261<p>
262The available length in bytes is returned in <tt>len</tt>. This is at
263least <tt>size</tt> bytes, but may be more to facilitate efficient
264buffer 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>
268The <tt>commit</tt> method appends the <tt>used</tt> bytes of the
269previously returned write space to the buffer data.
270</p>
271<p>
272This pair of methods allows zero-copy use of C read-style APIs:
273</p>
274<pre class="code">
275local MIN_SIZE = 65536
276repeat
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 &lt; 0 then error("read error") end
281 buf:commit(n)
282until false
283</pre>
284<p>
285The 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>
288method, 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>
295Returns 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>
300The Lua concatenation operator <tt>..</tt> also accepts buffers, just
301like strings or numbers. It always returns a string and not a buffer.
302</p>
303<p>
304Note that although this is supported for convenience, this thwarts one
305of the main reasons to use buffers, which is to avoid string
306allocations. Rewrite it with <tt>buf:put()</tt> and <tt>buf:get()</tt>.
307</p>
308<p>
309Mixing this with unrelated objects that have a <tt>__concat</tt>
310metamethod 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>
315Skips (consumes) <tt>len</tt> bytes from the buffer up to the current
316length of the buffer data.
317</p>
318
319<h3 id="buffer_get"><tt>str, … = buf:get([len|nil] [,…])</tt></h3>
320<p>
321Consumes the buffer data and returns one or more strings. If called
322without arguments, the whole buffer data is consumed. If called with a
323number, up to <tt>len</tt> bytes are consumed. A <tt>nil</tt> argument
324consumes the remaining buffer space (this only makes sense as the last
325argument). Multiple arguments consume the buffer data in the given
326order.
327</p>
328<p>
329Note: a zero length or no remaining buffer data returns an empty string
330and not <tt>nil</tt>.
331</p>
332
333<h3 id="buffer_tostring"><tt>str = buf:tostring()<br>
334str = tostring(buf)</tt></h3>
335<p>
336Creates a string from the buffer data, but doesn't consume it. The
337buffer remains unchanged.
338</p>
339<p>
340Buffer objects also define a <tt>__tostring</tt> metamethod. This means
341buffers can be passed to the global <tt>tostring()</tt> function and
342many other functions that accept this in place of strings. The important
343internal uses in functions like <tt>io.write()</tt> are short-circuited
344to 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>
349Returns an <tt>uint8_t&nbsp;*</tt> FFI cdata pointer <tt>ptr</tt> that
350points to the buffer data. The length of the buffer data in bytes is
351returned in <tt>len</tt>.
352</p>
353<p>
354The returned pointer can be directly passed to C functions that expect a
355buffer and a length. You can also do bytewise reads
356(<tt>local&nbsp;x&nbsp;=&nbsp;ptr[i]</tt>) or writes
357(<tt>ptr[i]&nbsp;=&nbsp;0x40</tt>) of the buffer data.
358</p>
359<p>
360In conjunction with the <tt>skip</tt> method, this allows zero-copy use
361of C write-style APIs:
362</p>
363<pre class="code">
364repeat
365 local ptr, len = buf:ref()
366 if len == 0 then break end
367 local n = C.write(fd, ptr, len)
368 if n &lt; 0 then error("write error") end
369 buf:skip(n)
370until n >= len
371</pre>
372<p>
373Unlike Lua strings, buffer data is <i>not</i> implicitly
374zero-terminated. It's not safe to pass <tt>ptr</tt> to C functions that
375expect zero-terminated strings. If you're not using <tt>len</tt>, then
376you're doing something wrong.
377</p>
378
379<h2 id="serialize">Serialization of Lua Objects</h2>
380<p>
381The 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
383object. This allows convenient storage and transport of <b>structured
384data</b>.
385</p>
386<p>
387The encoded data is in an <a href="#serialize_format">internal binary
388format</a>. The data can be stored in files, binary-transparent
389databases or transmitted to other LuaJIT instances across threads,
390processes or networks.
391</p>
392<p>
393Encoding speed can reach up to 1 Gigabyte/second on a modern desktop- or
394server-class system, even when serializing many small objects. Decoding
395speed is mostly constrained by object creation cost.
396</p>
397<p>
398The serializer handles most Lua types, common FFI number types and
399nested structures. Functions, thread objects, other FFI cdata and full
400userdata cannot be serialized (yet).
401</p>
402<p>
403The encoder serializes nested structures as trees. Multiple references
404to a single object will be stored separately and create distinct objects
405after 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>
411buf = buf:encode(obj)</tt></h3>
412<p>
413Serializes (encodes) the Lua object <tt>obj</tt>. The stand-alone
414function returns a string <tt>str</tt>. The buffer method appends the
415encoding to the buffer.
416</p>
417<p>
418<tt>obj</tt> can be any of the supported Lua types &mdash; it doesn't
419need to be a Lua table.
420</p>
421<p>
422This function may throw an error when attempting to serialize
423unsupported object types, circular references or deeply nested tables.
424</p>
425
426<h3 id="buffer_decode"><tt>obj = buffer.decode(str)<br>
427obj = buf:decode()</tt></h3>
428<p>
429The stand-alone function deserializes (decodes) the string
430<tt>str</tt>, the buffer method deserializes one object from the
431buffer. Both return a Lua object <tt>obj</tt>.
432</p>
433<p>
434The returned object may be any of the supported Lua types &mdash;
435even <tt>nil</tt>.
436</p>
437<p>
438This function may throw an error when fed with malformed or incomplete
439encoded data. The stand-alone function throws when there's left-over
440data after decoding a single top-level object. The buffer method leaves
441any left-over data in the buffer.
442</p>
443<p>
444Attempting to deserialize an FFI type will throw an error, if the FFI
445library is not built-in or has not been loaded, yet.
446</p>
447
448<h3 id="serialize_options">Serialization Options</h3>
449<p>
450The <tt>options</tt> table passed to <tt>buffer.new()</tt> may contain
451the 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
456commonly occur as table keys of objects you are serializing. These keys
457are compactly encoded as indexes during serialization. A well-chosen
458dictionary 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>
462for 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
467to 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
469internally modified into a two-way index (don't do this yourself, just pass
470a plain array). The tables must not be modified after they have been passed
471to <tt>buffer.new()</tt>.
472</p>
473<p>
474The <tt>dict</tt> and <tt>metatable</tt> tables used by the encoder and
475decoder must be the same. Put the most common entries at the front. Extend
476at the end to ensure backwards-compatibility &mdash; older encodings can
477then still be read. You may also set some indexes to <tt>false</tt> to
478explicitly drop backwards-compatibility. Old encodings that use these
479indexes will throw an error when decoded.
480</p>
481<p>
482Metatables that are not found in the <tt>metatable</tt> dictionary are
483ignored when encoding. Decoding returns a table with a <tt>nil</tt>
484metatable.
485</p>
486<p>
487Note: parsing and preparation of the options table is somewhat
488expensive. Create a buffer object only once and recycle it for multiple
489uses. 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">
493local options = {
494 dict = { "commonly", "used", "string", "keys" },
495}
496local buf_enc = buffer.new(options)
497local buf_dec = buffer.new(options)
498
499local function encode(obj)
500 return buf_enc:reset():encode(obj):get()
501end
502
503local function decode(str)
504 return buf_dec:set(str):decode()
505end
506</pre>
507
508<h3 id="serialize_stream">Streaming Serialization</h3>
509<p>
510In some contexts, it's desirable to do piecewise serialization of large
511datasets, also known as <i>streaming</i>.
512</p>
513<p>
514This serialization format can be safely concatenated and supports streaming.
515Multiple encodings can simply be appended to a buffer and later decoded
516individually:
517</p>
518<pre class="code">
519local buf = buffer.new()
520buf:encode(obj1)
521buf:encode(obj2)
522local copy1 = buf:decode()
523local copy2 = buf:decode()
524</pre>
525<p>
526Here's how to iterate over a stream:
527</p>
528<pre class="code">
529while #buf ~= 0 do
530 local obj = buf:decode()
531 -- Do something with obj.
532end
533</pre>
534<p>
535Since the serialization format doesn't prepend a length to its encoding,
536network applications may need to transmit the length, too.
537</p>
538
539<h3 id="serialize_format">Serialization Format Specification</h3>
540<p>
541This serialization format is designed for <b>internal use</b> by LuaJIT
542applications. Serialized data is upwards-compatible and portable across
543all supported LuaJIT platforms.
544</p>
545<p>
546It's an <b>8-bit binary format</b> and not human-readable. It uses e.g.
547embedded zeroes and stores embedded Lua string objects unmodified, which
548are 8-bit-clean, too. Encoded data can be safely concatenated for
549streaming and later decoded one top-level object at a time.
550</p>
551<p>
552The encoding is reasonably compact, but tuned for maximum performance,
553not for minimum space usage. It compresses well with any of the common
554byte-oriented data compression algorithms.
555</p>
556<p>
557Although documented here for reference, this format is explicitly
558<b>not</b> intended to be a 'public standard' for structured data
559interchange across computer languages (like JSON or MessagePack). Please
560do not use it as such.
561</p>
562<p>
563The specification is given below as a context-free grammar with a
564top-level <tt>object</tt> as the starting point. Alternatives are
565separated by the <tt>|</tt> symbol and <tt>*</tt> indicates repeats.
566Grouping is implicit or indicated by <tt>{…}</tt>. Terminals are
567either plain hex numbers, encoded as bytes, or have a <tt>.format</tt>
568suffix.
569</p>
570<pre>
571object → nil | false | true
572 | null | lightud32 | lightud64
573 | int | num | tab | tab_mt
574 | int64 | uint64 | complex
575 | string
576
577nil → 0x00
578false → 0x01
579true → 0x02
580
581null → 0x03 // NULL lightuserdata
582lightud32 → 0x04 data.I // 32 bit lightuserdata
583lightud64 → 0x05 data.L // 64 bit lightuserdata
584
585int → 0x06 int.I // int32_t
586num → 0x07 double.L
587
588tab → 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 a*object h.U h*{object object} // Mixed
592 | 0x0c a.U (a-1)*object // 1-based array
593 | 0x0d a.U (a-1)*object h.U h*{object object} // Mixed
594tab_mt → 0x0e (index-1).U tab // Metatable dict entry
595
596int64 → 0x10 int.L // FFI int64_t
597uint64 → 0x11 uint.L // FFI uint64_t
598complex → 0x12 re.L im.L // FFI complex
599
600string → (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>
614Many of the buffer methods can throw an error. Out-of-memory or usage
615errors are best caught with an outer wrapper for larger parts of code.
616There's not much one can do after that, anyway.
617</p>
618<p>
619OTOH, you may want to catch some errors individually. Buffer methods need
620to 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">
625local ok, err = pcall(buf.encode, buf, obj)
626if not ok then
627 -- Handle error in err.
628end
629</pre>
630
631<h2 id="ffi_caveats">FFI caveats</h2>
632<p>
633The string buffer library has been designed to work well together with
634the FFI library. But due to the low-level nature of the FFI library,
635some care needs to be taken:
636</p>
637<p>
638First, please remember that FFI pointers are zero-indexed. The space
639returned by <tt>buf:reserve()</tt> and <tt>buf:ref()</tt> starts at the
640returned pointer and ends before <tt>len</tt> bytes after that.
641</p>
642<p>
643I.e. the first valid index is <tt>ptr[0]</tt> and the last valid index
644is <tt>ptr[len-1]</tt>. If the returned length is zero, there's no valid
645index at all. The returned pointer may even be <tt>NULL</tt>.
646</p>
647<p>
648The space pointed to by the returned pointer is only valid as long as
649the buffer is not modified in any way (neither append, nor consume, nor
650reset, etc.). The pointer is also not a GC anchor for the buffer object
651itself.
652</p>
653<p>
654Buffer data is only guaranteed to be byte-aligned. Casting the returned
655pointer to a data type with higher alignment may cause unaligned
656accesses. It depends on the CPU architecture whether this is allowed or
657not (it's always OK on x86/x64 and mostly OK on other modern
658architectures).
659</p>
660<p>
661FFI pointers or references do not count as GC anchors for an underlying
662object. E.g. an <tt>array</tt> allocated with <tt>ffi.new()</tt> is
663anchored by <tt>buf:set(array,&nbsp;len)</tt>, but not by
664<tt>buf:set(array+offset,&nbsp;len)</tt>. The addition of the offset
665creates a new pointer, even when the offset is zero. In this case, you
666need to make sure there's still a reference to the original array as
667long as its contents are in use by the buffer.
668</p>
669<p>
670Even though each LuaJIT VM instance is single-threaded (but you can
671create multiple VMs), FFI data structures can be accessed concurrently.
672Be careful when reading/writing FFI cdata from/to buffers to avoid
673concurrent accesses or modifications. In particular, the memory
674referenced by <tt>buf:set(cdata,&nbsp;len)</tt> must not be modified
675while buffer readers are working on it. Shared, but read-only memory
676mappings 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">
682Copyright &copy; 2005-2023
683<span class="noprint">
684&middot;
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 43c82047..d5e6bb60 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-2023"> 6<meta name="Copyright" content="Copyright (C) 2005-2023">
7<meta name="Language" content="en"> 7<meta name="Language" content="en">
8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen"> 8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
@@ -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">&raquo;</span></a> 49<a href="https://luajit.org/status.html">Status <span class="ext">&raquo;</span></a>
diff --git a/doc/ext_ffi.html b/doc/ext_ffi.html
index 683c0cd0..eaa176b6 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-2023"> 6<meta name="Copyright" content="Copyright (C) 2005-2023">
7<meta name="Language" content="en"> 7<meta name="Language" content="en">
8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen"> 8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
@@ -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">&raquo;</span></a> 49<a href="https://luajit.org/status.html">Status <span class="ext">&raquo;</span></a>
diff --git a/doc/ext_ffi_api.html b/doc/ext_ffi_api.html
index d5f7032f..500a2143 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-2023"> 6<meta name="Copyright" content="Copyright (C) 2005-2023">
7<meta name="Language" content="en"> 7<meta name="Language" content="en">
8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen"> 8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
@@ -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">&raquo;</span></a> 54<a href="https://luajit.org/status.html">Status <span class="ext">&raquo;</span></a>
@@ -458,6 +462,12 @@ 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>
461</table> 471</table>
462 472
463<h3 id="ffi_os"><tt>ffi.os</tt></h3> 473<h3 id="ffi_os"><tt>ffi.os</tt></h3>
@@ -534,8 +544,8 @@ corresponding ctype.
534The parser for Lua source code treats numeric literals with the 544The parser for Lua source code treats numeric literals with the
535suffixes <tt>LL</tt> or <tt>ULL</tt> as signed or unsigned 64&nbsp;bit 545suffixes <tt>LL</tt> or <tt>ULL</tt> as signed or unsigned 64&nbsp;bit
536integers. Case doesn't matter, but uppercase is recommended for 546integers. Case doesn't matter, but uppercase is recommended for
537readability. It handles both decimal (<tt>42LL</tt>) and hexadecimal 547readability. It handles decimal (<tt>42LL</tt>), hexadecimal
538(<tt>0x2aLL</tt>) literals. 548(<tt>0x2aLL</tt>) and binary (<tt>0b101010LL</tt>) literals.
539</p> 549</p>
540<p> 550<p>
541The imaginary part of complex numbers can be specified by suffixing 551The 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 381a2010..5ba82a1e 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-2023"> 6<meta name="Copyright" content="Copyright (C) 2005-2023">
7<meta name="Language" content="en"> 7<meta name="Language" content="en">
8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen"> 8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
@@ -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">&raquo;</span></a> 54<a href="https://luajit.org/status.html">Status <span class="ext">&raquo;</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>&lt;unistd.h&gt;</tt> (POSIX): <tt>ssize_t</tt>.</li>
183
178</ul> 184</ul>
179<p> 185<p>
180You're encouraged to use these types in preference to 186You're encouraged to use these types in preference to
@@ -722,6 +728,22 @@ You'll have to explicitly convert a 64&nbsp;bit integer to a Lua
722number (e.g. for regular floating-point calculations) with 728number (e.g. for regular floating-point calculations) with
723<tt>tonumber()</tt>. But note this may incur a precision loss.</li> 729<tt>tonumber()</tt>. But note this may incur a precision loss.</li>
724 730
731<li><b>64&nbsp;bit bitwise operations</b>: the rules for 64&nbsp;bit
732arithmetic operators apply analogously.<br>
733
734Unlike the other <tt>bit.*</tt> operations, <tt>bit.tobit()</tt>
735converts a cdata number via <tt>int64_t</tt> to <tt>int32_t</tt> and
736returns a Lua number.<br>
737
738For <tt>bit.band()</tt>, <tt>bit.bor()</tt> and <tt>bit.bxor()</tt>, the
739conversion to <tt>int64_t</tt> or <tt>uint64_t</tt> applies to
740<em>all</em> arguments, if <em>any</em> argument is a cdata number.<br>
741
742For all other operations, only the first argument is used to determine
743the output type. This implies that a cdata number as a shift count for
744shifts and rotates is accepted, but that alone does <em>not</em> cause
745a cdata number output.
746
725</ul> 747</ul>
726 748
727<h3 id="cdata_comp">Comparisons of cdata objects</h3> 749<h3 id="cdata_comp">Comparisons of cdata objects</h3>
@@ -1193,14 +1215,12 @@ The following operations are currently not compiled and may exhibit
1193suboptimal performance, especially when used in inner loops: 1215suboptimal performance, especially when used in inner loops:
1194</p> 1216</p>
1195<ul> 1217<ul>
1196<li>Bitfield accesses and initializations.</li>
1197<li>Vector operations.</li> 1218<li>Vector operations.</li>
1198<li>Table initializers.</li> 1219<li>Table initializers.</li>
1199<li>Initialization of nested <tt>struct</tt>/<tt>union</tt> types.</li> 1220<li>Initialization of nested <tt>struct</tt>/<tt>union</tt> types.</li>
1200<li>Allocations of variable-length arrays or structs.</li> 1221<li>Non-default initialization of VLA/VLS or large C&nbsp;types
1201<li>Allocations of C&nbsp;types with a size &gt; 128&nbsp;bytes or an 1222(&gt; 128&nbsp;bytes or &gt; 16 array elements).</li>
1202alignment &gt; 8&nbsp;bytes.</li> 1223<li>Bitfield initializations.</li>
1203<li>Conversions from lightuserdata to <tt>void&nbsp;*</tt>.</li>
1204<li>Pointer differences for element sizes that are not a power of 1224<li>Pointer differences for element sizes that are not a power of
1205two.</li> 1225two.</li>
1206<li>Calls to C&nbsp;functions with aggregates passed or returned by 1226<li>Calls to C&nbsp;functions with aggregates passed or returned by
@@ -1216,7 +1236,6 @@ value.</li>
1216Other missing features: 1236Other missing features:
1217</p> 1237</p>
1218<ul> 1238<ul>
1219<li>Bit operations for 64&nbsp;bit types.</li>
1220<li>Arithmetic for <tt>complex</tt> numbers.</li> 1239<li>Arithmetic for <tt>complex</tt> numbers.</li>
1221<li>Passing structs by value to vararg C&nbsp;functions.</li> 1240<li>Passing structs by value to vararg C&nbsp;functions.</li>
1222<li><a href="extensions.html#exceptions">C++ exception interoperability</a> 1241<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 03b6ec56..a5236f0b 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-2023"> 6<meta name="Copyright" content="Copyright (C) 2005-2023">
7<meta name="Language" content="en"> 7<meta name="Language" content="en">
8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen"> 8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
@@ -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">&raquo;</span></a> 56<a href="https://luajit.org/status.html">Status <span class="ext">&raquo;</span></a>
diff --git a/doc/ext_jit.html b/doc/ext_jit.html
index b1dbf36c..dd136d65 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-2023"> 6<meta name="Copyright" content="Copyright (C) 2005-2023">
7<meta name="Language" content="en"> 7<meta name="Language" content="en">
8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen"> 8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
@@ -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">&raquo;</span></a> 49<a href="https://luajit.org/status.html">Status <span class="ext">&raquo;</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>
147Contains the target architecture name: 151Contains 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> &mdash; JIT compiler optimization control</h2> 155<h2 id="jit_opt"><tt>jit.opt.*</tt> &mdash; JIT compiler optimization control</h2>
diff --git a/doc/ext_profiler.html b/doc/ext_profiler.html
new file mode 100644
index 00000000..81b5d773
--- /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-2023">
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">&raquo;</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">&raquo;</span></a>
50</li><li>
51<a href="https://luajit.org/faq.html">FAQ <span class="ext">&raquo;</span></a>
52</li><li>
53<a href="https://luajit.org/list.html">Mailing List <span class="ext">&raquo;</span></a>
54</li></ul>
55</div>
56<div id="main">
57<p>
58LuaJIT has an integrated statistical profiler with very low overhead. It
59allows sampling the currently executing stack and other parameters in
60regular intervals.
61</p>
62<p>
63The 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>
74The bundled high-level profiler offers basic profiling functionality. It
75generates simple textual summaries or source code annotations. It can be
76accessed with the <a href="#j_p"><tt>-jp</tt></a> command line option
77or from Lua code by loading the underlying <tt>jit.p</tt> module.
78</p>
79<p>
80To cut to the chase &mdash; run this to get a CPU usage profile by
81function name:
82</p>
83<pre class="code">
84luajit -jp myapp.lua
85</pre>
86<p>
87It's <em>not</em> a stated goal of the bundled profiler to add every
88possible option or to cater for special profiling needs. The low-level
89profiler APIs are documented below. They may be used by third-party
90authors to implement advanced functionality, e.g. IDE integration or
91graphical profilers.
92</p>
93<p>
94Note: Sampling works for both interpreted and JIT-compiled code. The
95results for JIT-compiled code may sometimes be surprising. LuaJIT
96heavily optimizes and inlines Lua code &mdash; there's no simple
97one-to-one correspondence between source code lines and the sampled
98machine code.
99</p>
100
101<h3 id="j_p"><tt>-jp=[options[,output]]</tt></h3>
102<p>
103The <tt>-jp</tt> command line option starts the high-level profiler.
104When the application run by the command line terminates, the profiler
105stops and writes the results to <tt>stdout</tt> or to the specified
106<tt>output</tt> file.
107</p>
108<p>
109The <tt>options</tt> argument specifies how the profiling is to be
110performed:
111</p>
112<ul>
113<li><tt>f</tt> &mdash; Stack dump: function name, otherwise module:line.
114This is the default mode.</li>
115<li><tt>F</tt> &mdash; Stack dump: ditto, but dump module:name.</li>
116<li><tt>l</tt> &mdash; Stack dump: module:line.</li>
117<li><tt>&lt;number&gt;</tt> &mdash; stack dump depth (callee &larr;
118caller). Default: 1.</li>
119<li><tt>-&lt;number&gt;</tt> &mdash; Inverse stack dump depth (caller
120&rarr; callee).</li>
121<li><tt>s</tt> &mdash; Split stack dump after first stack level. Implies
122depth&nbsp;&ge;&nbsp;2 or depth&nbsp;&le;&nbsp;-2.</li>
123<li><tt>p</tt> &mdash; Show full path for module names.</li>
124<li><tt>v</tt> &mdash; Show VM states.</li>
125<li><tt>z</tt> &mdash; Show <a href="#jit_zone">zones</a>.</li>
126<li><tt>r</tt> &mdash; Show raw sample counts. Default: show percentages.</li>
127<li><tt>a</tt> &mdash; Annotate excerpts from source code files.</li>
128<li><tt>A</tt> &mdash; Annotate complete source code files.</li>
129<li><tt>G</tt> &mdash; Produce raw output suitable for graphical tools.</li>
130<li><tt>m&lt;number&gt;</tt> &mdash; Minimum sample percentage to be shown.
131Default: 3%.</li>
132<li><tt>i&lt;number&gt;</tt> &mdash; Sampling interval in milliseconds.
133Default: 10ms.<br>
134Note: The actual sampling precision is OS-dependent.</li>
135</ul>
136<p>
137The default output for <tt>-jp</tt> is a list of the most CPU consuming
138spots 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
140hotspots. But sample aggregation is still flat per unique stack dump.
141</p>
142<p>
143To 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
145level are relative to the first level.
146</p>
147<p>
148To see how much time is spent in each line relative to a function, use
149<tt>-jp=fl</tt>.
150</p>
151<p>
152To 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>
156Combinations of <tt>v/z</tt> with <tt>f/F/l</tt> produce two-level
157views, e.g. <tt>-jp=vf</tt> or <tt>-jp=fv</tt>. This shows the time
158spent in a VM state or zone vs. hotspots. This can be used to answer
159questions like "Which time-consuming functions are only interpreted?" or
160"What's the garbage collector overhead for a specific function?".
161</p>
162<p>
163Multiple options can be combined &mdash; but not all combinations make
164sense, see above. E.g. <tt>-jp=3si4m1</tt> samples three stack levels
165deep in 4ms intervals and shows a split view of the CPU consuming
166functions and their callers with a 1% threshold.
167</p>
168<p>
169Source code annotations produced by <tt>-jp=a</tt> or <tt>-jp=A</tt> are
170always flat and at the line level. Obviously, the source code files need
171to be readable by the profiler script.
172</p>
173<p>
174The high-level profiler can also be started and stopped from Lua code with:
175</p>
176<pre class="code">
177require("jit.p").start(options, output)
178...
179require("jit.p").stop()
180</pre>
181
182<h3 id="jit_zone"><tt>jit.zone</tt> &mdash; Zones</h3>
183<p>
184Zones can be used to provide information about different parts of an
185application 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,
187organized as a stack.
188</p>
189<p>
190The <tt>jit.zone</tt> module needs to be loaded explicitly:
191</p>
192<pre class="code">
193local 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
198returns 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>
203To show the time spent in each zone use <tt>-jp=z</tt>. To show the time
204spent 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>
209The <tt>jit.profile</tt> module gives access to the low-level API of the
210profiler from Lua code. This module needs to be loaded explicitly:
211<pre class="code">
212local profile = require("jit.profile")
213</pre>
214<p>
215This module can be used to implement your own higher-level profiler.
216A typical profiling run starts the profiler, captures stack dumps in
217the profiler callback, adds them to a hash table to aggregate the number
218of samples, stops the profiler and then analyzes all captured
219stack dumps. Other parameters can be sampled in the profiler callback,
220too. But it's important not to spend too much time in the callback,
221since this may skew the statistics.
222</p>
223
224<h3 id="profile_start"><tt>profile.start(mode, cb)</tt>
225&mdash; Start profiler</h3>
226<p>
227This function starts the profiler. The <tt>mode</tt> argument is a
228string holding options:
229</p>
230<ul>
231<li><tt>f</tt> &mdash; Profile with precision down to the function level.</li>
232<li><tt>l</tt> &mdash; Profile with precision down to the line level.</li>
233<li><tt>i&lt;number&gt;</tt> &mdash; Sampling interval in milliseconds (default
23410ms).</br>
235Note: The actual sampling precision is OS-dependent.
236</li>
237</ul>
238<p>
239The <tt>cb</tt> argument is a callback function which is called with
240three arguments: <tt>(thread, samples, vmstate)</tt>. The callback is
241called on a separate coroutine, the <tt>thread</tt> argument is the
242state 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
247callback (usually 1).
248</p>
249<p>
250<tt>vmstate</tt> holds the VM state at the time the profiling timer
251triggered. This may or may not correspond to the state of the VM when
252the profiling callback is called. The state is either <tt>'N'</tt>
253native (compiled) code, <tt>'I'</tt> interpreted code, <tt>'C'</tt>
254C&nbsp;code, <tt>'G'</tt> the garbage collector, or <tt>'J'</tt> the JIT
255compiler.
256</p>
257
258<h3 id="profile_stop"><tt>profile.stop()</tt>
259&mdash; Stop profiler</h3>
260<p>
261This function stops the profiler.
262</p>
263
264<h3 id="profile_dump"><tt>dump = profile.dumpstack([thread,] fmt, depth)</tt>
265&mdash; Dump stack </h3>
266<p>
267This function allows taking stack dumps in an efficient manner. It
268returns a string with a stack dump for the <tt>thread</tt> (coroutine),
269formatted according to the <tt>fmt</tt> argument:
270</p>
271<ul>
272<li><tt>p</tt> &mdash; Preserve the full path for module names. Otherwise,
273only the file name is used.</li>
274<li><tt>f</tt> &mdash; Dump the function name if it can be derived. Otherwise,
275use module:line.</li>
276<li><tt>F</tt> &mdash; Ditto, but dump module:name.</li>
277<li><tt>l</tt> &mdash; Dump module:line.</li>
278<li><tt>Z</tt> &mdash; Zap the following characters for the last dumped
279frame.</li>
280<li>All other characters are added verbatim to the output string.</li>
281</ul>
282<p>
283The <tt>depth</tt> argument gives the number of frames to dump, starting
284at the topmost frame of the thread. A negative number dumps the frames in
285inverse order.
286</p>
287<p>
288The first example prints a list of the current module names and line
289numbers of up to 10 frames in separate lines. The second example prints
290semicolon-separated function names for all frames (up to 100) in inverse
291order:
292</p>
293<pre class="code">
294print(profile.dumpstack(thread, "l\n", 10))
295print(profile.dumpstack(thread, "lZ;", -100))
296</pre>
297
298<h2 id="ll_c_api">Low-level C API</h2>
299<p>
300The profiler can be controlled directly from C&nbsp;code, e.g. for
301use 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&mdash; Start profiler</h3>
307<p>
308This function starts the profiler. <a href="#profile_start">See
309above</a> for a description of the <tt>mode</tt> argument.
310</p>
311<p>
312The <tt>cb</tt> argument is a callback function with the following
313declaration:
314</p>
315<pre class="code">
316typedef 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
321state that holds the stack to sample for profiling. Note: do
322<em>not</em> modify this stack or call functions on this stack &mdash;
323use a separate coroutine for this purpose. <a href="#profile_start">See
324above</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&mdash; Stop profiler</h3>
329<p>
330This function stops the profiler.
331</p>
332
333<h3 id="luaJIT_profile_dumpstack"><tt>p = luaJIT_profile_dumpstack(L, fmt, depth, len)</tt>
334&mdash; Dump stack </h3>
335<p>
336This function allows taking stack dumps in an efficient manner.
337<a href="#profile_dump">See above</a> for a description of <tt>fmt</tt>
338and <tt>depth</tt>.
339</p>
340<p>
341This function returns a <tt>const&nbsp;char&nbsp;*</tt> pointing to a
342private string buffer of the profiler. The <tt>int&nbsp;*len</tt>
343argument returns the length of the output string. The buffer is
344overwritten on the next call and deallocated when the profiler stops.
345You either need to consume the content immediately or copy it for later
346use.
347</p>
348<br class="flush">
349</div>
350<div id="foot">
351<hr class="hide">
352Copyright &copy; 2005-2023
353<span class="noprint">
354&middot;
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 f8b45c28..eb591d1e 100644
--- a/doc/extensions.html
+++ b/doc/extensions.html
@@ -1,8 +1,8 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> 1<!DOCTYPE html>
2<html> 2<html>
3<head> 3<head>
4<title>Extensions</title> 4<title>Extensions</title>
5<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> 5<meta charset="utf-8">
6<meta name="Copyright" content="Copyright (C) 2005-2023"> 6<meta name="Copyright" content="Copyright (C) 2005-2023">
7<meta name="Language" content="en"> 7<meta name="Language" content="en">
8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen"> 8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
@@ -54,9 +54,13 @@ td.excinterop {
54<a href="ext_ffi_semantics.html">FFI Semantics</a> 54<a href="ext_ffi_semantics.html">FFI Semantics</a>
55</li></ul> 55</li></ul>
56</li><li> 56</li><li>
57<a href="ext_buffer.html">String Buffers</a>
58</li><li>
57<a href="ext_jit.html">jit.* Library</a> 59<a href="ext_jit.html">jit.* Library</a>
58</li><li> 60</li><li>
59<a href="ext_c_api.html">Lua/C API</a> 61<a href="ext_c_api.html">Lua/C API</a>
62</li><li>
63<a href="ext_profiler.html">Profiler</a>
60</li></ul> 64</li></ul>
61</li><li> 65</li><li>
62<a href="https://luajit.org/status.html">Status <span class="ext">&raquo;</span></a> 66<a href="https://luajit.org/status.html">Status <span class="ext">&raquo;</span></a>
@@ -106,6 +110,9 @@ bit.lshift bit.rshift bit.arshift bit.rol bit.ror bit.bswap
106This module is a LuaJIT built-in &mdash; you don't need to download or 110This module is a LuaJIT built-in &mdash; you don't need to download or
107install Lua BitOp. The Lua BitOp site has full documentation for all 111install Lua BitOp. The Lua BitOp site has full documentation for all
108<a href="https://bitop.luajit.org/api.html"><span class="ext">&raquo;</span>&nbsp;Lua BitOp API functions</a>. 112<a href="https://bitop.luajit.org/api.html"><span class="ext">&raquo;</span>&nbsp;Lua BitOp API functions</a>.
113The FFI adds support for
114<a href="ext_ffi_semantics.html#cdata_arith">64&nbsp;bit bitwise operations</a>,
115using the same API functions.
109</p> 116</p>
110<p> 117<p>
111Please make sure to <tt>require</tt> the module before using any of 118Please make sure to <tt>require</tt> the module before using any of
@@ -139,6 +146,11 @@ LuaJIT adds some
139<a href="ext_c_api.html">extra functions to the Lua/C API</a>. 146<a href="ext_c_api.html">extra functions to the Lua/C API</a>.
140</p> 147</p>
141 148
149<h3 id="profiler">Profiler</h3>
150<p>
151LuaJIT has an <a href="ext_profiler.html">integrated profiler</a>.
152</p>
153
142<h2 id="library">Enhanced Standard Library Functions</h2> 154<h2 id="library">Enhanced Standard Library Functions</h2>
143 155
144<h3 id="xpcall"><tt>xpcall(f, err [,args...])</tt> passes arguments</h3> 156<h3 id="xpcall"><tt>xpcall(f, err [,args...])</tt> passes arguments</h3>
@@ -166,7 +178,7 @@ in <tt>"-inf"</tt>.
166<h3 id="tonumber"><tt>tonumber()</tt> etc. use builtin string to number conversion</h3> 178<h3 id="tonumber"><tt>tonumber()</tt> etc. use builtin string to number conversion</h3>
167<p> 179<p>
168All string-to-number conversions consistently convert integer and 180All string-to-number conversions consistently convert integer and
169floating-point inputs in decimal and hexadecimal on all platforms. 181floating-point inputs in decimal, hexadecimal and binary on all platforms.
170<tt>strtod()</tt> is <em>not</em> used anymore, which avoids numerous 182<tt>strtod()</tt> is <em>not</em> used anymore, which avoids numerous
171problems with poor C library implementations. The builtin conversion 183problems with poor C library implementations. The builtin conversion
172function provides full precision according to the IEEE-754 standard, it 184function provides full precision according to the IEEE-754 standard, it
@@ -190,6 +202,36 @@ for dot releases (x.y.0 &rarr; x.y.1), but may change with major or
190minor releases (2.0 &rarr; 2.1) or between any beta release. Foreign 202minor releases (2.0 &rarr; 2.1) or between any beta release. Foreign
191bytecode (e.g. from Lua 5.1) is incompatible and cannot be loaded. 203bytecode (e.g. from Lua 5.1) is incompatible and cannot be loaded.
192</p> 204</p>
205<p>
206Note: <tt>LJ_GC64</tt> mode requires a different frame layout, which implies
207a different, incompatible bytecode format for all 64 bit ports. This may be
208rectified in the future.
209</p>
210
211<h3 id="table_new"><tt>table.new(narray, nhash)</tt> allocates a pre-sized table</h3>
212<p>
213An extra library function <tt>table.new()</tt> can be made available via
214<tt>require("table.new")</tt>. This creates a pre-sized table, just like
215the C API equivalent <tt>lua_createtable()</tt>. This is useful for big
216tables if the final table size is known and automatic table resizing is
217too expensive.
218</p>
219
220<h3 id="table_clear"><tt>table.clear(tab)</tt> clears a table</h3>
221<p>
222An extra library function <tt>table.clear()</tt> can be made available
223via <tt>require("table.clear")</tt>. This clears all keys and values
224from a table, but preserves the allocated array/hash sizes. This is
225useful when a table, which is linked from multiple places, needs to be
226cleared and/or when recycling a table for use by the same context. This
227avoids managing backlinks, saves an allocation and the overhead of
228incremental array/hash part growth.
229</p>
230<p>
231Please note, this function is meant for very specific situations. In most
232cases it's better to replace the (usually single) link with a new table
233and let the GC do its work.
234</p>
193 235
194<h3 id="math_random">Enhanced PRNG for <tt>math.random()</tt></h3> 236<h3 id="math_random">Enhanced PRNG for <tt>math.random()</tt></h3>
195<p> 237<p>
@@ -268,6 +310,26 @@ indexes for varargs.</li>
268<li><tt>debug.getupvalue()</tt> and <tt>debug.setupvalue()</tt> handle 310<li><tt>debug.getupvalue()</tt> and <tt>debug.setupvalue()</tt> handle
269C&nbsp;functions.</li> 311C&nbsp;functions.</li>
270<li><tt>debug.upvalueid()</tt> and <tt>debug.upvaluejoin()</tt>.</li> 312<li><tt>debug.upvalueid()</tt> and <tt>debug.upvaluejoin()</tt>.</li>
313<li>Lua/C API extensions:
314<tt>lua_version()</tt>
315<tt>lua_upvalueid()</tt>
316<tt>lua_upvaluejoin()</tt>
317<tt>lua_loadx()</tt>
318<tt>lua_copy()</tt>
319<tt>lua_tonumberx()</tt>
320<tt>lua_tointegerx()</tt>
321<tt>luaL_fileresult()</tt>
322<tt>luaL_execresult()</tt>
323<tt>luaL_loadfilex()</tt>
324<tt>luaL_loadbufferx()</tt>
325<tt>luaL_traceback()</tt>
326<tt>luaL_setfuncs()</tt>
327<tt>luaL_pushmodule()</tt>
328<tt>luaL_newlibtable()</tt>
329<tt>luaL_newlib()</tt>
330<tt>luaL_testudata()</tt>
331<tt>luaL_setmetatable()</tt>
332</li>
271<li>Command line option <tt>-E</tt>.</li> 333<li>Command line option <tt>-E</tt>.</li>
272<li>Command line checks <tt>__tostring</tt> for errors.</li> 334<li>Command line checks <tt>__tostring</tt> for errors.</li>
273</ul> 335</ul>
@@ -293,6 +355,8 @@ exit status.</li>
293<li><tt>debug.setmetatable()</tt> returns object.</li> 355<li><tt>debug.setmetatable()</tt> returns object.</li>
294<li><tt>debug.getuservalue()</tt> and <tt>debug.setuservalue()</tt>.</li> 356<li><tt>debug.getuservalue()</tt> and <tt>debug.setuservalue()</tt>.</li>
295<li>Remove <tt>math.mod()</tt>, <tt>string.gfind()</tt>.</li> 357<li>Remove <tt>math.mod()</tt>, <tt>string.gfind()</tt>.</li>
358<li><tt>package.searchers</tt>.</li>
359<li><tt>module()</tt> returns the module table.</li>
296</ul> 360</ul>
297<p> 361<p>
298Note: this provides only partial compatibility with Lua 5.2 at the 362Note: this provides only partial compatibility with Lua 5.2 at the
@@ -301,6 +365,21 @@ Lua&nbsp;5.1, which prevents implementing features that would otherwise
301break the Lua/C API and ABI (e.g. <tt>_ENV</tt>). 365break the Lua/C API and ABI (e.g. <tt>_ENV</tt>).
302</p> 366</p>
303 367
368<h2 id="lua53">Extensions from Lua 5.3</h2>
369<p>
370LuaJIT supports some extensions from Lua&nbsp;5.3:
371<ul>
372<li>Unicode escape <tt>'\u{XX...}'</tt> embeds the UTF-8 encoding in string literals.</li>
373<li>The argument table <tt>arg</tt> can be read (and modified) by <tt>LUA_INIT</tt> and <tt>-e</tt> chunks.</li>
374<li><tt>io.read()</tt> and <tt>file:read()</tt> accept formats with or without a leading <tt>*</tt>.</li>
375<li><tt>assert()</tt> accepts any type of error object.</li>
376<li><tt>table.move(a1, f, e, t [,a2])</tt>.</li>
377<li><tt>coroutine.isyieldable()</tt>.</li>
378<li>Lua/C API extensions:
379<tt>lua_isyieldable()</tt>
380</li>
381</ul>
382
304<h2 id="exceptions">C++ Exception Interoperability</h2> 383<h2 id="exceptions">C++ Exception Interoperability</h2>
305<p> 384<p>
306LuaJIT has built-in support for interoperating with C++&nbsp;exceptions. 385LuaJIT has built-in support for interoperating with C++&nbsp;exceptions.
@@ -314,26 +393,21 @@ the toolchain used to compile LuaJIT:
314<td class="excinterop">Interoperability</td> 393<td class="excinterop">Interoperability</td>
315</tr> 394</tr>
316<tr class="odd separate"> 395<tr class="odd separate">
317<td class="excplatform">POSIX/x64, DWARF2 unwinding</td> 396<td class="excplatform">External frame unwinding</td>
318<td class="exccompiler">GCC 4.3+</td> 397<td class="exccompiler">GCC, Clang, MSVC</td>
319<td class="excinterop"><b style="color: #00a000;">Full</b></td> 398<td class="excinterop"><b style="color: #00a000;">Full</b></td>
320</tr> 399</tr>
321<tr class="even"> 400<tr class="even">
322<td class="excplatform">Other platforms, DWARF2 unwinding</td> 401<td class="excplatform">Internal frame unwinding + DWARF2</td>
323<td class="exccompiler">GCC</td> 402<td class="exccompiler">GCC, Clang</td>
324<td class="excinterop"><b style="color: #c06000;">Limited</b></td> 403<td class="excinterop"><b style="color: #c06000;">Limited</b></td>
325</tr> 404</tr>
326<tr class="odd"> 405<tr class="odd">
327<td class="excplatform">Windows/x64</td> 406<td class="excplatform">Windows 64 bit</td>
328<td class="exccompiler">MSVC</td> 407<td class="exccompiler">non-MSVC</td>
329<td class="excinterop"><b style="color: #00a000;">Full</b></td> 408<td class="excinterop"><b style="color: #c06000;">Limited</b></td>
330</tr> 409</tr>
331<tr class="even"> 410<tr class="even">
332<td class="excplatform">Windows/x86</td>
333<td class="exccompiler">Any</td>
334<td class="excinterop"><b style="color: #a00000;">No</b></td>
335</tr>
336<tr class="odd">
337<td class="excplatform">Other platforms</td> 411<td class="excplatform">Other platforms</td>
338<td class="exccompiler">Other compilers</td> 412<td class="exccompiler">Other compilers</td>
339<td class="excinterop"><b style="color: #a00000;">No</b></td> 413<td class="excinterop"><b style="color: #a00000;">No</b></td>
@@ -384,14 +458,6 @@ C++ destructors.</li>
384<li>Lua errors <b>cannot</b> be caught on the C++ side.</li> 458<li>Lua errors <b>cannot</b> be caught on the C++ side.</li>
385<li>Throwing Lua errors across C++ frames will <b>not</b> call 459<li>Throwing Lua errors across C++ frames will <b>not</b> call
386C++ destructors.</li> 460C++ destructors.</li>
387<li>Additionally, on Windows/x86 with SEH-based C++&nbsp;exceptions:
388it's <b>not</b> safe to throw a Lua error across any frames containing
389a C++ function with any try/catch construct or using variables with
390(implicit) destructors. This also applies to any functions which may be
391inlined in such a function. It doesn't matter whether <tt>lua_error()</tt>
392is called inside or outside of a try/catch or whether any object actually
393needs to be destroyed: the SEH chain is corrupted and this will eventually
394lead to the termination of the process.</li>
395</ul> 461</ul>
396<br class="flush"> 462<br class="flush">
397</div> 463</div>
diff --git a/doc/install.html b/doc/install.html
index 21866315..be721031 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-2023"> 6<meta name="Copyright" content="Copyright (C) 2005-2023">
7<meta name="Language" content="en"> 7<meta name="Language" content="en">
8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen"> 8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
@@ -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">&raquo;</span></a> 72<a href="https://luajit.org/status.html">Status <span class="ext">&raquo;</span></a>
@@ -121,6 +125,13 @@ MSVC (Visual Studio).</li>
121Please read the instructions given in these files, before changing 125Please read the instructions given in these files, before changing
122any settings. 126any settings.
123</p> 127</p>
128<p>
129All LuaJIT 64 bit ports use 64 bit GC objects by default (<tt>LJ_GC64</tt>).
130For x64, you can select the old 32-on-64 bit mode by adding
131<tt>XCFLAGS=-DLUAJIT_DISABLE_GC64</tt> to the make command.
132Please 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
154make PREFIX=/home/myself/lj2 165make PREFIX=/home/myself/lj2
155</pre> 166</pre>
156<p> 167<p>
157Please use the LuaJIT 2.1 branch to compile for 168Note for macOS: you <b>must</b> set the <tt>MACOSX_DEPLOYMENT_TARGET</tt>
158<b id="osx">macOS (OSX)</b>. 169environment variable to a value supported by your toolchain:
159</p> 170</p>
171<pre class="code">
172MACOSX_DEPLOYMENT_TARGET=XX.YY make
173</pre>
160<h3>Installing LuaJIT</h3> 174<h3>Installing LuaJIT</h3>
161<p> 175<p>
162The top-level Makefile installs LuaJIT by default under 176The top-level Makefile installs LuaJIT by default under
@@ -235,25 +249,36 @@ directory where <tt>luajit.exe</tt> is installed
235 249
236<h2 id="cross">Cross-compiling LuaJIT</h2> 250<h2 id="cross">Cross-compiling LuaJIT</h2>
237<p> 251<p>
252First, let's clear up some terminology:
253</p>
254<ul>
255<li>Host: This is your development system, usually based on a x64 or x86 CPU.</li>
256<li>Target: This is the target system you want LuaJIT to run on, e.g. Android/ARM.</li>
257<li>Toolchain: This comprises a C compiler, linker, assembler and a matching C library.</li>
258<li>Host (or system) toolchain: This is the toolchain used to build native binaries for your host system.</li>
259<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>
260</ul>
261<p>
238The GNU Makefile-based build system allows cross-compiling on any host 262The GNU Makefile-based build system allows cross-compiling on any host
239for any supported target, as long as both architectures have the same 263for any supported target:
240pointer size. If you want to cross-compile to any 32 bit target on an
241x64 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>).
244</p> 264</p>
265<ul>
266<li>Yes, you need a toolchain for both your host <em>and</em> your target!</li>
267<li>Both host and target architectures must have the same pointer size.</li>
268<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>
269<li>64 bit targets always require compilation on a 64 bit host.</li>
270</ul>
245<p> 271<p>
246You need to specify <tt>TARGET_SYS</tt> whenever the host OS and the 272You need to specify <tt>TARGET_SYS</tt> whenever the host OS and the
247target OS differ, or you'll get assembler or linker errors. E.g. if 273target OS differ, or you'll get assembler or linker errors:
248you're compiling on a Windows or macOS host for embedded Linux or Android,
249you need to add <tt>TARGET_SYS=Linux</tt> to the examples below. For a
250minimal target OS, you may need to disable the built-in allocator in
251<tt>src/Makefile</tt> and use <tt>TARGET_SYS=Other</tt>. Don't forget to
252specify the same <tt>TARGET_SYS</tt> for the install step, too.
253</p> 274</p>
275<ul>
276<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>
277<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>
278<li>Don't forget to specify the same <tt>TARGET_SYS</tt> for the install step, too.</li>
279</ul>
254<p> 280<p>
255The examples below only show some popular targets &mdash; please check 281Here are some examples where host and target have the same CPU:
256the comments in <tt>src/Makefile</tt> for more details.
257</p> 282</p>
258<pre class="code"> 283<pre class="code">
259# Cross-compile to a 32 bit binary on a multilib x64 OS 284# Cross-compile to a 32 bit binary on a multilib x64 OS
@@ -271,34 +296,44 @@ use the canonical toolchain triplets for Linux.
271</p> 296</p>
272<p> 297<p>
273Since there's often no easy way to detect CPU features at runtime, it's 298Since there's often no easy way to detect CPU features at runtime, it's
274important to compile with the proper CPU or architecture settings. You 299important to compile with the proper CPU or architecture settings:
275can specify these when building the toolchain yourself. Or add 300</o>
276<tt>-mcpu=...</tt> or <tt>-march=...</tt> to <tt>TARGET_CFLAGS</tt>. For 301<ul>
277ARM it's important to have the correct <tt>-mfloat-abi=...</tt> setting, 302<li>The best way to get consistent results is to specify the correct settings when building the toolchain yourself.</li>
278too. Otherwise, LuaJIT may not run at the full performance of your target 303<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>
279CPU. 304<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>
305<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>
306</ul>
307<p>
308Here are some examples for targets with a different CPU than the host:
280</p> 309</p>
281<pre class="code"> 310<pre class="code">
282# ARM soft-float 311# ARM soft-float
283make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabi- \ 312make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabi- \
284 TARGET_CFLAGS="-mfloat-abi=soft" 313 TARGET_CFLAGS="-mfloat-abi=soft"
285 314
286# ARM soft-float ABI with VFP (example for Cortex-A8) 315# ARM soft-float ABI with VFP (example for Cortex-A9)
287make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabi- \ 316make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabi- \
288 TARGET_CFLAGS="-mcpu=cortex-a8 -mfloat-abi=softfp" 317 TARGET_CFLAGS="-mcpu=cortex-a9 -mfloat-abi=softfp"
289 318
290# ARM hard-float ABI with VFP (armhf, requires recent toolchain) 319# ARM hard-float ABI with VFP (armhf, most modern toolchains)
291make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabihf- 320make HOST_CC="gcc -m32" CROSS=arm-linux-gnueabihf-
292 321
322# ARM64
323make CROSS=aarch64-linux-gnu-
324
293# PPC 325# PPC
294make HOST_CC="gcc -m32" CROSS=powerpc-linux-gnu- 326make HOST_CC="gcc -m32" CROSS=powerpc-linux-gnu-
295# PPC/e500v2 (fast interpreter only)
296make HOST_CC="gcc -m32" CROSS=powerpc-e500v2-linux-gnuspe-
297 327
298# MIPS big-endian 328# MIPS32 big-endian
299make HOST_CC="gcc -m32" CROSS=mips-linux- 329make HOST_CC="gcc -m32" CROSS=mips-linux-gnu-
300# MIPS little-endian 330# MIPS32 little-endian
301make HOST_CC="gcc -m32" CROSS=mipsel-linux- 331make HOST_CC="gcc -m32" CROSS=mipsel-linux-gnu-
332
333# MIPS64 big-endian
334make CROSS=mips-linux- TARGET_CFLAGS="-mips64r2 -mabi=64"
335# MIPS64 little-endian
336make CROSS=mipsel-linux- TARGET_CFLAGS="-mips64r2 -mabi=64"
302</pre> 337</pre>
303<p> 338<p>
304You can cross-compile for <b id="android">Android</b> using the <a href="https://developer.android.com/ndk/"><span class="ext">&raquo;</span>&nbsp;Android NDK</a>. 339You can cross-compile for <b id="android">Android</b> using the <a href="https://developer.android.com/ndk/"><span class="ext">&raquo;</span>&nbsp;Android NDK</a>.
@@ -306,8 +341,17 @@ Please adapt the environment variables to match the install locations and the
306desired target platform. E.g. Android&nbsp;4.1 corresponds to ABI level&nbsp;16. 341desired target platform. E.g. Android&nbsp;4.1 corresponds to ABI level&nbsp;16.
307</p> 342</p>
308<pre class="code"> 343<pre class="code">
309# Android/ARM, armeabi-v7a (ARMv7 VFP), Android 4.1+ (JB) 344# Android/ARM64, aarch64, Android 5.0+ (L)
345NDKDIR=/opt/android/ndk
346NDKBIN=$NDKDIR/toolchains/llvm/prebuilt/linux-x86_64/bin
347NDKCROSS=$NDKBIN/aarch64-linux-android-
348NDKCC=$NDKBIN/aarch64-linux-android21-clang
349make CROSS=$NDKCROSS \
350 STATIC_CC=$NDKCC DYNAMIC_CC="$NDKCC -fPIC" \
351 TARGET_LD=$NDKCC TARGET_AR="$NDKBIN/llvm-ar rcus" \
352 TARGET_STRIP=$NDKBIN/llvm-strip
310 353
354# Android/ARM, armeabi-v7a (ARMv7 VFP), Android 4.1+ (JB)
311NDKDIR=/opt/android/ndk 355NDKDIR=/opt/android/ndk
312NDKBIN=$NDKDIR/toolchains/llvm/prebuilt/linux-x86_64/bin 356NDKBIN=$NDKDIR/toolchains/llvm/prebuilt/linux-x86_64/bin
313NDKCROSS=$NDKBIN/arm-linux-androideabi- 357NDKCROSS=$NDKBIN/arm-linux-androideabi-
@@ -318,9 +362,23 @@ make HOST_CC="gcc -m32" CROSS=$NDKCROSS \
318 TARGET_STRIP=$NDKBIN/llvm-strip 362 TARGET_STRIP=$NDKBIN/llvm-strip
319</pre> 363</pre>
320<p> 364<p>
321Please use the LuaJIT 2.1 branch to compile for 365You 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">&raquo;</span>&nbsp;iOS SDK</a>:
322<b id="ios">iOS</b> (iPhone/iPad). 366</p>
367<p style="font-size: 8pt;">
368Note: <b>the JIT compiler is disabled for iOS</b>, because regular iOS Apps
369are not allowed to generate code at runtime. You'll only get the performance
370of the LuaJIT interpreter on iOS. This is still faster than plain Lua, but
371much slower than the JIT compiler. Please complain to Apple, not me.
372Or use Android. :-p
323</p> 373</p>
374<pre class="code">
375# iOS/ARM64
376ISDKP=$(xcrun --sdk iphoneos --show-sdk-path)
377ICC=$(xcrun --sdk iphoneos --find clang)
378ISDKF="-arch arm64 -isysroot $ISDKP"
379make DEFAULT_CC=clang CROSS="$(dirname $ICC)/" \
380 TARGET_FLAGS="$ISDKF" TARGET_SYS=iOS
381</pre>
324 382
325<h3 id="consoles">Cross-compiling for consoles</h3> 383<h3 id="consoles">Cross-compiling for consoles</h3>
326<p> 384<p>
@@ -364,15 +422,35 @@ and run the build command given in the table:
364<td class="compatx"><tt>ps4build</tt></td> 422<td class="compatx"><tt>ps4build</tt></td>
365</tr> 423</tr>
366<tr class="even"> 424<tr class="even">
425<td class="compatname"><b id="ps5">PS5</b></td>
426<td class="compatbits">64</td>
427<td class="compatx"><tt>ps5build</tt></td>
428</tr>
429<tr class="odd">
367<td class="compatname"><b id="psvita">PS Vita</b></td> 430<td class="compatname"><b id="psvita">PS Vita</b></td>
368<td class="compatbits">32</td> 431<td class="compatbits">32</td>
369<td class="compatx"><tt>psvitabuild</tt></td> 432<td class="compatx"><tt>psvitabuild</tt></td>
370</tr> 433</tr>
371<tr class="odd"> 434<tr class="even">
372<td class="compatname"><b id="xbox360">Xbox 360</b></td> 435<td class="compatname"><b id="xbox360">Xbox 360</b></td>
373<td class="compatbits">32</td> 436<td class="compatbits">32</td>
374<td class="compatx"><tt>xedkbuild</tt></td> 437<td class="compatx"><tt>xedkbuild</tt></td>
375</tr> 438</tr>
439<tr class="odd">
440<td class="compatname"><b id="xboxone">Xbox One</b></td>
441<td class="compatbits">64</td>
442<td class="compatx"><tt>xb1build</tt></td>
443</tr>
444<tr class="even">
445<td class="compatname"><b id="nx32">Nintendo Switch NX32</b></td>
446<td class="compatbits">32</td>
447<td class="compatx"><tt>nxbuild</tt></td>
448</tr>
449<tr class="odd">
450<td class="compatname"><b id="nx64">Nintendo Switch NX64</b></td>
451<td class="compatbits">64</td>
452<td class="compatx"><tt>nxbuild</tt></td>
453</tr>
376</table> 454</table>
377<p> 455<p>
378Please check out the comments in the corresponding <tt>*.bat</tt> 456Please check out the comments in the corresponding <tt>*.bat</tt>
diff --git a/doc/luajit.html b/doc/luajit.html
index 7346acb3..030cf705 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-2023"> 6<meta name="Copyright" content="Copyright (C) 2005-2023">
7<meta name="Language" content="en"> 7<meta name="Language" content="en">
8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen"> 8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
@@ -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">&raquo;</span></a> 110<a href="https://luajit.org/status.html">Status <span class="ext">&raquo;</span></a>
@@ -132,13 +136,13 @@ LuaJIT is Copyright &copy; 2005-2023 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&nbsp;5.1<br>API+ABI</td><td>+&nbsp;JIT</td><td>+&nbsp;BitOp</td><td>+&nbsp;FFI</td><td>Drop-in<br>DLL/.so</td></tr> 148<tr><td>Lua&nbsp;5.1<br>API+ABI</td><td>+&nbsp;JIT</td><td>+&nbsp;BitOp</td><td>+&nbsp;FFI</td><td>Drop-in<br>DLL/.so</td></tr>
diff --git a/doc/running.html b/doc/running.html
index c7d9e9b6..3afc1b56 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-2023"> 6<meta name="Copyright" content="Copyright (C) 2005-2023">
7<meta name="Language" content="en"> 7<meta name="Language" content="en">
8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen"> 8<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
@@ -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">&raquo;</span></a> 71<a href="https://luajit.org/status.html">Status <span class="ext">&raquo;</span></a>
@@ -106,6 +110,7 @@ are accepted:
106<li><tt>-t type</tt> &mdash; Set output file type (default: auto-detect from output name).</li> 110<li><tt>-t type</tt> &mdash; Set output file type (default: auto-detect from output name).</li>
107<li><tt>-a arch</tt> &mdash; Override architecture for object files (default: native).</li> 111<li><tt>-a arch</tt> &mdash; Override architecture for object files (default: native).</li>
108<li><tt>-o os</tt> &mdash; Override OS for object files (default: native).</li> 112<li><tt>-o os</tt> &mdash; Override OS for object files (default: native).</li>
113<li><tt>-F name</tt> &mdash; Override filename (default: input filename).</li>
109<li><tt>-e chunk</tt> &mdash; Use chunk string as input.</li> 114<li><tt>-e chunk</tt> &mdash; Use chunk string as input.</li>
110<li><tt>-</tt> (a single minus sign) &mdash; Use stdin as input and/or stdout as output.</li> 115<li><tt>-</tt> (a single minus sign) &mdash; Use stdin as input and/or stdout as output.</li>
111</ul> 116</ul>
@@ -171,6 +176,7 @@ Here are the available LuaJIT control commands:
171<li id="j_flush"><tt>-jflush</tt> &mdash; Flushes the whole cache of compiled code.</li> 176<li id="j_flush"><tt>-jflush</tt> &mdash; Flushes the whole cache of compiled code.</li>
172<li id="j_v"><tt>-jv</tt> &mdash; Shows verbose information about the progress of the JIT compiler.</li> 177<li id="j_v"><tt>-jv</tt> &mdash; Shows verbose information about the progress of the JIT compiler.</li>
173<li id="j_dump"><tt>-jdump</tt> &mdash; Dumps the code and structures used in various compiler stages.</li> 178<li id="j_dump"><tt>-jdump</tt> &mdash; Dumps the code and structures used in various compiler stages.</li>
179<li id="j_p"><tt>-jp</tt> &mdash; Start the <a href="ext_profiler.html">integrated profiler</a>.</li>
174</ul> 180</ul>
175<p> 181<p>
176The <tt>-jv</tt> and <tt>-jdump</tt> commands are extension modules 182The <tt>-jv</tt> and <tt>-jdump</tt> commands are extension modules
@@ -215,6 +221,12 @@ mix the three forms, but note that setting an optimization level
215overrides all earlier flags. 221overrides all earlier flags.
216</p> 222</p>
217<p> 223<p>
224Note that <tt>-Ofma</tt> is not enabled by default at any level,
225because it affects floating-point result accuracy. Only enable this,
226if you fully understand the trade-offs of FMA for performance (higher),
227determinism (lower) and numerical accuracy (higher).
228</p>
229<p>
218Here are the available flags and at what optimization levels they 230Here are the available flags and at what optimization levels they
219are enabled: 231are enabled:
220</p> 232</p>
@@ -246,6 +258,8 @@ are enabled:
246<td class="flag_name">sink</td><td class="flag_level">&nbsp;</td><td class="flag_level">&nbsp;</td><td class="flag_level">&bull;</td><td class="flag_desc">Allocation/Store Sinking</td></tr> 258<td class="flag_name">sink</td><td class="flag_level">&nbsp;</td><td class="flag_level">&nbsp;</td><td class="flag_level">&bull;</td><td class="flag_desc">Allocation/Store Sinking</td></tr>
247<tr class="even"> 259<tr class="even">
248<td class="flag_name">fuse</td><td class="flag_level">&nbsp;</td><td class="flag_level">&nbsp;</td><td class="flag_level">&bull;</td><td class="flag_desc">Fusion of operands into instructions</td></tr> 260<td class="flag_name">fuse</td><td class="flag_level">&nbsp;</td><td class="flag_level">&nbsp;</td><td class="flag_level">&bull;</td><td class="flag_desc">Fusion of operands into instructions</td></tr>
261<tr class="odd">
262<td class="flag_name">fma </td><td class="flag_level">&nbsp;</td><td class="flag_level">&nbsp;</td><td class="flag_level">&nbsp;</td><td class="flag_desc">Fused multiply-add</td></tr>
249</table> 263</table>
250<p> 264<p>
251Here are the parameters and their default settings: 265Here are the parameters and their default settings:
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-08-15 07:11:00 +0000