Question

FFI 库，是 LuaJIT 中最重要的一个扩展库。它允许从纯 Lua 代码调用外部 C 函数，使用 C 数据结构。有了它，就不用再像 Lua 标准 math 库一样，编写 Lua 扩展库。把开发者从开发 Lua 扩展 C 库（语言/功能绑定库）的繁重工作中释放出来。学习完本小节对开发纯 ffi 的库是有帮助的，像 lru-resty-lrucache 中的 pureffi.lua，这个纯 ffi 库非常高效地完成了 lru 缓存策略。

简单解释一下 Lua 扩展 C 库，对于那些能够被 Lua 调用的 C 函数来说，它的接口必须遵循 Lua 要求的形式，就是 typedef int (*lua_CFunction)(lua_State* L)，这个函数包含的参数是 lua_State 类型的指针 L 。可以通过这个指针进一步获取通过 Lua 代码传入的参数。这个函数的返回值类型是一个整型，表示返回值的数量。需要注意的是，用 C 编写的函数无法把返回值返回给 Lua 代码，而是通过虚拟栈来传递 Lua 和 C 之间的调用参数和返回值。不仅在编程上开发效率变低，而且性能上比不上 FFI 库调用 C 函数。

FFI 库最大限度的省去了使用 C 手工编写繁重的 Lua/C 绑定的需要。不需要学习一门独立/额外的绑定语言——它解析普通 C 声明。这样可以从 C 头文件或参考手册中，直接剪切，粘贴。它的任务就是绑定很大的库，但不需要捣鼓脆弱的绑定生成器。

FFI 紧紧的整合进了 LuaJIT（几乎不可能作为一个独立的模块）。JIT 编译器在 C 数据结构上所产生的代码，等同于一个 C 编译器应该生产的代码。在 JIT 编译过的代码中，调用 C 函数，可以被内连处理，不同于基于 Lua/C API 函数调用。

ffi 库 词汇

noun	Explanation
cdecl	A definition of an abstract C type(actually, is a lua string)
ctype	C type object
cdata	C data object
ct	C type format, is a template object, may be cdecl, cdata, ctype
cb	callback object
VLA	An array of variable length
VLS	A structure of variable length

ffi.* API

功能： Lua ffi 库的 API，与 LuaJIT 不可分割。

毫无疑问，在 lua 文件中使用 ffi 库的时候，必须要有下面的一行。

local ffi = require "ffi"

ffi.cdef

语法： ffi.cdef(def)

功能： 声明 C 函数或者 C 的数据结构，数据结构可以是结构体、枚举或者是联合体，函数可以是 C 标准函数，或者第三方库函数，也可以是自定义的函数，注意这里只是函数的声明，并不是函数的定义。声明的函数应该要和原来的函数保持一致。

ffi.cdef[[
typedef struct foo { int a, b; } foo_t;  /* Declare a struct and typedef.   */
int printf(const char *fmt, ...);        /* Declare a typical printf function. */
]]

注意： 所有使用的库函数都要对其进行声明，这和我们写 C 语言时候引入 .h 头文件是一样的。

顺带一提的是，并不是所有的 C 标准函数都能满足我们的需求，那么如何使用 第三方库函数 或 自定义的函数 呢，这会稍微麻烦一点，不用担心，你可以很快学会。: ) 首先创建一个 myffi.c，其内容是：

int add(int x, int y)
{
  return x + y;
}

接下来在 Linux 下生成动态链接库：

gcc -g -o libmyffi.so -fpic -shared myffi.c

为了方便我们测试，我们在 LD_LIBRARY_PATH 这个环境变量中加入了刚刚库所在的路径，因为编译器在查找动态库所在的路径的时候其中一个环节就是在 LD_LIBRARY_PATH 这个环境变量中的所有路径进行查找。命令如下所示。

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:your_lib_path

在 Lua 代码中要增加如下的行：

ffi.load(name [,global])

