介绍

LuaJIT is a Just-In-Time Compiler (JIT) for the Lua programming language. Lua is a powerful, dynamic and light-weight programming language. It may be embedded or used as a general-purpose, stand-alone language.

LuaJIT is fully upwards-compatible with Lua 5.1. It supports all standard Lua library functions and the full set of Lua/C API functions.

LuaJIT is also fully ABI-compatible to Lua 5.1 at the linker/dynamic loader level. This means you can compile a C module against the standard Lua headers and load the same shared library from either Lua or LuaJIT.

LuaJIT extends the standard Lua VM with new functionality and adds several extension modules. Please note, this page is only about functional enhancements and not about performance enhancements, such as the optimized VM, the faster interpreter or the JIT compiler.

Extensions Modules

LuaJIT comes with several built-in extension modules:

bit.* — Bitwise operations

LuaJIT supports all bitwise operations as defined by Lua BitOp:

bit.tobit  bit.tohex  bit.bnot    bit.band bit.bor  bit.bxor
bit.lshift bit.rshift bit.arshift bit.rol  bit.ror  bit.bswap

This module is a LuaJIT built-in — you don’t need to download or install Lua BitOp. The Lua BitOp site has full documentation for all Lua BitOp API functions. The FFI adds support for 64 bit bitwise operations, using the same API functions.

Please make sure to require the module before using any of its functions:

local bit = require("bit")

An already installed Lua BitOp module is ignored by LuaJIT. This way you can use bit operations from both Lua and LuaJIT on a shared installation.

ffi.* — FFI library

The FFI library allows calling external C functions and the use of C data structures from pure Lua code【重点】.

jit.* — JIT compiler control

The functions in this module control the behavior of the JIT compiler engine.

C API extensions

LuaJIT adds some extra functions to the Lua/C API.

Profiler

LuaJIT has an integrated profiler.

Enhanced Standard Library Functions

xpcall(f, err [,args...]) passes arguments

Unlike the standard implementation in Lua 5.1, xpcall() passes any arguments after the error function to the function which is called in a protected context.

例子： xpcall 的使用

local function divide(a, b)
    if b == 0 then
        error("Division by zero")
    end
    return a / b
end

local function error_handler(err)
    return "Handled error: " .. err
end

local function safe_divide(a, b)
    local status, result = xpcall(divide, error_handler, a, b)
    if status then
        return result
    else
        print("Custom Error Handler: " .. result)  -- 自定义错误处理
        return nil
    end
end

print(safe_divide(10, 2))  -- 输出：5
print(safe_divide(10, 0))  -- 输出：Custom Error Handler: Handled error: Division by zero

load*() handle UTF-8 source code

Non-ASCII characters are handled transparently by the Lua source code parser. This allows the use of UTF-8 characters in identifiers and strings. A UTF-8 BOM is skipped at the start of the source code.

例子：变量名是中文

local 姓名 = "张三"
local 年龄 = 25

print("姓名：" .. 姓名)
print("年龄：" .. 年龄)

使用标准的lua5.1会语法报错

load*() add a mode parameter

As an extension from Lua 5.2, the functions loadstring(), loadfile() and (new) load() add an optional mode parameter.

The default mode string is "bt", which allows loading of both source code and bytecode. Use "t" to allow only source code or "b" to allow only bytecode to be loaded.

By default, the load* functions generate the native bytecode format. For cross-compilation purposes, add W to the mode string to force the 32 bit format and X to force the 64 bit format. Add both to force the opposite format. 【同时使用 W 和 X 来强制使用与本机平台相反的字节码格式】Note that non-native bytecode generated by load* cannot be run, but can still be passed to string.dump.

string.dump(f [,mode]) generates portable bytecode

An extra argument has been added to string.dump(). If set to true or to a string which contains the character s, ‘stripped’ bytecode without debug information is generated. This speeds up later bytecode loading and reduces memory usage. See also the -b command line option.

The generated bytecode is portable and can be loaded on any architecture that LuaJIT supports. However, the bytecode compatibility versions must match. Bytecode only stays compatible within a major+minor version (x.y.aaa → x.y.bbb), except for development branches. Foreign bytecode (e.g. from Lua 5.1) is incompatible and cannot be loaded.

Note: LJ_GC64 mode requires a different frame layout, which implies a different, incompatible bytecode format between 32 bit and 64 bit ports. This may be rectified in the future. In the meantime, use the W and X modes of the load* functions for cross-compilation purposes.

