14.1 C API 简介

文档摘要

14.1 C API 简介 Lua C API 简介：在 C 中扩展和嵌入 Lua 的桥梁 Lua 以其轻量、快速和易于嵌入而闻名。然而，Lua 的强大之处不仅仅在于其独立的脚本能力，还在于它与 C 语言的无缝集成。Lua C API 正是连接 Lua 世界和 C 世界的桥梁，它允许开发者：扩展 Lua 的功能：使用 C 编写高性能的模块，为 Lua 脚本提供额外的功能，例如访问操作系统底层 API、高性能计算、硬件控制等。在 C 应用中嵌入 Lua：将 Lua 脚本引擎嵌入到 C 应用中，实现配置管理、脚本扩展、热更新等功能，使 C 应用更加灵活和可配置。本文将深入探讨 Lua C API 的基础概念和常用操作，并通过代码示例进行实践，帮助你快速入门 Lua C API 的世界。

14.1 C API 简介

Lua C API 简介：在 C 中扩展和嵌入 Lua 的桥梁

Lua 以其轻量、快速和易于嵌入而闻名。然而，Lua 的强大之处不仅仅在于其独立的脚本能力，还在于它与 C 语言的无缝集成。Lua C API 正是连接 Lua 世界和 C 世界的桥梁，它允许开发者：

扩展 Lua 的功能： 使用 C 编写高性能的模块，为 Lua 脚本提供额外的功能，例如访问操作系统底层 API、高性能计算、硬件控制等。
在 C 应用中嵌入 Lua： 将 Lua 脚本引擎嵌入到 C 应用中，实现配置管理、脚本扩展、热更新等功能，使 C 应用更加灵活和可配置。

本文将深入探讨 Lua C API 的基础概念和常用操作，并通过代码示例进行实践，帮助你快速入门 Lua C API 的世界。

文章目录

Lua C API 简介

1.1. Lua C API 的作用和应用场景

1.2. Lua 虚拟机和 Lua 状态

1.3. Lua 堆栈：数据交换的核心

1.4. C API 的基本原则：类型安全和错误处理

Lua C API 基础操作

2.1. 创建和销毁 Lua 状态

2.2. 加载和执行 Lua 代码


 2.2.1. 加载 Lua 代码块

 2.2.2. 执行 Lua 代码块

2.3. Lua 堆栈操作：数据推送和获取


 2.3.1. 推送数据到堆栈 (Push)

 2.3.2. 从堆栈获取数据 (Pop 和 Get)

 2.3.3. 堆栈索引和类型检查

2.4. 调用 Lua 函数


 2.4.1. 获取 Lua 函数

 2.4.2. 压入函数参数

 2.4.3. 调用 Lua 函数并获取返回值

C 函数注册到 Lua

3.1. C 函数的签名和约定

3.2. 注册 C 函数到 Lua

3.3. C 函数中访问和操作 Lua 堆栈
```
 3.3.1. 获取 C 函数参数

 3.3.2. 返回值给 Lua
```
完整示例：C 模块扩展 Lua

4.1. 编写 C 模块代码 (my_module.c)

4.2. 编译 C 模块为动态链接库

4.3. Lua 中加载和使用 C 模块 (main.lua)
错误处理和资源管理

5.1. Lua C API 的错误处理机制

5.2. 内存管理和垃圾回收

5.3. 资源释放和清理
总结与进阶方向

1. Lua C API 简介

1.1. Lua C API 的作用和应用场景

Lua C API 是一组 C 函数、结构体和宏的集合，它定义了 C 代码与 Lua 虚拟机交互的方式。通过 C API，C 代码可以：

与 Lua 虚拟机通信： 创建 Lua 虚拟机、加载和执行 Lua 代码、调用 Lua 函数、注册 C 函数供 Lua 调用等。
操作 Lua 数据： 在 C 代码和 Lua 代码之间传递数据，例如数字、字符串、表、函数等。
扩展 Lua 功能： 使用 C 编写高性能的模块，并将其注册到 Lua 环境中，从而扩展 Lua 的功能。

Lua C API 的应用场景非常广泛，包括：