ffi.load 会通过给定的 name 加载动态库，返回一个绑定到这个库符号的新的 C 库命名空间，在 POSIX 系统中，如果 global 被设置为 ture，这个库符号被加载到一个全局命名空间。另外这个 name 可以是一个动态库的路径，那么会根据路径来查找，否则的话会在默认的搜索路径中去找动态库。在 POSIX 系统中，如果在 name 这个字段中没有写上点符号 .，那么 .so 将会被自动添加进去，例如 ffi.load("z") 会在默认的共享库搜寻路径中去查找 libz.so，在 windows 系统，如果没有包含点号，那么 .dll 会被自动加上。

下面看一个完整例子：

local ffi = require "ffi"
local myffi = ffi.load('myffi')

ffi.cdef[[
int add(int x, int y);   /* don't forget to declare */
]]

local res = myffi.add(1, 2)
print(res)  -- output: 3   Note: please use luajit to run this script.

除此之外，还能使用 ffi.C (调用 ffi.cdef 中声明的系统函数) 来直接调用 add 函数，记得要在 ffi.load 的时候加上参数 true，例如 ffi.load('myffi', true)。

完整的代码如下所示：

local ffi = require "ffi"
ffi.load('myffi',true)

ffi.cdef[[
int add(int x, int y);   /* don't forget to declare */
]]

local res = ffi.C.add(1, 2)
print(res)  -- output: 3   Note: please use luajit to run this script.

ffi.typeof

语法： ctype = ffi.typeof(ct)

功能： 创建一个 ctype 对象，会解析一个抽象的 C 类型定义。

local uintptr_t = ffi.typeof("uintptr_t")
local c_str_t = ffi.typeof("const char*")
local int_t = ffi.typeof("int")
local int_array_t = ffi.typeof("int[?]")

ffi.new

语法： cdata = ffi.new(ct [,nelem] [,init...])

功能： 开辟空间，第一个参数为 ctype 对象，ctype 对象最好通过 ctype = ffi.typeof(ct) 构建。

顺便一提，可能很多人会有疑问，到底 ffi.new 和 ffi.C.malloc 有什么区别呢？

如果使用 ffi.new 分配的 cdata 对象指向的内存块是由垃圾回收器 LuaJIT GC 自动管理的，所以不需要用户去释放内存。

如果使用 ffi.C.malloc 分配的空间便不再使用 LuaJIT 自己的分配器了，所以不是由 LuaJIT GC 来管理的，但是，要注意的是 ffi.C.malloc 返回的指针本身所对应的 cdata 对象还是由 LuaJIT GC 来管理的，也就是这个指针的 cdata 对象指向的是用 ffi.C.malloc 分配的内存空间。这个时候，你应该通过 ffi.gc() 函数在这个 C 指针的 cdata 对象上面注册自己的析构函数，这个析构函数里面你可以再调用 ffi.C.free，这样的话当 C 指针所对应的 cdata 对象被 Luajit GC 管理器垃圾回收时候，也会自动调用你注册的那个析构函数来执行 C 级别的内存释放。

请尽可能使用最新版本的 Luajit，x86_64 上由 LuaJIT GC 管理的内存已经由 1G->2G，虽然管理的内存变大了，但是如果要使用很大的内存，还是用 ffi.C.malloc 来分配会比较好，避免耗尽了 LuaJIT GC 管理内存的上限，不过还是建议不要一下子分配很大的内存。

local int_array_t = ffi.typeof("int[?]")
local bucket_v = ffi.new(int_array_t, bucket_sz)

local queue_arr_type = ffi.typeof("lrucache_pureffi_queue_t[?]")
local q = ffi.new(queue_arr_type, size + 1)

ffi.fill

语法： ffi.fill(dst, len [,c])

功能： 填充数据，此函数和 memset(dst, c, len) 类似，注意参数的顺序。

ffi.fill(self.bucket_v, ffi_sizeof(int_t, bucket_sz), 0)
ffi.fill(q, ffi_sizeof(queue_type, size + 1), 0)

ffi.cast

语法： cdata = ffi.cast(ct, init)

功能： 创建一个 scalar cdata 对象。

local c_str_t = ffi.typeof("const char*")
local c_str = ffi.cast(c_str_t, str)       -- 转换为指针地址

local uintptr_t = ffi.typeof("uintptr_t")
tonumber(ffi.cast(uintptr_t, c_str))       -- 转换为数字

cdata 对象的垃圾回收

