README.md
1# Name
2
3openresty/luajit2 - OpenResty's maintained branch of LuaJIT.
4
5Table of Contents
6=================
7
8* [Name](#name)
9* [Description](#description)
10* [OpenResty extensions](#openresty-extensions)
11 * [New Lua APIs](#new-lua-apis)
12 * [table.isempty](#tableisempty)
13 * [table.isarray](#tableisarray)
14 * [table.nkeys](#tablenkeys)
15 * [table.clone](#tableclone)
16 * [jit.prngstate](#jitprngstate)
17 * [thread.exdata](#threadexdata)
18 * [thread.exdata2](#threadexdata2)
19 * [New C API](#new-c-api)
20 * [lua_setexdata](#lua_setexdata)
21 * [lua_getexdata](#lua_getexdata)
22 * [lua_setexdata2](#lua_setexdata2)
23 * [lua_getexdata2](#lua_getexdata2)
24 * [lua_resetthread](#lua_resetthread)
25 * [New macros](#new-macros)
26 * [`OPENRESTY_LUAJIT`](#openresty_luajit)
27 * [`HAVE_LUA_RESETTHREAD`](#have_lua_resetthread)
28 * [Optimizations](#optimizations)
29 * [Updated JIT default parameters](#updated-jit-default-parameters)
30 * [String hashing](#string-hashing)
31 * [Updated bytecode options](#updated-bytecode-options)
32 * [New `-bL` option](#new--bl-option)
33 * [Updated `-bl` option](#updated--bl-option)
34 * [Miscellaneous](#miscellaneous)
35* [Copyright & License](#copyright--license)
36
37# Description
38
39This is the official OpenResty branch of LuaJIT. It is not to be considered a
40fork, since we still regularly synchronize changes from the upstream LuaJIT
41project (https://github.com/LuaJIT/LuaJIT).
42
43# OpenResty extensions
44
45Additionally to synchronizing upstream changes, we introduce our own changes
46which haven't been merged yet (or never will be). This document describes those
47changes that are specific to this branch.
48
49## New Lua APIs
50
51### table.isempty
52
53**syntax:** *res = isempty(tab)*
54
55Returns `true` when the given Lua table contains neither non-nil array elements
56nor non-nil key-value pairs, or `false` otherwise.
57
58This API can be JIT compiled.
59
60Usage:
61
62```lua
63local isempty = require "table.isempty"
64
65print(isempty({})) -- true
66print(isempty({nil, dog = nil})) -- true
67print(isempty({"a", "b"})) -- false
68print(isempty({nil, 3})) -- false
69print(isempty({cat = 3})) -- false
70```
71
72[Back to TOC](#table-of-contents)
73
74### table.isarray
75
76**syntax:** *res = isarray(tab)*
77
78Returns `true` when the given Lua table is a pure array-like Lua table, or
79`false` otherwise.
80
81Empty Lua tables are treated as arrays.
82
83This API can be JIT compiled.
84
85Usage:
86
87```lua
88local isarray = require "table.isarray"
89
90print(isarray{"a", true, 3.14}) -- true
91print(isarray{dog = 3}) -- false
92print(isarray{}) -- true
93```
94
95[Back to TOC](#table-of-contents)
96
97### table.nkeys
98
99**syntax:** *n = nkeys(tab)*
100
101Returns the total number of elements in a given Lua table (i.e. from both the
102array and hash parts combined).
103
104This API can be JIT compiled.
105
106Usage:
107
108```lua
109local nkeys = require "table.nkeys"
110
111print(nkeys({})) -- 0
112print(nkeys({ "a", nil, "b" })) -- 2
113print(nkeys({ dog = 3, cat = 4, bird = nil })) -- 2
114print(nkeys({ "a", dog = 3, cat = 4 })) -- 3
115```
116
117[Back to TOC](#table-of-contents)
118
119### table.clone
120
121**syntax:** *t = clone(tab)*
122
123Returns a shallow copy of the given Lua table.
124
125This API can be JIT compiled.
126
127Usage:
128
129```lua
130local clone = require "table.clone"
131
132local x = {x=12, y={5, 6, 7}}
133local y = clone(x)
134... use y ...
135```
136
137**Note:** We observe 7% over-all speedup in the edgelang-fan compiler's
138compiling speed whose Lua is generated by the fanlang compiler.
139
140**Note bis:** Deep cloning is planned to be supported by adding `true` as a
141second argument.
142
143[Back to TOC](#table-of-contents)
144
145### jit.prngstate
146
147**syntax:** *state = jit.prngstate(state?)*
148
149Returns (and optionally sets) the current PRNG state (an array of 8 Lua
150numbers with 32-bit integer values) currently used by the JIT compiler.
151
152When the `state` argument is non-nil, it is expected to be an array of up to 8
153unsigned Lua numbers, each with value less than 2\*\*32-1. This will set the
154current PRNG state and return the state that was overridden.
155
156**Note:** For backward compatibility, `state` argument can also be an unsigned
157Lua number less than 2\*\*32-1.
158
159**Note:** When the `state` argument is an array and less than 8 numbers, or the
160`state` is a number, the remaining positions are filled with zeros.
161
162Usage:
163
164```lua
165local state = jit.prngstate()
166local oldstate = jit.prngstate{ a, b, c, ... }
167
168jit.prngstate(32) -- {32, 0, 0, 0, 0, 0, 0, 0}
169jit.prngstate{432, 23, 50} -- {432, 23, 50, 0, 0, 0, 0, 0}
170```
171
172**Note:** This API has no effect if LuaJIT is compiled with
173`-DLUAJIT_DISABLE_JIT`, and will return a table with all `0`.
174
175[Back to TOC](#table-of-contents)
176
177### thread.exdata
178
179**syntax:** *exdata = th_exdata(data?)*
180
181This API allows for embedding user data into a thread (`lua_State`).
182
183The retrieved `exdata` value on the Lua land is represented as a cdata object
184of the ctype `void*`.
185
186As of this version, retrieving the `exdata` (i.e. `th_exdata()` without any
187argument) can be JIT compiled.
188
189Usage:
190
191```lua
192local th_exdata = require "thread.exdata"
193
194th_exdata(0xdeadbeefLL) -- set the exdata of the current Lua thread
195local exdata = th_exdata() -- fetch the exdata of the current Lua thread
196```
197
198Also available are the following public C API functions for manipulating
199`exdata` on the C land:
200
201```C
202void lua_setexdata(lua_State *L, void *exdata);
203void *lua_getexdata(lua_State *L);
204```
205
206The `exdata` pointer is initialized to `NULL` when the main thread is created.
207Any child Lua thread will inherit its parent's `exdata`, but still can override
208it.
209
210**Note:** This API will not be available if LuaJIT is compiled with
211`-DLUAJIT_DISABLE_FFI`.
212
213**Note bis:** This API is used internally by the OpenResty core, and it is
214strongly discouraged to use it yourself in the context of OpenResty.
215
216[Back to TOC](#table-of-contents)
217
218### thread.exdata2
219
220**syntax:** *exdata = th_exdata2(data?)*
221
222Similar to `thread.exdata` but for a 2nd separate user data as a pointer value.
223
224[Back to TOC](#table-of-contents)
225
226## New C API
227
228### lua_setexdata
229
230```C
231void lua_setexdata(lua_State *L, void *exdata);
232```
233
234Sets extra user data as a pointer value to the current Lua state or thread.
235
236[Back to TOC](#table-of-contents)
237
238### lua_getexdata
239
240```C
241void *lua_getexdata(lua_State *L);
242```
243
244Gets extra user data as a pointer value to the current Lua state or thread.
245
246[Back to TOC](#table-of-contents)
247
248### lua_setexdata2
249
250```C
251void lua_setexdata2(lua_State *L, void *exdata2);
252```
253
254Similar to `lua_setexdata` but for a 2nd user data (pointer) value.
255
256[Back to TOC](#table-of-contents)
257
258### lua_getexdata2
259
260```C
261void *lua_getexdata2(lua_State *L);
262```
263
264Similar to `lua_getexdata` but for a 2nd user data (pointer) value.
265
266[Back to TOC](#table-of-contents)
267
268### lua_resetthread
269
270```C
271void lua_resetthread(lua_State *L, lua_State *th);
272```
273
274Resets the state of `th` to the initial state of a newly created Lua thread
275object as returned by `lua_newthread()`. This is mainly for Lua thread
276recycling. Lua threads in arbitrary states (like yielded or errored) can be
277reset properly.
278
279The current implementation does not shrink the already allocated Lua stack
280though. It only clears it.
281
282[Back to TOC](#table-of-contents)
283
284## New macros
285
286The macros described in this section have been added to this branch.
287
288[Back to TOC](#table-of-contents)
289
290### `OPENRESTY_LUAJIT`
291
292In the `luajit.h` header file, a new macro `OPENRESTY_LUAJIT` was defined to
293help distinguishing this OpenResty-specific branch of LuaJIT.
294
295### `HAVE_LUA_RESETTHREAD`
296
297This macro is set when the `lua_resetthread` C API is present.
298
299[Back to TOC](#table-of-contents)
300
301## Optimizations
302
303### Updated JIT default parameters
304
305We use more appressive default JIT compiler options to help large OpenResty
306Lua applications.
307
308The following `jit.opt` options are used by default:
309
310```lua
311maxtrace=8000
312maxrecord=16000
313minstitch=3
314maxmcode=40960 -- in KB
315```
316
317[Back to TOC](#table-of-contents)
318
319### String hashing
320
321This optimization only applies to Intel CPUs supporting the SSE 4.2 instruction
322sets. For such CPUs, and when this branch is compiled with `-msse4.2`, the
323string hashing function used for strings interning will be based on an
324optimized crc32 implementation (see `lj_str_new()`).
325
326This optimization still provides constant-time hashing complexity (`O(n)`), but
327makes hash collision attacks harder for strings up to 127 bytes of size.
328
329[Back to TOC](#table-of-contents)
330
331## Updated bytecode options
332
333### New `-bL` option
334
335The bytecode option `L` was added to display Lua sources line numbers.
336
337For example, `luajit -bL -e 'print(1)'` now produces bytecode dumps like below:
338
339```
340-- BYTECODE -- "print(1)":0-1
3410001 [1] GGET 0 0 ; "print"
3420002 [1] KSHORT 1 1
3430003 [1] CALL 0 1 2
3440004 [1] RET0 0 1
345```
346
347The `[N]` column corresponds to the Lua source line number. For example, `[1]`
348means "the first source line".
349
350[Back to TOC](#table-of-contents)
351
352### Updated `-bl` option
353
354The bytecode option `l` was updated to display the constant tables of each Lua
355prototype.
356
357For example, `luajit -bl a.lua'` now produces bytecode dumps like below:
358
359```
360-- BYTECODE -- a.lua:0-48
361KGC 0 "print"
362KGC 1 "hi"
363KGC 2 table
364KGC 3 a.lua:17
365KN 1 1000000
366KN 2 1.390671161567e-309
367...
368```
369
370[Back to TOC](#table-of-contents)
371
372## Miscellaneous
373
374* Increased the maximum number of allowed upvalues from 60 to 120.
375* Various important bugfixes in the JIT compiler and Lua VM which have
376 not been merged in upstream LuaJIT.
377* Removed the GCC 4 requirement for x86 on older systems such as Solaris i386.
378* In the `Makefile` file, make sure we always install the symlink for "luajit"
379 even for alpha or beta versions.
380* Applied a patch to fix DragonFlyBSD compatibility. Note: this is not an
381 officially supported target.
382* feature: jit.dump: output Lua source location after every BC.
383* feature: added internal memory-buffer-based trace entry/exit/start-recording
384 event logging, mainly for debugging bugs in the JIT compiler. it requires
385 `-DLUA_USE_TRACE_LOGS` when building LuaJIT.
386* feature: save `g->jit_base` to `g->saved_jit_base` before `lj_err_throw`
387 clears `g->jit_base` which makes it impossible to get Lua backtrace in such
388 states.
389
390[Back to TOC](#table-of-contents)
391
392# Copyright & License
393
394LuaJIT is a Just-In-Time (JIT) compiler for the Lua programming language.
395
396Project Homepage: http://luajit.org/
397
398LuaJIT is Copyright (C) 2005-2019 Mike Pall.
399
400Additional patches for OpenResty are copyrighted by Yichun Zhang and OpenResty
401Inc.:
402
403Copyright (C) 2017-2019 Yichun Zhang. All rights reserved.
404
405Copyright (C) 2017-2019 OpenResty Inc. All rights reserved.
406
407LuaJIT is free software, released under the MIT license.
408See full Copyright Notice in the COPYRIGHT file or in luajit.h.
409
410Documentation for the official LuaJIT is available in HTML format.
411Please point your favorite browser to:
412
413 doc/luajit.html
414
415[Back to TOC](#table-of-contents)
416