14. Lua 与 C 交互 (Lua C API) (简要了解)

Lua 与 C 交互 (Lua C API) 简要详解与实践

Lua 以其轻量、高效和易于嵌入的特性，在游戏开发、配置管理、脚本扩展等领域得到了广泛应用。而 Lua 强大的可扩展性，很大程度上得益于其与 C 语言的无缝集成能力。通过 Lua C API，C 语言可以轻松地调用 Lua 代码，反之，Lua 也可以调用 C 编写的函数和库。这种双向交互机制，使得开发者能够充分利用 Lua 的灵活性和 C 的性能，构建强大而高效的应用程序。

本文将深入浅出地介绍 Lua C API 的核心概念和常用函数，并通过丰富的代码示例，帮助读者快速掌握 Lua 与 C 交互的基本方法和技巧。

1. Lua C API 概述

Lua C API 是一组 C 函数、数据结构和宏定义，它们构成了 Lua 与 C 代码交互的桥梁。通过这些 API，C 代码可以：

• 创建和管理 Lua 虚拟机（Lua State）：每个 Lua 虚拟机都代表一个独立的 Lua 运行环境。

• 执行 Lua 代码：加载和运行 Lua 脚本或代码片段。

• 操作 Lua 堆栈：Lua C API 的核心机制，用于在 C 和 Lua 之间传递数据。

• 调用 Lua 函数：从 C 代码中调用 Lua 函数，并获取返回值。

• 注册 C 函数供 Lua 调用：将 C 函数暴露给 Lua 环境，作为 Lua 模块或库的一部分。

• 管理 Lua 中的数据类型：创建、读取和修改 Lua 中的各种数据类型，如数字、字符串、表等。

• 处理错误和异常：捕获和处理 Lua 代码执行过程中产生的错误。

2. 准备工作：环境搭建

在开始 Lua C API 编程之前，需要确保你的开发环境已经配置好 Lua 开发库。

安装 Lua 开发库 (以 Ubuntu 为例):

sudo apt-get update
sudo apt-get install lua5.3 liblua5.3-dev  # 或你使用的 Lua 版本
​

编译和链接:

在编译 C 代码时，需要链接 Lua 库。假设你的 C 源文件名为 myluaext.c，编译命令可能如下 (具体命令可能因系统和编译器而异):

gcc -o myluaext.so -shared myluaext.c -llua5.3  # 或你使用的 Lua 库名
​

• -o myluaext.so: 指定输出文件名为 myluaext.so (Linux 下的共享库，Windows 下为 .dll)。

• -shared: 生成共享库。

• myluaext.c: 你的 C 源文件。

• -llua5.3: 链接 Lua 5.3 库 (根据实际安装的 Lua 版本调整)。

3. Lua 虚拟机 (Lua State)

Lua C API 的核心是 Lua 虚拟机 (Lua State)。所有的 Lua 操作都必须在一个 Lua State 中进行。你可以将 Lua State 理解为一个独立的 Lua 运行环境。

创建 Lua State:

#include <lua.h>
#include <lauxlib.h>
#include <lualib.h>
int main() {
    lua_State *L = luaL_newstate(); // 创建一个新的 Lua State
    if (L == NULL) {
        fprintf(stderr, "luaL_newstate failed\n");
        return 1;
    }
    // ... 在这里使用 Lua C API 进行操作 ...
    lua_close(L); // 关闭 Lua State
    return 0;
}
​

• lua_State *L = luaL_newstate();: luaL_newstate() 函数创建一个新的 Lua State 并返回指向它的指针。如果创建失败，返回 NULL。

• lua_close(L);: lua_close() 函数用于关闭 Lua State，释放所有相关的资源。这是一个非常重要的步骤，必须在程序结束前调用。

包含头文件:

• lua.h: Lua 核心头文件，包含 Lua 虚拟机的基本定义。

• lauxlib.h: Lua 辅助库头文件，提供了一些便捷的辅助函数，例如 luaL_newstate 和 luaL_loadstring。

• lualib.h: Lua 标准库头文件，包含了 luaL_openlibs 函数，用于加载 Lua 的标准库。

加载 Lua 标准库:

通常，我们会在创建 Lua State 后立即加载 Lua 的标准库，以便在 Lua 环境中使用如 print、string、math 等常用的库函数。