Due to VM hardening, bytecode is not deterministic. Add d to the mode string to dump it in a deterministic manner: identical source code always gives a byte-for-byte identical bytecode dump. This feature is mainly useful for reproducible builds.

table.new(narray, nhash) allocates a pre-sized table

An extra library function table.new() can be made available via require("table.new"). This creates a pre-sized table, just like the C API equivalent lua_createtable(). This is useful for big tables if the final table size is known and automatic table resizing is too expensive.

例子：table.new 的使用

require("table.new")

t = table.new(1,1)
t[1] = 1
t["a"] = 2
print(type(t)) -- table

table.clear(tab) clears a table

An extra library function table.clear() can be made available via require("table.clear"). This clears all keys and values from a table, but preserves the allocated array/hash sizes. This is useful when a table, which is linked from multiple places, needs to be cleared and/or when recycling a table for use by the same context. This avoids managing backlinks, saves an allocation and the overhead of incremental array/hash part growth.

Please note, this function is meant for very specific situations. In most cases it’s better to replace the (usually single) link with a new table and let the GC do its wo

例子：table.clear 的使用

local tab = {1, 2, 3, a = 10, b = 20}

-- 清空表，但保留表的内存分配
require("table.clear")  -- 确保你加载了这个扩展函数
table.clear(tab)

-- 现在 tab 变成了空表，但它的内存结构（数组和哈希大小）没有改变
print(next(tab))  -- 输出 nil，因为表已经没有内容了

Enhanced PRNG for math.random()

LuaJIT uses a Tausworthe PRNG with period 2^223 to implement math.random() and math.randomseed(). The quality of the PRNG results is much superior compared to the standard Lua implementation, which uses the platform-specific ANSI rand().

The PRNG generates the same sequences from the same seeds on all platforms and makes use of all bits in the seed argument. math.random() without arguments generates 52 pseudo-random bits for every call. The result is uniformly distributed between 0.0 and 1.0. It’s correctly scaled up and rounded for math.random(n [,m]) to preserve uniformity.

Call math.randomseed() without any arguments to seed it from system entropy.

Important: Neither this nor any other PRNG based on the simplistic math.random() API is suitable for cryptographic use.

io.* functions handle 64 bit file offsets

The file I/O functions in the standard io.* library handle 64 bit file offsets. In particular, this means it’s possible to open files larger than 2 Gigabytes and to reposition or obtain the current file position for offsets beyond 2 GB (fp:seek() method).

debug.* functions identify metamethods

debug.getinfo() and lua_getinfo() also return information about invoked metamethods. The namewhat field is set to "metamethod" and the name field has the name of the corresponding metamethod (e.g. "__index").

Fully Resumable VM

The LuaJIT VM is fully resumable. This means you can yield from a coroutine even across contexts, where this would not possible with the standard Lua 5.1 VM: e.g. you can yield across pcall() and xpcall(), across iterators and across metamethods.

例子：协程在 pcall 中 yield

local function testCoroutine()
    pcall(function()
        print("Start coroutine")
        coroutine.yield() -- 在这里挂起协程
        print("Resumed coroutine")
    end)
end

local co = coroutine.create(testCoroutine)


coroutine.resume(co) -- 启动协程
coroutine.resume(co) -- 恢复协程

输出

Start coroutine
Resumed coroutine

而在标准的lua5.1中只输出

Start coroutine

例子：协程在迭代器中 yield

local coroutine = require("coroutine")

-- 一个自定义的迭代器，它会在每次返回一个元素时进行yield
function my_iterator(start, _end)
  local i = start
  return function()
    if i <= _end then
      coroutine.yield()  -- 在返回每个元素时进行yield
      i = i + 1
      return i - 1
    end
  end
end

-- 创建一个协程来使用迭代器
local co = coroutine.create(function()
  for value in my_iterator(1, 5) do
    print("迭代值: ", value)
    -- 在这里可以插入一些逻辑，例如，暂停协程，模拟某些异步操作
  end
end)

-- 在主线程中控制协程的恢复
while coroutine.status(co) ~= "dead" do
  print("恢复协程")
  coroutine.resume(co)
  -- 每次恢复时迭代器会继续从`yield`的位置往下执行
end

输出

