【免费下载】 LuaJIT FFI库API详解：从基础到高级应用

前言

LuaJIT的FFI（Foreign Function Interface）库是一个强大的工具，它允许Lua代码直接调用C函数和使用C数据结构，而无需编写任何胶水代码。本文将全面解析FFI库提供的API函数，帮助开发者充分利用这一功能。

核心概念解析

在深入API之前，我们需要理解几个关键术语：

1. cdecl：C类型声明的Lua字符串表示
2. ctype：C类型对象，由ffi.typeof()返回的特殊cdata
3. cdata：C数据对象，持有对应ctype的值
4. cb：回调对象，持有特殊函数指针的C数据对象
5. VLA：可变长度数组（如int[?]）
6. VLS：可变长度结构体（最后一个元素是VLA的结构体）

外部符号声明与访问

ffi.cdef(def)

声明C类型或外部符号（变量或函数）。参数必须是Lua字符串，推荐使用以下语法：

ffi.cdef[[
typedef struct { int x, y; } point_t;
extern int printf(const char *fmt, ...);
]]

重要说明：

• 只声明符号，不绑定地址
• 不支持C预处理器指令（除了#pragma pack）
• 每个声明以分号分隔，最后一个分号可省略

默认C库命名空间：ffi.C

这是默认的C库命名空间，绑定到目标系统的默认符号集：

• POSIX系统：全局命名空间中的符号（包括libc、libm等）
• Windows系统：exe、lua51.dll、CRT库等导出的符号

动态库加载：ffi.load(name [,global])

加载动态库并返回新的C库命名空间：

• name为路径时直接加载
• 否则按系统规则查找：
  • POSIX：自动添加.so和lib前缀
  • Windows：自动添加.dll后缀
• global为true时（仅POSIX）将符号加载到全局命名空间

创建cdata对象

ffi.new(ct [,nelem] [,init...])

创建指定类型的cdata对象：

• VLA/VLS类型需要nelem参数
• 可选的init参数用于初始化
• 性能提示：对频繁创建的类型，先用ffi.typeof()获取ctype再重复使用

常见陷阱：

• 匿名结构体每次会创建新类型，建议使用命名结构体或typedef

ffi.typeof(ct)

创建ctype对象，常用于解析cdecl后重复使用：

local point_t = ffi.typeof("struct { int x, y; }")
local p1 = point_t(1, 2)
local p2 = point_t(3, 4)

ffi.cast(ct, init)

创建标量cdata对象，使用强制转换规则初始化：

• 主要用于绕过指针兼容性检查
• 可在指针和地址间转换

ffi.metatype(ct, metatable)

创建带元表的ctype对象：

• 仅适用于结构体/联合体、复数和向量
• 元表关联是永久的
• 所有标准Lua元方法都可用

ffi.gc(cdata, finalizer)

为指针或聚合cdata对象关联终结器：

local p = ffi.gc(ffi.C.malloc(100), ffi.C.free)
-- 当p不再被引用时自动调用free

C类型信息查询

基本类型信息函数

1. ffi.sizeof(ct [,nelem])：返回类型大小（字节）
2. ffi.alignof(ct)：返回类型对齐要求（字节）
3. ffi.offsetof(ct, field)：返回字段偏移量（对位字段额外返回位置和大小）
4. ffi.istype(ct, obj)：检查对象是否具有指定C类型

实用工具函数

ffi.errno([newerr])

获取/设置最后的C错误号：

• 便携且跨操作系统
• 只在相关C函数指示错误时有效
• 建议尽快调用，避免被其他操作覆盖

ffi.string(ptr [,len])

从指针数据创建Lua字符串：

• 无len时视为零终止字符串
• 有len时可包含嵌入零值
• 注意：返回的是数据副本

内存操作函数

1. ffi.copy(dst, src, len)：内存复制
   • 比C的memcpy/strcpy更快（可内联）
2. ffi.copy(dst, str)：复制Lua字符串（包括零终止符）
3. ffi.fill(dst, len [,c])：内存填充
   • 比memset更快（注意参数顺序不同）

目标系统信息

ffi.abi(param)

查询目标ABI特性，常用参数包括：

• 32bit/64bit：架构位数
• le/be：字节序
• fpu：硬件浮点单元
• softfp/hardfp：浮点调用约定
• eabi/win：ABI变体

最佳实践建议

1. 类型定义：避免重复解析相同cdecl，使用ffi.typeof()缓存ctype
2. 内存管理：对分配的资源总是关联适当的终结器
3. 错误处理：及时检查ffi.errno()，特别是在系统调用后
4. 性能优化：
   • 优先使用ffi.copy()/ffi.fill()而非C库函数
   • 为已知长度的字符串操作提供长度参数
5. 跨平台考虑：使用ffi.abi()检查目标特性，编写条件代码

通过掌握这些API，开发者可以在Lua中无缝集成C代码，实现高性能的混合编程解决方案。FFI不仅消除了传统Lua/C绑定的复杂性，还能在JIT编译下获得接近原生C的性能。