lua_State *L = luaL_newstate();
if (L == NULL) { /* ... */ }
luaL_openlibs(L); // 加载 Lua 标准库
// ... 后续操作 ...
lua_close(L);
​

• luaL_openlibs(L);: 加载 Lua 的所有标准库，包括 base, coroutine, table, io, os, string, math, debug, package 和 utf8。

4. Lua 堆栈 (Stack)

Lua C API 的核心交互机制是 Lua 堆栈 (Stack)。Lua 堆栈是一个虚拟的栈结构，用于在 C 和 Lua 之间传递数据。可以将其想象成一块内存区域，C 代码和 Lua 代码都通过这个栈来交换数据。

堆栈操作原则:

• LIFO (后进先出): 堆栈的操作遵循后进先出原则。

• 索引: 堆栈中的每个元素都有一个索引。正索引从栈底向上计数，栈底为 1，栈顶为 lua_gettop(L)。负索引从栈顶向下计数，栈顶为 -1，栈底为 -lua_gettop(L)。

常用堆栈操作:

• 压入数据 (Push): 将数据从 C 代码压入 Lua 堆栈。

• 读取数据 (Get/To): 从 Lua 堆栈中读取数据到 C 代码。

• 弹出数据 (Pop): 从 Lua 堆栈中移除数据。

• 检查数据类型 (Is): 检查堆栈中指定位置的数据类型。

4.1 压入数据 (Push)

Lua C API 提供了一系列 lua_push* 函数，用于将不同类型的数据从 C 代码压入 Lua 堆栈。

示例代码:

lua_State *L = luaL_newstate();
luaL_openlibs(L);
// 压入一个数字
lua_pushnumber(L, 10);
// 压入一个字符串
lua_pushstring(L, "hello lua");
// 压入一个布尔值
lua_pushboolean(L, 1); // 1 代表 true, 0 代表 false
// 压入 nil 值
lua_pushnil(L);
// 此时堆栈从栈底到栈顶依次为:  数字 10, 字符串 "hello lua", 布尔值 true, nil
// ... 后续操作 ...
lua_close(L);
​

• lua_pushnumber(L, n): 将双精度浮点数 n 压入堆栈。

• lua_pushstring(L, s): 将 C 字符串 s 压入堆栈。Lua 会复制字符串，因此 C 代码可以释放 s 指向的内存。

• lua_pushboolean(L, b): 将布尔值 b 压入堆栈。b 为 1 代表 true，0 代表 false。

• lua_pushnil(L): 将 nil 值压入堆栈。

4.2 读取数据 (Get/To)

Lua C API 提供了一系列 lua_to* 函数和 lua_is* 函数，用于从 Lua 堆栈中读取数据到 C 代码。

示例代码:

lua_State *L = luaL_newstate();
luaL_openlibs(L);
lua_pushnumber(L, 123);
lua_pushstring(L, "test string");
// 检查栈顶是否为字符串
if (lua_isstring(L, -1)) {
    const char *str = lua_tostring(L, -1); // 读取栈顶字符串
    printf("String from stack: %s\n", str);
}
// 检查栈顶第二个元素是否为数字
if (lua_isnumber(L, -2)) {
    double num = lua_tonumber(L, -2); // 读取栈顶第二个数字
    printf("Number from stack: %.2f\n", num);
}
// ... 后续操作 ...
lua_close(L);
​

• lua_isstring(L, index): 检查堆栈中索引 index 位置的值是否为字符串。

• lua_isnumber(L, index): 检查堆栈中索引 index 位置的值是否为数字。

• lua_tostring(L, index): 如果索引 index 位置的值是字符串，则返回指向该字符串的 C 字符串指针。否则返回 NULL。注意: 返回的指针指向 Lua 虚拟机内部的字符串，不要尝试释放该指针指向的内存。

• lua_tonumber(L, index): 如果索引 index 位置的值可以转换为数字，则返回该数字。否则返回 0。

• lua_toboolean(L, index): 如果索引 index 位置的值可以转换为布尔值，则返回该布尔值 (1 或 0)。否则返回 0。

• lua_topointer(L, index): 返回索引 index 位置值的指针表示。对于userdata 和 table 等类型，返回的是其内存地址。

其他 lua_is* 和 lua_to* 函数:

• lua_isboolean(L, index)

• lua_istable(L, index)

• lua_isfunction(L, index)

