fuchencong

The way I am

0%

《lua 程序设计》读书笔记（15）：C 语言中的用户自定义类型 & 管理资源

发表于 分类于

之前介绍过了如何通过 C 语言来编写新函数来扩展 Lua，这篇文章将介绍如何用 C 来编写新的类型来扩展 Lua。同时还会介绍除内存以外的其他资源。

用户数据

如下实现了一个布尔数组，将每个布尔值存储在一个比特中，所以相比于 Lua 的表实现，其内存使用量要小得多。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
#include <limits.h>

#define BITS_PER_WORD (CHAR_BIT * sizeof(unsigned int))
#define I_WORD(i) ((unsigned int)(i) / BITS_PER_WORD)
#define I_BIT(i) (1 << ((unsigned int)(i) % BITS_PER_WORD))


typedef struct BitArray {
    int size;
    unsigned int values[1];
} BitArray;


static int newarray(lua_State *L) {
    int i;
    size_t nbytes;
    BitArray *a;

    int n = (int)luaL_checkinteger(L, 1);
    luaL_argcheck(L, n >= 1, 1 "invalid size");

    nbytes = sizeof(BitArray) + I_WORD(n - 1) * sizeof(unsigned int);
    a = (BitArray*)lua_newuserdata(L, nbytes);

    a->size = n;
    for (i = 0; i < I_WORD(n - 1); i++) {
        a->values[i] = 0;
    }

    return 1;
}


static int setarray(lua_State *L) {
    BitArray *a = (BitArray *)lua_touserdata(L, 1);
    int index = (int)luaL_checkinteger(L, 2) - 1;

    luaL_argcheck(L, a != NULL, 1, "array expected");
    luaL_argcheck(L, 0 <= index && index < a->size, 2, "index out of range");
    luaL_checkany(L, 3);

    if (lua_toboolean(L, 3)) {
        a->values[I_WORD(index)] |= I_BIT(index);
    } else {
        a->values[I_WORD(index)] &= ~I_BIT(index);
    }

    return 0;
}


static int getarray(lua_State *L) {
    BitArray *a = (BitArray *)lua_touserdata(L, 1);
    int index = (int)luaL_checkinteger(L, 2) - 1;

    luaL_argcheck(L, a != NULL, 1, "array expected");
    luaL_argcheck(L, 0 <= index && index < a->size, 2, "index out of range");

    lua_pushboolean(L, a->values[I_WORD(index)] & I_BIT(index));
    return 1;
}

为了在 Lua 中表示一个 C 语言结构体，Lua 提供了一个称为 用户数据（userdata）的基本类型。用户数据为 Lua 提供了可以用来存储任何数据的原始内存区域，没有预定义操作。lua_newuserdata 分配一块指定大小的内存，然后将用户数据压栈，并返回该块内存的地址。

如下还定义了一个获取数组大小的函数以及一些初始化库的额外代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
static int getsize(lua_State *L) {
    BitArray *a = (BitArray*)lua_touserdata(L, 1);
    luaL_argcheck(L, a != NULL, 1, "array expected");
    lua_pushinteger(L, a->size);
    return 1;
}


static const struct luaL_Reg arraylib[] = {
    {"new", newarray},
    {"set", setarray},
    {"get", getarray},
    {"size", getsize},
    {NULL, NULL}
};


int luaopen_array(lua_State *L) {
    luaL_newlib(L, arraylib);
    return 1;
}

元表

当前实现有漏洞，例如 setarray 并没有确认用户传入的参数的确是一个 BitArray* 指针，如果用户传入其他类型的指针，可能会造成内存越界访问。要区别不用类型的用户数据，一种常用的方法是每一种类型创建唯一的元表。每次创建用户数据时，用相应的元表进行标记，每当获取用户时，检查其是否有正确的元表。由于 Lua 代码不能改变用户数据的元表，因此不能绕过这些检查。

在 Lua 中，惯例是将所有新的 C 语言类型注册到注册表中，用类型名作为索引，以元表作为值。由于注册表中还有其他索引，所以需要谨慎选择类型名称以避免冲突。