恢复协程
恢复协程
迭代值:         1
恢复协程
迭代值:         2
恢复协程
迭代值:         3
恢复协程
迭代值:         4
恢复协程
迭代值:         5

而标准的lua5.1输出

恢复协程

Extensions from Lua 5.2

LuaJIT supports some language and library extensions from Lua 5.2. Features that are unlikely to break existing code are unconditionally enabled:

• goto and ::labels::.

例子：goto 的使用

local i = 0

::start::  -- 标签定义

if i < 5 then
    print("i is " .. i)
    i = i + 1
    goto start  -- 跳回到 start 标签
end

print("Finished")

• Hex escapes '\x3F' and '\z' escape in strings.

The escape sequence ‘\z’ skips the following span of white-space characters, including line breaks; it is particularly useful to break and indent a long literal string into multiple lines without adding the newlines and spaces into the string contents.

例子：'\z’转义字符的使用

local long_str ="This is a very long string that we\z
    want to break into multiple lines,\z
    but without including the newlines\z
    or spaces in the actual string content."

print(long_str)

A byte in a literal string can also be specified by its numerical value. This can be done with the escape sequence \xXX, where XX is a sequence of exactly two hexadecimal digits, or with the escape sequence \ddd, where ddd is a sequence of up to three decimal digits. (Note that if a decimal escape is to be followed by a digit, it must be expressed using exactly three digits.) Strings in Lua can contain any 8-bit value, including embedded zeros, which can be specified as ‘\0’.

• load(string|reader [, chunkname [,mode [,env]]]).
• loadstring() is an alias for load().
• loadfile(filename [,mode [,env]]).
• math.log(x [,base]).
• string.rep(s, n [,sep]).
• string.format(): %q reversible. %s checks __tostring. %a and "%A added.
• String matching pattern %g added.【%g: represents all printable characters except space.】
• io.read("*L").【“\*L”: reads the next line keeping the end of line (if present), returning nil on end of file.】
• io.lines() and file:lines() process io.read() options.【和 io.read() 函数一样的参数】
• os.exit(status|true|false [,close]).
• package.searchpath(name, path [, sep [, rep]]).
• package.loadlib(name, "*").

例子：package.loadlib 的使用

假设你有两个 C 库：libcore.so 和 libext.so。libext.so 依赖于 libcore.so，但是你不想让 libcore.so 的函数直接暴露到 Lua 环境中，而是只需要确保它的符号可以在 libext.so 中使用。

-- 仅仅加载 libcore.so，并确保符号链接到 Lua 环境中
package.loadlib("libcore.so", "*")

-- 加载并使用 libext.so（它依赖于 libcore.so 的符号）
package.loadlib("libext.so", "luaopen_libext")

• debug.getinfo() returns nparams and isvararg for option "u".
• debug.getlocal() accepts function instead of level.
• debug.getlocal() and debug.setlocal() accept negative indexes for varargs.
• debug.getupvalue() and debug.setupvalue() handle C functions.
• debug.upvalueid() and debug.upvaluejoin().
• Lua/C API extensions: lua_version() lua_upvalueid() lua_upvaluejoin() lua_loadx() lua_copy() lua_tonumberx() lua_tointegerx() luaL_fileresult() luaL_execresult() luaL_loadfilex() luaL_loadbufferx() luaL_traceback() luaL_setfuncs() luaL_pushmodule() luaL_newlibtable() luaL_newlib() luaL_testudata() luaL_setmetatable()
• Command line option -E.
• Command line checks __tostring for errors.

Extensions from Lua 5.3

LuaJIT supports some extensions from Lua 5.3:

• Unicode escape '\u{XX...}' embeds the UTF-8 encoding in string literals.【支持 Unicode 转义！】
• The argument table arg can be read (and modified) by LUA_INIT and -e chunks.
• io.read() and file:read() accept formats with or without a leading *.
• assert() accepts any type of error object.
• table.move(a1, f, e, t [,a2]).

Moves elements from table a1 to table a2, performing the equivalent to the following multiple assignment: a2[t],··· = a1[f],···,a1[e]. The default for a2 is a1. The destination range can overlap with the source range. The number of elements to be moved must fit in a Lua integer.

Returns the destination table a2.

• coroutine.isyieldable().

Returns 1 if the given coroutine can yield, and 0 otherwise.

• Lua/C API extensions: lua_isyieldable()