游戏开发： 使用 Lua 作为游戏脚本语言，C/C++ 编写游戏引擎核心逻辑，并通过 C API 连接 Lua 脚本和游戏引擎，实现游戏逻辑的快速迭代和可扩展性。
嵌入式系统： 在资源受限的嵌入式系统中嵌入 Lua 解释器，使用 Lua 脚本进行配置管理、设备控制、自动化脚本等。
Web 应用： 在 Web 服务器中使用 Lua 脚本处理业务逻辑，C/C++ 编写高性能的 Web 服务器核心，通过 C API 连接 Lua 脚本和服务器，提高 Web 应用的性能和灵活性。
插件系统： 为 C/C++ 应用开发插件系统，使用 Lua 脚本编写插件，通过 C API 将插件集成到应用中，实现应用的扩展和定制。

1.2. Lua 虚拟机和 Lua 状态

Lua 是一个嵌入式脚本语言，它的核心是一个虚拟机 (Virtual Machine, VM)。Lua 虚拟机负责解释和执行 Lua 代码。

在使用 Lua C API 时，最重要的概念之一是 Lua 状态 (Lua State)。 Lua 状态是一个独立的 Lua 运行环境，包含了 Lua 虚拟机的所有状态信息，例如全局变量、函数定义、堆栈等。

每个 Lua 状态都是相互独立的，这意味着在一个 Lua 状态中定义的变量和函数不会影响到另一个 Lua 状态。这使得我们可以在同一个 C 应用中创建多个 Lua 状态，实现不同 Lua 环境的隔离。

C 代码通过 lua_State 指针来操作 Lua 状态。所有 Lua C API 函数都以 lua_State* L 作为第一个参数，表示要操作的 Lua 状态。

1.3. Lua 堆栈：数据交换的核心

Lua C API 使用一个 虚拟堆栈 (Virtual Stack) 来实现 C 代码和 Lua 代码之间的数据交换。这个堆栈是一个后进先出 (LIFO) 的数据结构，用于传递参数、返回值和临时数据。

当 C 代码需要调用 Lua 函数或者将数据传递给 Lua 代码时，需要将数据压入堆栈 (Push)。Lua 代码执行完毕后，返回值也会被压入堆栈。C 代码再从堆栈中弹出 (Pop) 或获取 (Get) 数据。

Lua 堆栈的关键特性：

虚拟堆栈： Lua 堆栈是虚拟的，它存在于 Lua 虚拟机内部，C 代码通过 C API 函数来操作这个堆栈，而不是直接访问内存。
类型安全： Lua C API 提供了类型检查机制，确保 C 代码和 Lua 代码之间的数据类型匹配，避免类型错误。
索引访问： 堆栈中的每个元素都有一个索引，可以使用索引来访问堆栈中的元素。索引可以是正数或负数。
- 正数索引： 从栈底到栈顶，栈底索引为 1，栈顶索引为 lua_gettop(L)。
- 负数索引： 从栈顶到栈底，栈顶索引为 -1，栈底索引为堆栈底部。

1.4. C API 的基本原则：类型安全和错误处理

Lua C API 设计时遵循了以下基本原则：

类型安全： Lua 是动态类型语言，而 C 是静态类型语言。Lua C API 提供了类型检查和转换机制，确保 C 代码和 Lua 代码之间的数据类型兼容。C API 提供了 lua_isnumber, lua_isstring, lua_toboolean, lua_tonumber, lua_tostring 等函数用于类型检查和转换。
错误处理： Lua C API 提供了完善的错误处理机制。当 Lua 代码执行出错或者 C API 调用出错时，会返回错误代码或者抛出异常。C 代码需要妥善处理错误，避免程序崩溃。Lua C API 主要使用 lua_pcall 函数来执行 Lua 代码，并捕获错误。
内存管理： Lua 虚拟机负责自动内存管理 (垃圾回收)。C 代码在使用 Lua C API 时，需要遵循 Lua 的内存管理规则，避免内存泄漏。

2. Lua C API 基础操作

2.1. 创建和销毁 Lua 状态

首先，我们需要创建一个 Lua 状态才能开始使用 Lua C API。