所有由显式的 ffi.new(), ffi.cast() etc. 或者隐式的 accessors 所创建的 cdata 对象都是能被垃圾回收的，当他们被使用的时候，你需要确保有在 Lua stack，upvalue，或者 Lua table 上保留有对 cdata 对象的有效引用，一旦最后一个 cdata 对象的有效引用失效了，那么垃圾回收器将自动释放内存（在下一个 GC 周期结束时候）。另外如果你要分配一个 cdata 数组给一个指针的话，你必须保持这个持有这个数据的 cdata 对象活跃，下面给出一个官方的示例：

ffi.cdef[[
typedef struct { int *a; } foo_t;
]]

local s = ffi.new("foo_t", ffi.new("int[10]")) -- WRONG!

local a = ffi.new("int[10]") -- OK
local s = ffi.new("foo_t", a)
-- Now do something with 's', but keep 'a' alive until you're done.

相信看完上面的 API 你已经很累了，再坚持一下吧！休息几分钟后，让我们来看看下面对官方文档中的示例做剖析，希望能再加深你对 ffi 的理解。

调用 C 函数

真的很用容易去调用一个外部 C 库函数，示例代码：

local ffi = require("ffi")
ffi.cdef[[
int printf(const char *fmt, ...);
]]
ffi.C.printf("Hello %s!", "world")

以上操作步骤，如下：

1. 加载 FFI 库。
2. 为函数增加一个函数声明。这个包含在 中括号 对之间的部分，是标准 C 语法。
3. 调用命名的 C 函数——非常简单。

事实上，背后的实现远非如此简单：③ 使用标准 C 库的命名空间 ffi.C。通过符号名 printf 索引这个命名空间，自动绑定标准 C 库。索引结果是一个特殊类型的对象，当被调用时，执行 printf 函数。传递给这个函数的参数，从 Lua 对象自动转换为相应的 C 类型。

再来一个源自官方的示例代码：

local ffi = require("ffi")
ffi.cdef[[
unsigned long compressBound(unsigned long sourceLen);
int compress2(uint8_t *dest, unsigned long *destLen,
        const uint8_t *source, unsigned long sourceLen, int level);
int uncompress(uint8_t *dest, unsigned long *destLen,
         const uint8_t *source, unsigned long sourceLen);
]]
local zlib = ffi.load(ffi.os == "Windows" and "zlib1" or "z")