辅助库提供了一些帮助函数：

  • luaL_newmetatable 创建一张新表（被称为元表），然后将其压入栈顶，并将该表与注册表中的指定名称关联起来
  • luaL_getmetatable 从注册表中获取与 tname 关联的元表
  • luaL_checkudata 会检查栈中指定位置上的对象是否是与指定名称的元表匹配的用户数据

对上述代码进行修改：

1
2
3
4
5
int luaopen_array(lua_State *L) {
    luaL_newmetatable(L, "LuaBook.array");
    luaL_newlib(L, arraylib);
    return 1;
}
1
2
3
4
5
6
static int newarray(lua_State *L) {
    ......
    luaL_getmetatable(L, "LuaBook.array");
    lua_setmetatable(L, -2);
    return 1;
}

setarray、getarray、getsize 则必须检查第一个参数是否为有效的数组：

1
2
#define checkarray(L) \
(BitArray*) luaL_checkudata(L, 1, "LuaBook.array")

面对对象访问

接下来将使这种新类型对象转换为一个对象，使得能够以普通的面向对象语法来操作该实例：

1
2
3
4
a = array.new(1000)
print(a:size())
a:set(10, true)
print(a:get(10))

a:size() 等价于 a.size(a)，因此我们需要让表达式 a.size() 返回函数 getsize()。这里的关键机制在于元方法 __index。对于表而言，Lua 会在找不到指定键时调用该元方法，而对于用户数据而言，由于它根本不提供 keys，所以每次访问时都会调用该元方法。

由于 array 的实例自己就是对象，因此 getsize、setsize 等方法就不再需要放到表 array 中。我们的库只需要导出一个用于创建新数组的函数 new 就行了，其他操作都成为对象的方法。C 代码允许我们直接这样注册。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
static const struct luaL_Reg arraylib_f[] = {
    {"new", newarray},
    {NULL, NULL}
};

static const struct luaL_Reg arraylib_m[] = {
    {"set", setarray},
    {"get", getarray},
    {"size", getsize},
    {NULL, NULL}
}

int luaopen_array(lua_State *L) {
    luaL_newmetatable(L, "LuaBook.array");
    lua_pushvalue(L, -1);
    lua_setfield(L, -2, "__index"); /* mt.__index = mt */
    luaL_setfuncs(L, arraylib_m, 0);
    luaL_newlib(L, arraylib_f);
    return 1;
}

这里使用了 luaL_setfuncs 将列表 arraylib_m 中的函数复制到栈顶的元表中，然后调用 luaL_newlib 创建一张新表，并在该表中注册来自列表中 arraylib_f 的函数。

我们可以继续在 arraylib_m 中继续添加其他元方法，例如 __tostring，这样 array 对象调用 print 时就可以打印其内容了。

数组访问

另一种更好的面向对象的表示方法是，使用普通的数组符号来访问数组，例如 a[i] 替代 a:get(i)。一种快速解决方案就是直接在 Lua 中定义这些元方法，例如：

1
2
3
4
local metaarray = getmetatable(array.new(1))
metaarray.__index = array.get
metaarray.__newindex = array.set
metaarray.__len = array.size

如果还要更加完美，可以在 C 语言代码中注册这些元方法。因此，需要需要重新修改初始化函数：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
static const struct luaL_Reg arraylib_f[] = {
    {"new", newarray},
    {NULL, NULL}
};

static const struct luaL_Reg arraylib_m[] = {
    {"__newindex", setarray},
    {"__index", getarray},
    {"__len", getsize},
    {NULL, NULL}
}

int luaopen_array(lua_State *L) {
    luaL_newmetatable(L, "LuaBook.array");
    luaL_setfuncs(L, arraylib_m, 0);
    luaL_newlib(L, arraylib_f);
    return 1;
}

轻量级用户数据

目前使用的用户数据称为 完全用户数据，Lua 还提供了另一种用户数据，称为 轻量级用户数据。轻量级用户数据是一个代表 C 语言的指针，即它是一个 void* 值，由于轻量级用户数据是一个值而不是一个对象，所以无需创建它。要将轻量级用户数据让入栈中，可以调用 lua_pushlightuserdata。