#include <lua.h>
#include <lualib.h>
#include <lauxlib.h>
int main() {
    // 创建 Lua 状态
    lua_State *L = luaL_newstate();
    if (L == NULL) {
        fprintf(stderr, "Failed to create Lua state\n");
        return 1;
    }
    // ... 使用 Lua C API 进行操作 ...
    // 关闭 Lua 状态
    lua_close(L);
    return 0;
}

luaL_newstate(): 创建一个新的 Lua 状态。luaL_newstate 是 lauxlib.h (Lua auxiliary library) 提供的辅助函数，它会创建一个包含标准库的 Lua 状态。
lua_close(L): 关闭并销毁指定的 Lua 状态，释放相关的资源。

2.2. 加载和执行 Lua 代码

在 Lua 状态创建之后，我们可以加载和执行 Lua 代码。Lua C API 提供了多种方式加载 Lua 代码，例如从字符串、文件等加载。

2.2.1. 加载 Lua 代码块

luaL_loadstring(L, code): 从 C 字符串 code 加载 Lua 代码块。
luaL_loadfile(L, filename): 从文件 filename 加载 Lua 代码块。

这些加载函数会将编译后的 Lua 代码块压入 Lua 堆栈的栈顶。如果加载过程中发生语法错误，这些函数会返回非零值，并将错误信息压入堆栈栈顶。

示例：从字符串加载 Lua 代码


lua_State *L = luaL_newstate();
luaL_openlibs(L); // 打开标准库
const char *lua_code = "print('Hello from Lua!')";
if (luaL_loadstring(L, lua_code) != LUA_OK) {
    fprintf(stderr, "Error loading Lua code: %s\n", lua_tostring(L, -1));
    lua_close(L);
    return 1;
}
// ... 执行 Lua 代码 ...
lua_close(L);

2.2.2. 执行 Lua 代码块

lua_pcall(L, nargs, nresults, msgh): 执行栈顶的函数 (通常是 luaL_loadstring 或 luaL_loadfile 加载的代码块)。
- L: Lua 状态。
- nargs: 传递给函数的参数个数 (对于加载的代码块，通常为 0)。
- nresults: 期望的返回值个数 (对于加载的代码块，通常为 0 或 LUA_MULTRET 表示所有返回值)。
- msgh: 错误处理函数索引 (通常为 0 表示不使用错误处理函数)。

lua_pcall 会弹出栈顶的函数，执行它，并将返回值压入堆栈。如果执行过程中发生运行时错误，lua_pcall 会捕获错误，返回非零值，并将错误信息压入堆栈栈顶。

示例：执行加载的 Lua 代码


lua_State *L = luaL_newstate();
luaL_openlibs(L);
const char *lua_code = "print('Hello from Lua!')";
if (luaL_loadstring(L, lua_code) != LUA_OK) {
    fprintf(stderr, "Error loading Lua code: %s\n", lua_tostring(L, -1));
    lua_close(L);
    return 1;
}
// 执行 Lua 代码块
if (lua_pcall(L, 0, 0, 0) != LUA_OK) {
    fprintf(stderr, "Error running Lua code: %s\n", lua_tostring(L, -1));
    lua_close(L);
    return 1;
}
lua_close(L);

2.3. Lua 堆栈操作：数据推送和获取

Lua 堆栈是 C 代码和 Lua 代码之间数据交换的关键。我们需要学习如何将数据压入堆栈 (Push) 以及如何从堆栈中获取数据 (Pop 和 Get)。

2.3.1. 推送数据到堆栈 (Push)

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

lua_pushnil(L): 压入一个 nil 值。
lua_pushboolean(L, b): 压入一个布尔值 b (1 为 true, 0 为 false)。
lua_pushnumber(L, n): 压入一个数字 n (Lua 中的数字类型默认是 double)。
lua_pushinteger(L, n): 压入一个整数 n (Lua 5.3+ 版本引入了整数类型)。
lua_pushstring(L, s): 压入一个字符串 s (C 风格字符串，需要以 null 结尾)。
lua_pushlstring(L, s, len): 压入一个长度为 len 的字符串 s (允许字符串中间包含 null 字符)。

示例：推送不同类型的数据到堆栈


