LuaJIT FFI API终极指南：从基础调用到高级用法的完整教程

gitblog_00025

479人浏览 · 2026-01-01 03:11:07

gitblog_00025 · 2026-01-01 03:11:07 发布

LuaJIT FFI API终极指南：从基础调用到高级用法的完整教程

【免费下载链接】LuaJIT Mirror of the LuaJIT git repository 项目地址: https://gitcode.com/gh_mirrors/lu/LuaJIT

LuaJIT FFI（Foreign Function Interface）是LuaJIT提供的强大扩展，它允许Lua代码直接调用C语言函数和访问C数据结构，无需编写繁琐的C扩展。本教程将带你从基础到高级，全面掌握LuaJIT FFI API的使用方法，让你轻松实现Lua与C的无缝交互。

一、FFI基础：快速入门指南

1.1 什么是FFI？

FFI（Foreign Function Interface）是LuaJIT提供的核心扩展功能，它允许Lua代码直接与C语言库进行交互。通过FFI，你可以在Lua中声明C函数、定义C数据结构，并直接调用动态链接库中的函数，无需编写任何C代码或包装器。

1.2 为什么选择LuaJIT FFI？

性能卓越：LuaJIT的JIT编译器能将FFI调用优化到接近原生C的速度
开发效率高：无需编写C扩展，直接在Lua中调用C函数
内存安全：自动管理内存，减少内存泄漏风险
跨平台兼容：支持Windows、Linux、macOS等多种操作系统

1.3 环境准备

要使用LuaJIT FFI，首先需要安装LuaJIT。你可以通过以下命令克隆仓库并编译：

git clone https://gitcode.com/gh_mirrors/lu/LuaJIT
cd LuaJIT
make
make install

二、核心API详解

2.1 声明C函数和类型：ffi.cdef()

ffi.cdef()函数用于在Lua中声明C类型和外部符号。它接受一个包含C声明的字符串参数，例如：

ffi.cdef[[
    typedef struct { int x, y; } Point;
    int add(int a, int b);
    double sqrt(double x);
]]

这个函数会解析C声明并创建相应的类型信息，为后续的调用做准备。

2.2 调用C函数：ffi.C

ffi.C是默认的C库命名空间，绑定了系统默认的符号集。通过它可以直接调用标准C库函数：

local sqrt = ffi.C.sqrt
print(sqrt(25))  -- 输出: 5.0

对于需要链接外部库的情况，可以使用ffi.load()：

local libz = ffi.load("z")  -- 加载zlib库

2.3 创建C数据对象：ffi.new()

ffi.new()用于创建C数据对象，支持各种基本类型和复合类型：

-- 创建基本类型
local i = ffi.new("int", 42)

-- 创建结构体
local point = ffi.new("Point", {10, 20})

-- 创建数组
local arr = ffi.new("int[5]", {1, 2, 3, 4, 5})

2.4 类型信息查询：ffi.typeof()和ffi.sizeof()

ffi.typeof()用于获取C类型对象，ffi.sizeof()用于获取类型大小：

local int_type = ffi.typeof("int")
print(ffi.sizeof(int_type))  -- 输出: 4 (在32位系统上)

三、高级用法与最佳实践

3.1 处理回调函数

FFI允许将Lua函数转换为C回调函数，这在处理事件驱动编程时非常有用：

ffi.cdef[[
    typedef void (*Callback)(int);
    void set_callback(Callback cb);
]]

local function my_callback(value)
    print("Callback called with:", value)
end

-- 将Lua函数转换为C回调
local c_cb = ffi.cast("Callback", my_callback)
ffi.C.set_callback(c_cb)

3.2 内存管理：ffi.gc()

使用ffi.gc()可以为C数据对象设置垃圾回收器，确保资源正确释放：

local p = ffi.gc(ffi.C.malloc(1024), ffi.C.free)
-- 当p被垃圾回收时，会自动调用free(p)

3.3 字符串与C数据转换

ffi.string()和ffi.copy()函数提供了Lua字符串与C数据的高效转换：

-- 将C字符串转换为Lua字符串
local c_str = ffi.new("char[10]", "hello")
local lua_str = ffi.string(c_str)

-- 将Lua字符串复制到C缓冲区
local buf = ffi.new("char[20]")
ffi.copy(buf, "LuaJIT FFI")

3.4 性能优化技巧

预编译类型：使用ffi.typeof()预编译类型，避免重复解析
减少边界检查：在性能关键代码中使用ffi.unsafe绕过某些安全检查
利用JIT优化：保持类型一致性，帮助JIT编译器生成更优代码

四、常见问题与解决方案

4.1 处理不同平台的差异

使用ffi.abi()和ffi.os可以检测目标平台特性：

if ffi.abi("64bit") then
    print("64位系统")
else
    print("32位系统")
end

if ffi.os == "Windows" then
    -- Windows特定代码
elseif ffi.os == "Linux" then
    -- Linux特定代码
end

4.2 处理C宏和常量

由于FFI不直接支持C预处理器，对于宏定义，可以使用enum或static const代替：

ffi.cdef[[
    enum {
        MAX_SIZE = 1024,
        FLAGS = 0x01 | 0x04
    };
    static const int VERSION = 123;
]]

五、实用示例：从理论到实践

5.1 调用系统API示例

以下示例展示如何使用FFI调用系统API创建窗口（Windows平台）：

ffi.cdef[[
    typedef void* HWND;
    HWND CreateWindowA(const char*, const char*, int, int, int, int, int, void*, void*, void*, void*);
]]

local hWnd = ffi.C.CreateWindowA("STATIC", "LuaJIT FFI Window", 0x10CF0000,
                                100, 100, 400, 300, nil, nil, nil, nil)

5.2 操作C结构体数组

ffi.cdef[[
    typedef struct { float x, y, z; } Vector3;
]]

local Vector3 = ffi.typeof("Vector3")
local arr = ffi.new("Vector3[3]", {
    {1.0, 2.0, 3.0},
    {4.0, 5.0, 6.0},
    {7.0, 8.0, 9.0}
})

-- 访问数组元素
for i = 0, 2 do
    print(arr[i].x, arr[i].y, arr[i].z)
end