轻量级用户数据只是一个值，它没有元表，也不受垃圾收集器的管理。它真正的用途是相等性判，因此可以使用轻量级用户数据在 Lua 语言中查找 C 语言对象。

轻量级用户数据的一种典型用法，即在注册表中被用作键。此时轻量级用户数据的相等性是非常重要的。每次使用 lua_pushlightuserdata 压入相同的地址，都可以从注册表中得到相同的元素。

Lua 的另外一种典型场景是把 Lua 语言对象当做 C 语言对象的代理。例如输入/输出库使用 Lua 中的用户数据来表示 C 语言中的流：

  • 当操作是从 Lua 到 C 时，从 Lua 对象到 C 对应的映射很简单，每个 Lua 对象保存指向其相应 C 语言流的指针即可
  • 当操作是从 C 到 Lua 时，由于 C 语言流是由标准库定义的，我们无法在 C 语言流中存储任何对象。一种解决方案是，可以保存一张表（这张表很可能是弱应用的），其中键是 流地址的轻量级用户数据，而值则是 Lua 中表示流的对象，从而在该表中使用 C 地址来检索对应的 Lua 对象

管理资源

除了内存之外，对象可能还需要使用其他资源。此时当一个对象被当成垃圾回收后，其他资源也需要被释放。此时，当一个对象被当成垃圾收集后，其他资源也需要被释放。Lua 以 __gc 元方法的形式提供了析构器，为了完整地演示在 C 语言中对该元方法和 API 的使用，将会开发两个示例。

目录迭代器

如下实现了函数 dir.open，它是一个工厂函数，Lua 调用该函数创建迭代器：它打开一个 DIR 结构体并将该结构体作为 upvalue 创建一个迭代函数的闭包：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
#include <dirent.h>
#include <errno.h>
#include <string.h>

#include "lua.h"
#include "lauxlib.h"


static int dir_iter(lua_State *L);

static int l_dir(lua_State *L) {
    const char *path = luaL_checkstring(L, 1);

    DIR **d = (DIR **)lua_newuserdata(L, sizeof(DIR *));

    *d = NULL;

    luaL_getmetatable(L, "LuaBook.dir");
    lua_setmetatable(L, -2);

    *d = opendir(path);
    if (*d == NULL) {
        luaL_error(L, "cannot open %s:%s", path, strerror(errno));
    }

    lua_pushcclosure(L, dir_iter, 1);
    return 1;
}

static int dir_iter(lua_State *L) {
    DIR *d = *(DIR **)lua_touserdata(L, lua_upvalueindex(1));

    struct dirent *entry = readdir(d);
    if (entry != NULL) {
        lua_pushstring(L, entry->d_name);
        return 1;
    } else {
        return 0;
    }
}


static int dir_gc(lua_State *L) {
    DIR *d = *(DIR**)lua_touserdata(L, 1);
    if (d) {
        closedir(d);
    }
    return 0;
}

static const struct luaL_Reg dirlib[] = {
    {"open", l_dir},
    {NULL, NULL}
};


int luaopen_dir(lua_State *L) {
    luaL_newmetatable(L, "LuaBook.dir");

    lua_pushcfunction(L, dir_gc);
    lua_setfield(L, -2, "__gc");

    luaL_newlib(L, dirlib);
    return 1;
}

函数 dir_gc 就是元方法 __gc，该元方法用于关闭目录。一旦设置了元表，元方法 __gc 就一定会调用。因此在设置元表前，所以 l_dir 在设置元表前，需要使用 NULL 预先初始化用户数据，以确保用户数据具有明确定义的值。

XML 解析器

接下来将介绍一种用 Lua 编写的 Expat 绑定（binding）的简单实现，称为 lxp。Expat 是用 C 语言编写的开源 XML1.0 解析器，实现了 SAX，即 Simple API for XML。SAX 是一套基于事件的 API，这意味着 SAX 解析器在读取 XML 文档时会一边读取一边通过回调函数向应用上报读取到的内容。

为了在 Lua 中使用这个库，第一种方法是一种直接的方法，即简单地把所有函数导出给 Lua，另一个更好的方法是让这些函数适配 Lua。如下代码展示了如何实现这一点：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
#include <stdlib.h>
#include "expat.h"
#include "lua.h"
#include "lauxlib.h"


