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