lua_State *L = luaL_newstate();
lua_pushnil(L);
lua_pushboolean(L, 1);
lua_pushnumber(L, 123.45);
lua_pushinteger(L, 100);
lua_pushstring(L, "Hello Lua Stack!");
// 堆栈现在包含 5 个元素：nil, true, 123.45, 100, "Hello Lua Stack!"
lua_close(L);

2.3.2. 从堆栈获取数据 (Pop 和 Get)

Lua C API 提供了一系列 lua_to... 函数用于从堆栈中获取数据，并将其转换为 C 类型。同时，也提供了 lua_pop 函数用于弹出堆栈元素。

lua_pop(L, n): 从堆栈中弹出 n 个元素。
lua_toboolean(L, index): 将索引 index 处的元素转换为布尔值。
lua_tonumber(L, index): 将索引 index 处的元素转换为数字 (double)。
lua_tointeger(L, index): 将索引 index 处的元素转换为整数 (lua_Integer 类型，通常是 long long)。
lua_tostring(L, index): 将索引 index 处的元素转换为字符串 (C 风格字符串)。

注意： lua_to... 函数不会弹出堆栈元素，只是获取指定索引处的值。在获取数据后，通常需要使用 lua_pop 弹出已处理的元素，保持堆栈的平衡。

示例：从堆栈获取数据


lua_State *L = luaL_newstate();
lua_pushstring(L, "Lua String");
lua_pushnumber(L, 42);
// 获取栈顶字符串 (索引 -1)
const char *str = lua_tostring(L, -1);
printf("String from stack: %s\n", str);
// 获取栈顶数字 (索引 -2)
double num = lua_tonumber(L, -2);
printf("Number from stack: %f\n", num);
// 弹出两个元素
lua_pop(L, 2);
lua_close(L);

2.3.3. 堆栈索引和类型检查

在操作 Lua 堆栈时，了解堆栈索引和类型检查非常重要。

堆栈索引: 如前所述，可以使用正数索引 (从栈底开始) 或负数索引 (从栈顶开始) 访问堆栈元素。
类型检查: Lua C API 提供了 lua_type(L, index) 函数用于获取指定索引处元素的类型。lua_type 函数返回一个整数常量，例如 LUA_TNIL, LUA_TBOOLEAN, LUA_TNUMBER, LUA_TSTRING, LUA_TTABLE, LUA_TFUNCTION 等。

此外，Lua C API 还提供了一系列 lua_is... 函数，用于判断指定索引处元素是否为特定类型，例如 lua_isnil(L, index), lua_isboolean(L, index), lua_isnumber(L, index), lua_isstring(L, index) 等。

示例：堆栈索引和类型检查


lua_State *L = luaL_newstate();
lua_pushstring(L, "Hello");
lua_pushnumber(L, 10);
// 获取栈顶元素类型
int type = lua_type(L, -1);
if (type == LUA_TNUMBER) {
    printf("Top element is a number: %f\n", lua_tonumber(L, -1));
}
// 检查栈底元素是否为字符串
if (lua_isstring(L, 1)) {
    printf("Bottom element is a string: %s\n", lua_tostring(L, 1));
}
lua_pop(L, 2);
lua_close(L);

2.4. 调用 Lua 函数

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

2.4.1. 获取 Lua 函数

要调用 Lua 函数，首先需要获取函数对象。可以使用以下方法获取全局 Lua 函数：

lua_getglobal(L, name): 从全局环境中获取名为 name 的变量，并将其压入堆栈。如果 name 是一个函数，则函数对象会被压入堆栈。

2.4.2. 压入函数参数

在调用 Lua 函数之前，需要将函数的参数按照顺序压入堆栈。参数会按照压入堆栈的顺序传递给 Lua 函数。

2.4.3. 调用 Lua 函数并获取返回值

使用 lua_pcall 函数调用栈顶的函数 (即通过 lua_getglobal 获取的 Lua 函数)。调用 lua_pcall 时，需要指定参数个数和期望的返回值个数。Lua 函数的返回值会被压入堆栈。

示例：C 代码调用 Lua 函数

Lua 代码 (test.lua):


function add(a, b)
  return a + b
end

C 代码 (main.c):