typedef struct lxp_userdata {
    XML_Parser parser;
    lua_State *L;
} lxp_userdata;

static void f_StartElement(void *ud,
                           const char *name,
                           const char **atts);
static void f_CharData(void *ud, const char *s, int len);
static void f_EndElement(void *ud, const char *name);


static int lxp_make_parser(lua_State *L) {
    XML_Parser p;

    lxp_userdata *xpu = (lxp_userdata *) lua_newuserdata(L, sizeof(lxp_userdata));
    xpu->parser = NULL;

    luaL_getmetatable(L, "Expat");
    lua_setmetatable(L, -2);

    p = xpu->parser = XML_ParserCreate(NULL);
    if (!p) {
        luaL_error(L, "XML_ParserCreate failed");
    }

    luaL_checktype(L, 1, LUA_TTABLE);
    lua_pushvalue(L, 1);
    lua_setuservalue(L, -2);

    XML_SetUserData(p, xpu);
    XML_SetElementHandler(p, f_StartElement, f_EndElement);
    XML_SetCharacterDataHandler(p, f_CharData);
    return 1;
}


static int lxp_parse(lua_State *L) {
    int status;
    size_t len;
    const char *s;
    lxp_userdata *xpu;

    xpu = (lxp_userdata *)luaL_checkudata(L, 1, "Expat");
    luaL_argcheck(L, xpu->parser != NULL, 1, "parser is closed");

    s = luaL_optlstring(L, 2, NULL, &len);
    lua_settop(L, 2);
    lua_getuservalue(L, 1);

    xpu->L = L;
    status = XML_Parse(xpu->parser, s, (int)len, s == NULL);

    lua_pushboolean(L, status);
    return 1;
}


static void f_CharData(void *ud, const char *s, int len) {
    lxp_userdata *xpu = (lxp_userdata*)ud;
    lua_State *L = xpu->L;

    lua_getfield(L, 3, "CharacterData");

    if (lua_isnil(L, -1)) {
        lua_pop(L, 1);
        return;
    }

    lua_pushvalue(L, 1);
    lua_pushlstring(L, s, len);
    lua_call(L, 2, 0);
}


static void f_EndElement(void *ud, const char *name) {
    lxp_userdata *xpu = (lxp_userdata *)ud;
    lua_State *L = xpu->L;

    lua_getfield(L, 3, "EndElement");
    if (lua_isnil(L, -1)) {
        lua_pop(L, 1);
        return;
    }

    lua_pushvalue(L, 1);
    lua_pushstring(L, name);
    lua_call(L, 2, 0);
}


static void f_StartElement(void *ud, const char *name, const char **atts) {
    lxp_userdata *xpu = (lxp_userdata *)ud;
    lua_State *L = xpu->L;

    lua_getfield(L, 3, "StartElement");
    if (lua_isnil(L, -1)) {
        lua_pop(L, 1);
        return;
    }

    lua_pushvalue(L, 1);
    lua_pushstring(L, name);

    lua_newtable(L);
    for (; *atts; atts += 2) {
        lua_pushstring(L, *(atts + 1));
        lua_setfield(L, -2, *atts);
    }

    lua_call(L, 3, 0);
}


static int lxp_close(lua_State *L) {
    lxp_userdata *xpu = (lxp_userdata *)luaL_checkudata(L, 1, "Expat");

    if (xpu->parser) {
        XML_ParserFree(xpu->parser);
    }

    xpu->parser = NULL;
    return 0;
}


static const struct luaL_Reg lxp_meths[] = {
    {"parse", lxp_parse},
    {"close", lxp_close},
    {"__gc", lxp_close},
    {NULL, NULL},
};


static const struct luaL_Reg lxp_funcs[] = {
    {"new", lxp_make_parser},
    {NULL, NULL},
};


int luaopen_lxp(lua_State *L) {
    luaL_newmetatable(L, "Expat");

    lua_pushvalue(L, -1);
    lua_setfield(L, -2, "__index");

    luaL_setfuncs(L, lxp_meths, 0);
    luaL_newlib(L, lxp_funcs);
    return 1;
}