local function compress(txt)
  local n = zlib.compressBound(#txt)
  local buf = ffi.new("uint8_t[?]", n)
  local buflen = ffi.new("unsigned long[1]", n)
  local res = zlib.compress2(buf, buflen, txt, #txt, 9)
  assert(res == 0)
  return ffi.string(buf, buflen[0])
end

local function uncompress(comp, n)
  local buf = ffi.new("uint8_t[?]", n)
  local buflen = ffi.new("unsigned long[1]", n)
  local res = zlib.uncompress(buf, buflen, comp, #comp)
  assert(res == 0)
  return ffi.string(buf, buflen[0])
end

-- Simple test code.
local txt = string.rep("abcd", 1000)
print("Uncompressed size: ", #txt)
local c = compress(txt)
print("Compressed size: ", #c)
local txt2 = uncompress(c, #txt)
assert(txt2 == txt)

解释一下这段代码。我们首先使用 ffi.cdef 声明了一些被 zlib 库提供的 C 函数。然后加载 zlib 共享库，在 Windows 系统上，则需要我们手动从网上下载 zlib1.dll 文件，而在 POSIX 系统上 libz 库一般都会被预安装。因为 ffi.load 函数会自动填补前缀和后缀，所以我们简单地使用 z 这个字母就可以加载了。我们检查 ffi.os，以确保我们传递给 ffi.load 函数正确的名字。

一开始，压缩缓冲区的最大值被传递给 compressBound 函数，下一行代码分配了一个要压缩字符串长度的字节缓冲区。[?] 意味着他是一个变长数组。它的实际长度由 ffi.new 函数的第二个参数指定。

我们仔细审视一下 compress2 函数的声明就会发现，目标长度是用指针传递的！这是因为我们要传递进去缓冲区的最大值，并且得到缓冲区实际被使用的大小。

在 C 语言中，我们可以传递变量地址。但因为在 Lua 中并没有地址相关的操作符，所以我们使用只有一个元素的数组来代替。我们先用最大缓冲区大小初始化这唯一一个元素，接下来就是很直观地调用 zlib.compress2 函数了。使用 ffi.string 函数得到一个存储着压缩数据的 Lua 字符串，这个函数需要一个指向数据起始区的指针和实际长度。实际长度将会在 buflen 这个数组中返回。因为压缩数据并不包括原始字符串的长度，所以我们要显式地传递进去。

使用 C 数据结构

cdata 类型用来将任意 C 数据保存在 Lua 变量中。这个类型相当于一块原生的内存，除了赋值和相同性判断，Lua 没有为之预定义任何操作。然而，通过使用 metatable（元表），程序员可以为 cdata 自定义一组操作。cdata 不能在 Lua 中创建出来，也不能在 Lua 中修改。这样的操作只能通过 C API。这一点保证了宿主程序完全掌管其中的数据。

我们将 C 语言类型与 metamethod（元方法）关联起来，这个操作只用做一次。ffi.metatype 会返回一个该类型的构造函数。原始 C 类型也可以被用来创建数组，元方法会被自动地应用到每个元素。

尤其需要指出的是，metatable 与 C 类型的关联是永久的，而且不允许被修改，__index 元方法也是。

下面是一个使用 C 数据结构的实例

local ffi = require("ffi")
ffi.cdef[[
typedef struct { double x, y; } point_t;
]]

local point
local mt = {
  __add = function(a, b) return point(a.x+b.x, a.y+b.y) end,
  __len = function(a) return math.sqrt(a.x*a.x + a.y*a.y) end,
  __index = {
    area = function(a) return a.x*a.x + a.y*a.y end,
  },
}
point = ffi.metatype("point_t", mt)

local a = point(3, 4)
print(a.x, a.y)  --> 3  4
print(#a)        --> 5
print(a:area())  --> 25
local b = a + point(0.5, 8)
print(#b)        --> 12.5

附表：Lua 与 C 语言语法对应关系

Idiom	C code	Lua code
Pointer dereference	x = *p	x = p[0]
int *p	*p = y	p[0] = y
Pointer indexing	x = p[i]	x = p[i]
int i, *p	p[i+1] = y	p[i+1] = y
Array indexing	x = a[i]	x = a[i]
int i, a[]	a[i+1] = y	a[i+1] = y
struct/union dereference	x = s.field	x = s.field
struct foo s	s.field = y	s.field = y
struct/union pointer deref	x = sp->field	x = sp.field
struct foo *sp	sp->field = y	s.field = y
int i, *p	y = p - i	y = p - i
Pointer dereference	x = p1 - p2	x = p1 - p2
Array element pointer	x = &a[i]	x = a + i

小心内存泄漏

所谓“能力越大，责任越大”，FFI 库在允许我们调用 C 函数的同时，也把内存管理的重担压到我们的肩上。 还好 FFI 库提供了很好用的 ffi.gc 方法。该方法允许给 cdata 对象注册在 GC 时调用的回调，它能让你在 Lua 领域里完成 C 手工释放资源的事。

C++ 提倡用一种叫 RAII 的方式管理你的资源。简单地说，就是创建对象时获取，销毁对象时释放。我们可以在 LuaJIT 的 FFI 里借鉴同样的做法，在调用 resource = ffi.C.xx_create 等申请资源的函数之后，立即补上一行 ffi.gc(resource, ...) 来注册释放资源的函数。尽量避免尝试手动释放资源！即使不考虑 error 对执行路径的影响，在每个出口都补上一模一样的逻辑会够你受的（用 goto 也差不多，只是稍稍好一点）。

有些时候，ffi.C.xx_create 返回的不是具体的 cdata，而是整型的 handle。这会儿需要用 ffi.metatype 把 ffi.gc 包装一下：

local resource_type = ffi.metatype("struct {int handle;}", {
    __gc = free_resource
})

local function free_resource(handle)
    ...
end

resource = ffi.new(resource_type)
resource.handle = ffi.C.xx_create()

如果你没能把申请资源和释放资源的步骤放一起，那么内存泄露多半会在前方等你。写代码的时候切记这一点。