#include <lua.h>
#include <lualib.h>
#include <lauxlib.h>
int main() {
    lua_State *L = luaL_newstate();
    luaL_openlibs(L);
    // 加载 Lua 代码
    if (luaL_loadfile(L, "test.lua") != LUA_OK || lua_pcall(L, 0, 0, 0) != LUA_OK) {
        fprintf(stderr, "Error loading or running Lua file: %s\n", lua_tostring(L, -1));
        lua_close(L);
        return 1;
    }
    // 获取全局函数 'add'
    lua_getglobal(L, "add");
    // 压入函数参数
    lua_pushnumber(L, 10);
    lua_pushnumber(L, 20);
    // 调用 Lua 函数 'add'，传递 2 个参数，期望 1 个返回值
    if (lua_pcall(L, 2, 1, 0) != LUA_OK) {
        fprintf(stderr, "Error calling Lua function: %s\n", lua_tostring(L, -1));
        lua_close(L);
        return 1;
    }
    // 获取返回值 (栈顶元素)
    if (lua_isnumber(L, -1)) {
        double result = lua_tonumber(L, -1);
        printf("Lua function 'add' returned: %f\n", result);
    } else {
        fprintf(stderr, "Lua function 'add' did not return a number\n");
    }
    // 弹出返回值
    lua_pop(L, 1);
    lua_close(L);
    return 0;
}

编译和运行：

确保已安装 Lua 开发库。
编译 C 代码：gcc main.c -o main -llua (可能需要根据你的 Lua 安装路径调整链接库选项 -llua)
运行 C 程序：./main

输出：


Lua function 'add' returned: 30.000000

3. C 函数注册到 Lua

Lua C API 最强大的功能之一是允许将 C 函数注册到 Lua 环境中，供 Lua 脚本调用。这使得我们可以使用 C 语言编写高性能的模块，扩展 Lua 的功能。

3.1. C 函数的签名和约定

要将 C 函数注册到 Lua，C 函数必须遵循特定的签名和约定：


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

lua_CFunction 是一个函数指针类型，表示 C 函数的签名。
C 函数必须接受一个 lua_State* L 参数，表示 Lua 状态。
C 函数必须返回一个整数值，表示 C 函数返回给 Lua 的返回值个数。返回值会被压入 Lua 堆栈，供 Lua 代码使用。

3.2. 注册 C 函数到 Lua

使用 lua_register(L, name, f) 函数将 C 函数 f 注册到 Lua 全局环境中，并命名为 name。

L: Lua 状态。
name: C 函数在 Lua 中使用的名字 (字符串)。
f: 指向要注册的 C 函数的函数指针 (lua_CFunction 类型)。

3.3. C 函数中访问和操作 Lua 堆栈

在 C 函数内部，可以通过 lua_State* L 参数访问和操作 Lua 堆栈，从而获取 Lua 传递的参数，并将返回值返回给 Lua。

3.3.1. 获取 C 函数参数

Lua 传递给 C 函数的参数会按照顺序压入 Lua 堆栈。C 函数可以使用 lua_to... 系列函数从堆栈中获取参数。通常，我们会从栈顶开始逆序获取参数 (因为栈顶是最后一个压入的参数)。

为了方便参数检查和类型转换，Lua auxiliary library (lauxlib.h) 提供了一系列 luaL_check... 函数，例如：

luaL_checknumber(L, arg): 检查索引 arg 处的参数是否为数字，如果是则返回数字值，否则抛出错误。
luaL_checkinteger(L, arg): 检查索引 arg 处的参数是否为整数，如果是则返回整数值，否则抛出错误。
luaL_checkstring(L, arg): 检查索引 arg 处的参数是否为字符串，如果是则返回字符串指针，否则抛出错误。
luaL_checklstring(L, arg, len): 检查索引 arg 处的参数是否为字符串，如果是则返回字符串指针和长度，否则抛出错误。

3.3.2. 返回值给 Lua

C 函数通过 lua_push... 系列函数将返回值压入 Lua 堆栈，然后返回一个整数值，表示压入堆栈的返回值个数。这个返回值个数会被 Lua 解释器识别，并作为 Lua 函数的返回值。