• lua_isnil(L, index)

• lua_isuserdata(L, index)

• lua_tolstring(L, index, len): 类似 lua_tostring，但可以获取字符串的长度。

• lua_touserdata(L, index): 获取 userdata 指针。

• lua_totable(L, index): 获取 table 指针 (不常用，通常使用 lua_gettable 等函数操作 table)。

4.3 弹出数据 (Pop)

lua_pop(L, n) 函数用于从堆栈中弹出 n 个元素。

示例代码:

lua_State *L = luaL_newstate();
luaL_openlibs(L);
lua_pushnumber(L, 1);
lua_pushstring(L, "two");
lua_pushboolean(L, 1);
printf("Stack top before pop: %d\n", lua_gettop(L)); // 输出 3
lua_pop(L, 2); // 弹出栈顶的 2 个元素 (boolean 和 string)
printf("Stack top after pop: %d\n", lua_gettop(L)); // 输出 1 (只剩下数字 1)
// ... 后续操作 ...
lua_close(L);
​

• lua_pop(L, n): 从堆栈顶部弹出 n 个元素。相当于执行 lua_settop(L, -n-1)。

4.4 获取堆栈顶部索引 (lua_gettop) 和 设置堆栈顶部索引 (lua_settop)

• lua_gettop(L): 返回堆栈顶部的索引。也表示堆栈中元素的数量。

• lua_settop(L, index): 设置堆栈的顶部索引。

  • 如果 index 大于当前堆栈顶部，则会在栈顶压入 (index - 原栈顶) 个 nil 值。

  • 如果 index 小于当前堆栈顶部，则会截断堆栈，移除栈顶以上的元素。

  • lua_settop(L, 0) 可以清空堆栈。

5. 执行 Lua 代码

Lua C API 提供了函数用于加载和执行 Lua 代码。

5.1 加载和运行 Lua 代码字符串 (luaL_loadstring, lua_pcall)

luaL_loadstring(L, code) 函数用于加载 Lua 代码字符串，将其编译成 Lua 字节码，并压入堆栈。 lua_pcall(L, nargs, nresults, errfunc) 函数用于从堆栈中弹出函数并执行。

示例代码:

lua_State *L = luaL_newstate();
luaL_openlibs(L);
const char *lua_code = "print('Hello from Lua!')";
int status = luaL_loadstring(L, lua_code); // 加载 Lua 代码字符串
if (status != LUA_OK) {
    fprintf(stderr, "luaL_loadstring failed: %s\n", lua_tostring(L, -1));
    lua_pop(L, 1); // 弹出错误消息
    lua_close(L);
    return 1;
}
status = lua_pcall(L, 0, 0, 0); // 执行加载的代码 (0 个参数, 0 个返回值, 0 错误处理函数)
if (status != LUA_OK) {
    fprintf(stderr, "lua_pcall failed: %s\n", lua_tostring(L, -1));
    lua_pop(L, 1); // 弹出错误消息
    lua_close(L);
    return 1;
}
lua_close(L);
return 0;
​

• luaL_loadstring(L, code): 加载 Lua 代码字符串 code。如果加载成功，将编译后的 chunk (函数) 压入堆栈，并返回 LUA_OK。如果加载失败 (例如语法错误)，将错误消息压入堆栈，并返回错误代码 (例如 LUA_ERRSYNTAX)。

• lua_pcall(L, nargs, nresults, errfunc): 调用栈顶的函数。

  • nargs: 传递给函数的参数个数。参数应该在函数之前压入堆栈。

  • nresults: 期望的返回值个数。LUA_MULTRET 表示返回所有返回值。

  • errfunc: 错误处理函数在堆栈中的索引。如果为 0，则使用标准错误处理函数。

  • 如果调用成功，函数返回值会被压入堆栈。

  • 如果调用失败 (例如运行时错误)，错误消息会被压入堆栈，并返回错误代码 (例如 LUA_ERRRUN)。

错误处理:

在 luaL_loadstring 和 lua_pcall 之后，都需要检查返回值 status。如果 status 不为 LUA_OK，则表示发生了错误。错误消息通常会被压入堆栈栈顶，可以使用 lua_tostring(L, -1) 获取错误消息，并使用 lua_pop(L, 1) 弹出错误消息。

5.2 加载和运行 Lua 代码文件 (luaL_loadfile, lua_pcall)

