Lua 中使用 C 语言的用户自定义类型——userdata

1. 引言

Lua 是一门轻量、可嵌入的脚本语言，其核心能力之一就是与 C 语言进行无缝交互。在 Lua 与 C 的交互中，userdata 是一种非常重要的数据类型，它允许我们在 Lua 中安全地持有 C 语言定义的对象指针。本文将深入讲解 userdata 的概念、分类、创建方法以及在实际项目中的使用技巧。

2. 什么是 userdata

userdata 是 Lua 中一种特殊的类型，用于表示 C 语言中任意类型的数据。它本质上是一块内存区域，Lua 本身不关心这块内存的具体内容，而是将其视为一个不透明的指针来管理。

userdata 分为两种：

完整 userdata（full userdata）：由 Lua 分配和管理内存，可以包含任意大小的数据块。
轻量 userdata（light userdata）：仅包装一个 C 指针，不参与 Lua 的内存管理。

3. 完整 userdata 的创建与使用

3.1 创建完整 userdata

在 C 语言中，我们使用 lua_newuserdata 函数来创建完整 userdata：

c 复制代码

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

该函数会在 Lua 栈上压入一个新的 userdata，并返回指向其内存块的指针。示例代码如下：

c 复制代码

typedef struct {
    int x;
    int y;
} Point;

static int point_new(lua_State *L) {
    Point *p = (Point *)lua_newuserdata(L, sizeof(Point));
    p->x = luaL_checkinteger(L, 1);
    p->y = luaL_checkinteger(L, 2);
    return 1;  // 将 userdata 返回给 Lua
}

3.2 在 Lua 中使用

lua 复制代码

local p = point_new(10, 20)
print(type(p))  -- 输出: userdata

4. 轻量 userdata 的使用

轻量 userdata 通过 lua_pushlightuserdata 创建，它只是一个指针的包装，不占用额外内存：

c 复制代码

static int push_pointer(lua_State *L) {
    void *ptr = malloc(100);
    lua_pushlightuserdata(L, ptr);
    return 1;
}

轻量 userdata 常用于：

表示 C 语言中的全局对象或单例。
作为 Lua 表中键的唯一标识。
传递不拥有所有权的指针。

5. 为 userdata 设置元表

为了让 userdata 在 Lua 中表现得像普通对象，我们通常会为其设置元表，实现面向对象的调用方式：

c 复制代码

static int point_new(lua_State *L) {
    Point *p = (Point *)lua_newuserdata(L, sizeof(Point));
    p->x = luaL_checkinteger(L, 1);
    p->y = luaL_checkinteger(L, 2);

    // 设置元表
    luaL_getmetatable(L, "Point");
    lua_setmetatable(L, -2);

    return 1;
}

static int point_get_x(lua_State *L) {
    Point *p = (Point *)luaL_checkudata(L, 1, "Point");
    lua_pushinteger(L, p->x);
    return 1;
}

// 注册元表
luaL_newmetatable(L, "Point");
lua_pushcfunction(L, point_get_x);
lua_setfield(L, -2, "get_x");
lua_pop(L, 1);

在 Lua 中就可以这样使用：

lua 复制代码

local p = point_new(10, 20)
print(p:get_x())  -- 输出: 10

6. userdata 的内存管理与垃圾回收

完整 userdata 由 Lua 的垃圾回收器自动管理。当 userdata 不再被引用时，Lua 会调用其元表中的 __gc 元方法进行清理：

c 复制代码

static int point_gc(lua_State *L) {
    Point *p = (Point *)luaL_checkudata(L, 1, "Point");
    // 释放内部资源
    free(p->data);
    return 0;
}

// 注册时设置 __gc
lua_pushcfunction(L, point_gc);
lua_setfield(L, -2, "__gc");

7. 类型安全检查

使用 luaL_checkudata 可以确保传入的 userdata 具有正确的元表，避免类型错误：

c 复制代码

static int point_get_x(lua_State *L) {
    Point *p = (Point *)luaL_checkudata(L, 1, "Point");
    // 如果类型不匹配，Lua 会抛出错误
    lua_pushinteger(L, p->x);
    return 1;
}

8. 完整示例：C 语言实现一个 Vector 类型

下面是一个完整的示例，展示如何在 C 语言中实现一个简单的 Vector 类型：

c 复制代码

#include <lua.h>
#include <lauxlib.h>
#include <stdlib.h>

typedef struct {
    double x, y;
} Vector;

static int vector_new(lua_State *L) {
    Vector *v = (Vector *)lua_newuserdata(L, sizeof(Vector));
    v->x = luaL_checknumber(L, 1);
    v->y = luaL_checknumber(L, 2);

    luaL_getmetatable(L, "Vector");
    lua_setmetatable(L, -2);
    return 1;
}

static int vector_add(lua_State *L) {
    Vector *a = (Vector *)luaL_checkudata(L, 1, "Vector");
    Vector *b = (Vector *)luaL_checkudata(L, 2, "Vector");
    Vector *result = (Vector *)lua_newuserdata(L, sizeof(Vector));
    result->x = a->x + b->x;
    result->y = a->y + b->y;

    luaL_getmetatable(L, "Vector");
    lua_setmetatable(L, -2);
    return 1;
}

static int vector_tostring(lua_State *L) {
    Vector *v = (Vector *)luaL_checkudata(L, 1, "Vector");
    lua_pushfstring(L, "Vector(%f, %f)", v->x, v->y);
    return 1;
}

int luaopen_vector(lua_State *L) {
    luaL_newmetatable(L, "Vector");
    lua_pushcfunction(L, vector_add);
    lua_setfield(L, -2, "__add");
    lua_pushcfunction(L, vector_tostring);
    lua_setfield(L, -2, "__tostring");
    lua_pop(L, 1);

    lua_newtable(L);
    lua_pushcfunction(L, vector_new);
    lua_setfield(L, -2, "new");
    return 1;
}

在 Lua 中使用：

lua 复制代码

local vector = require("vector")

local v1 = vector.new(1, 2)
local v2 = vector.new(3, 4)
local v3 = v1 + v2

print(v3)  -- 输出: Vector(4.000000, 6.000000)

9. 总结

userdata 是 Lua 与 C 语言交互的核心机制，它让 Lua 能够安全地操作 C 语言中的复杂数据类型。通过合理使用完整 userdata、轻量 userdata 以及元表机制，我们可以构建出高效、类型安全的 Lua 扩展库。在实际开发中，务必注意内存管理和类型检查，避免内存泄漏和类型错误。