luaL_loadfile(L, filename) 函数用于加载 Lua 代码文件，将其编译成 Lua 字节码，并压入堆栈。

示例代码:

假设有一个 Lua 文件 hello.lua，内容如下：

print("Hello from Lua file!")
​

C 代码:

lua_State *L = luaL_newstate();
luaL_openlibs(L);
int status = luaL_loadfile(L, "hello.lua"); // 加载 Lua 代码文件
if (status != LUA_OK) {
    fprintf(stderr, "luaL_loadfile failed: %s\n", lua_tostring(L, -1));
    lua_pop(L, 1);
    lua_close(L);
    return 1;
}
status = lua_pcall(L, 0, 0, 0); // 执行加载的代码
if (status != LUA_OK) {
    fprintf(stderr, "lua_pcall failed: %s\n", lua_tostring(L, -1));
    lua_pop(L, 1);
    lua_close(L);
    return 1;
}
lua_close(L);
return 0;
​

• luaL_loadfile(L, filename): 加载 Lua 代码文件 filename。行为和返回值与 luaL_loadstring 类似。

6. 调用 Lua 函数

C 代码可以通过 Lua C API 调用 Lua 中定义的函数。

步骤:

1. 获取 Lua 函数: 通常通过函数名从全局环境或 table 中获取 Lua 函数并压入堆栈。

2. 压入参数: 将需要传递给 Lua 函数的参数依次压入堆栈。

3. 调用函数: 使用 lua_pcall 调用栈顶的函数。

4. 获取返回值: 从堆栈中读取 Lua 函数的返回值。

5. 清理堆栈: 移除堆栈上的函数和参数，保留返回值 (或根据需要清理返回值)。

示例代码:

假设 Lua 代码 call_lua_func.lua 中定义了一个函数 add：

-- call_lua_func.lua
function add(a, b)
  return a + b
end
​

C 代码调用 add 函数:

lua_State *L = luaL_newstate();
luaL_openlibs(L);
if (luaL_loadfile(L, "call_lua_func.lua") != LUA_OK || lua_pcall(L, 0, 0, 0) != LUA_OK) { // 加载并执行 Lua 文件
    fprintf(stderr, "Error loading or running Lua file: %s\n", lua_tostring(L, -1));
    lua_close(L);
    return 1;
}
// 1. 获取 Lua 函数 'add' (从全局环境中获取)
lua_getglobal(L, "add"); // 将全局变量 'add' 的值 (函数) 压入堆栈
// 2. 压入参数
lua_pushnumber(L, 5);
lua_pushnumber(L, 3);
// 3. 调用函数 (2 个参数, 1 个返回值, 0 错误处理函数)
if (lua_pcall(L, 2, 1, 0) != LUA_OK) {
    fprintf(stderr, "Error calling function 'add': %s\n", lua_tostring(L, -1));
    lua_pop(L, 1); // 弹出错误消息
    lua_close(L);
    return 1;
}
// 4. 获取返回值 (栈顶是返回值)
if (lua_isnumber(L, -1)) {
    double result = lua_tonumber(L, -1);
    printf("Result of add(5, 3) is: %.2f\n", result);
} else {
    fprintf(stderr, "Function 'add' did not return a number\n");
}
// 5. 清理堆栈 (弹出返回值)
lua_pop(L, 1);
lua_close(L);
return 0;
​

• lua_getglobal(L, name): 从全局环境中获取名为 name 的全局变量的值，并压入堆栈。

7. 注册 C 函数供 Lua 调用

Lua C API 允许将 C 函数注册到 Lua 环境中，供 Lua 代码调用。这使得我们可以用 C 编写高性能的模块或扩展 Lua 的功能。

步骤:

1. 编写 C 函数: C 函数需要符合 lua_CFunction 类型的签名。

2. 注册 C 函数: 使用 lua_pushcfunction 将 C 函数压入堆栈，然后使用 lua_setglobal 或 lua_settable 将其注册为全局函数或 table 的方法。

lua_CFunction 类型:

typedef int (*lua_CFunction) (lua_State *L);
​

• C 函数必须接受一个 lua_State *L 参数，并返回一个整数，表示返回给 Lua 的返回值数量。

• C 函数通过操作 Lua 堆栈来获取参数和返回结果。

示例代码:

C 代码 mylualib.c 定义一个 C 函数 l_add 并将其注册为 Lua 全局函数 c_add。

#include <lua.h>
#include <lauxlib.h>
#include <lualib.h>
// C 函数: 实现加法功能
static int l_add(lua_State *L) {
    // 1. 检查参数数量 (可选)
    if (lua_gettop(L) != 2) {
        return luaL_error(L, "Usage: c_add(num1, num2)");
    }
    // 2. 获取参数 (从堆栈中读取)
    double num1 = luaL_checknumber(L, 1); // 获取第一个参数，并检查是否为数字
    double num2 = luaL_checknumber(L, 2); // 获取第二个参数，并检查是否为数字
    // 3. 执行计算
    double sum = num1 + num2;
    // 4. 返回结果 (将结果压入堆栈)
    lua_pushnumber(L, sum);
    // 5. 返回值数量 (这里返回 1 个值)
    return 1;
}
// 注册 C 函数的函数 (必须导出)
int luaopen_mylualib(lua_State *L) {
    // 将 C 函数 'l_add' 注册为 Lua 全局函数 'c_add'
    lua_pushcfunction(L, l_add);
    lua_setglobal(L, "c_add");
    return 0; // 返回值数量，表示模块初始化成功 (通常返回 0)
}
​

• luaL_checknumber(L, index): 检查堆栈中索引 index 位置的值是否为数字。如果是，则返回该数字，否则抛出一个 Lua 错误。

• luaL_error(L, format, ...): 创建一个错误消息并抛出一个 Lua 错误。

• lua_pushcfunction(L, f): 将 C 函数 f 压入堆栈。

• lua_setglobal(L, name): 从堆栈中弹出一个值，并将其设置为全局变量 name 的值。

编译 C 模块:

gcc -o mylualib.so -shared mylualib.c -llua5.3
​

Lua 代码使用 C 模块:

-- Lua 代码 use_c_lib.lua
local mylib = require("mylualib") -- 加载 C 模块 (mylualib.so 或 mylualib.dll)
print("Calling C function c_add(10, 20):", mylib.c_add(10, 20))
​

运行 Lua 代码:

lua use_c_lib.lua
​

luaL_newlib 和 luaL_setfuncs (更推荐的方式):

可以使用 luaL_newlib 和 luaL_setfuncs 函数更方便地注册一组 C 函数作为一个 Lua 模块。

// ... (l_add 函数定义同上) ...
static const luaL_Reg mylib_funcs[] = {
    {"add", l_add},  // {Lua 函数名, C 函数指针}
    {NULL, NULL}     // 哨兵，表示函数列表结束
};
int luaopen_mylualib(lua_State *L) {
    luaL_newlib(L, mylib_funcs); // 创建一个新的 table 并注册函数
    return 1; // 返回值数量，表示返回模块 table
}
​

• luaL_Reg: 一个结构体数组，用于描述要注册的 C 函数列表。每个元素包含 Lua 函数名和对应的 C 函数指针。最后一个元素必须是 {NULL, NULL}。

• luaL_newlib(L, funcs): 创建一个新的 table，并将 funcs 数组中定义的 C 函数注册到这个 table 中。最后将这个 table 压入堆栈。

• return 1;: luaopen_mylualib 函数返回 1，表示将模块 table 作为返回值返回给 Lua 的 require 函数。

Lua 代码使用模块 (使用 luaL_newlib 注册的模块):

-- Lua 代码 use_c_lib.lua
local mylib = require("mylualib") -- 加载 C 模块 (mylualib.so 或 mylualib.dll)
print("Calling C function mylib.add(10, 20):", mylib.add(10, 20)) -- 注意这里使用 mylib.add
​

8. Userdata

Userdata 是 Lua 中一种特殊的数据类型，允许 C 代码在 Lua 中存储和操作 C 数据结构。Userdata 本身是一个指向 C 内存块的指针。Lua 虚拟机负责 userdata 的内存管理，当 userdata 不再被 Lua 引用时，Lua 的垃圾回收器会自动回收 userdata 占用的内存。

两种 Userdata:

• light userdata: 简单的 C 指针，没有元表，Lua 不负责内存管理。

• full userdata: 一块由 Lua 管理的内存块，可以关联元表，支持垃圾回收。

创建 Full Userdata:

void *lua_newuserdata(lua_State *L, size_t size);
​