第二十四课 C API概述

Lua是一种嵌入式语言，即Lua不是一个单独运行的程序，而是一个可以链接到其他程序的库。通过链接就可以将Lua的功能合并入这些程序。

如果Lua不是一个独立运行的程序，那么之前我们使用的Lua程序是怎么来的呢？这个问题的答案是Lua解释器，即可执行程序“lua”。这个解释器是一个简单的应用程序，它依靠Lua库来实现主要功能。这个程序会处理 与用户的交互，它将用户的文件或字符串输入Lua库，由Lua库来完成主要的工作，例如真正地运行Lua代码等。

这种使用一个库来扩展应用程序的能力使得Lua成为一种“扩展语言”。而与此同时，一个使用了Lua的程序可以在Lua环境中注册C语言或其他语言实现的新函数，由此就可以向Lua添加某些无法直接用Lua编写的功能， 这便使Lua成为一种“可扩展的语言”。

C API是一组能使C代码与Lua交互的函数。其中包括读写Lua全局变量、调用Lua函数、运行一段代码，以及注册C函数以供Lua代码调用等。

Lua和C语言通信的主要方法是一个无所不在的虚拟栈。几乎所有的API调用都会操作这个栈上的值。所有的数据交换，无论是Lua到C语言或C语言到Lua都通过这个栈 来完成。此外，还可以用这个栈来保存一些中间结果。栈可以解决Lua和C语言之间存在的两大差异，第一种差异是Lua使用垃圾收集，而C语言要求显示地释放内存；第二种是Lua使用动态类型，而C语言使用静态类型。

第一个示例

通过一个简单的Lua解释器程序来开始学习C API。以下代码是一个最原始的解释器程序：

#include <stdio.h>

#include <string.h>

#include "lua.h"

#include "lauxlib.h"

#include "lualib.h"

int main(void)

{

char buff[256];

int error;

lua_State *L = luaL_newstate(); //打开Lua

luaL_openLibs(L); //打开标准库

while (fgets(buff, sizeof(buff), stdin) != NULL)

{

error = luaL_loadbuffer(L, buff, strlen(buff), "line") || lua_pcall(L, 0, 0, 0);

if (error)

{

fprintf(stderr, "%s", lua_tostring(L, -1));

lua_pop(L, 1); //从栈中弹出错误消息

}

}

lua_close(L);

return 0;

}

头文件lua.h定义了Lua提供的基础函数，包括创建Lua环境、调用Lua函数（如lua_pcall）、读写Lua环境中全局变量，以及注册供Lua调用的新函数等。lua.h中定义所有内容都有一个lua_前缀。

头文件 lauxlib.h定义了辅助库（ auxiliary、library、auxlib）提供的函数。它的所有定义都以luaL_开头。辅助库是一个使用lua.h中API编写的一个较高的抽象层。Lua的所有标准库编写都用到了辅助库。基础API的设计保持原子性和正交性，而辅助库则侧重于解决具体的任务。当然，程序若要创建自己的抽象也是非常简单的。注意辅助库并 没有直接访问Lua的内部，它都是用官方的 基础API来完成所有的工作的。

Lua库中没有定义任何全局变量。它将所有的 状态都保存在动态结构 lua_State中，所有的C API都要求 传入一个指向该结构的指针。这种实现使得Lua可以重入，稍加修改即可用于多线程的代码中。

luaL_newstate函数用于创建一个新环境（或状态）。当 luaL_newstate创建一个新的环境时，新环境中没有包含预定义的函数，甚至没有print。为了使Lua保持小巧，所有的标准库都被组织到了不同的包中。这样便可以忽略那些不需要的包。在头文件lualib.h中定义了打开这些库的函数，而辅助库函数 luaL_openlibs则可以打开所有的标准库。

当创建好一个状态，并在其中加载了标准库后，就可以解释用户的输入了。程序调用 luaL_loadbuffer来编译用户输入的每行内容。如果没有错误，此调用返回0，并向栈中压入编译后的程序块。然后，程序调用lua_pcall，这个函数会将程序块从栈中弹出，并在保护模式中运行它。与 luaL_loadbuffer类似，lua_pcall返回0表示没有错误。若发生错误，那么这些函数就会向栈中压入一条错误消息。用lua_tostring可以获取这条消息，打印后可以用 lua_pop把它从栈中删除。

Lua可以同时作为C代码或C++代码来编译。某些C程序库中 常会出现以下这种 调节代码，而在lua.h中并没有包含它们：

#ifdef --cplusplus

extern "C"{

#endif

...

#ifdef --cplusplus

}

#endif

如果将Lua作为C代码来编译，并在C++中使用它，那么 可以包含lua.hpp来代替lua.h。lua.hpp定义为：

extern "C"{

#include "lua.h"

}

栈

在Lua和C语言之间交换数据时，需要面对两个问题：

1、动态类型和静态类型之间的区别；

2、自动内存管理和手动内存管理之间的区别。

在Lua中，当用户写a[k]=v，k和v可以是任意的类型。甚至于a也有可能是其他类型，因为可以通过元表重载操作符。假设要在C语言中提供一个API函数settable。由于C函数的参数是固定类型，所以必须为各种类型的参数编写一个settable函数。

可以在C语言中声明一些联合（union）类型来解决这个问题。假设这种类型叫做lua_Value，能够表示所有的Lua值。那么settable就可以声明为：

void lua_settable(lua_Value a, lua_Value k, lua_Value v)

这种做法有两个缺点。首先，很难将这种复杂的类型映射到其他语言中。Lua的设计目标不仅仅是为了便于C/C++访问，还应该可以被Java、 Fortran、C#或其他语言访问。其次，Lua采用垃圾收集机制，如果将一个Lua table保持在一个C变量中，Lua引擎则无法搜索出，因此，它会认为这个table是垃圾文件，并回收它。

由于上述原因，Lua API中没有定义任何类似于 lua_Value的类型，而是使用了一个抽象的栈，在Lua和C语言之间交换数据。栈中的每个元素都能保存任何类型的Lua值。要获取Lua中的一个值时，只要调用一个Lua API函数，Lua就会将指定的值压入栈中。要将一个值传给Lua时，需要先将这个值压入栈，然后调用Lua API，Lua就会获取该值并将其从栈中弹出。为了将C类型的值压入栈，或者从栈中获取不同类型的值，就需要为每种类型定义一个特定的函数。但这种定义的数量远远小于上例中提到的定义settable的数量。另外，由于这个栈是Lua管理的，垃圾收集器能确定C语言使用哪些值。

Lua严格按照LIFO后进先出的规范来操作这个栈。当调用Lua时，Lua只会改变栈的顶部。不过，C代码则有更大的自由度，它可以检索栈中间的元素，甚至在栈的任意位置插入或删除元素。

压入元素

对于每种可以呈现在Lua中的C类型，API都有一个对应的压入函数：

nil lua_pushnil

双精度浮点数 lua_pushnumber

整数 lua_pushinteger

布尔（C语言中的整数） lua_pushboolean

任意字符串（char*及长度） lua_pushlstring

零结尾的字符串 lua_pushstring

void lua_pushnil (lua_State *L);

void lua_pushboolean (lua_State *L, int bool);

void lua_pushnumber (lua_State *L, lua_Number n);

void lua_pushinteger (lua_State *L, lua_Integer n);

void lua_pushlstring (lua_State *L, const char *s, size_t len);

void lua_pushstring (lua_State *L, const char *s);

类型 lua_Number是Lua中的数字类型。默认为 双精度浮点数，但有些 发行版本为了适应某种硬件受限的环境，会将数字类型改 为 单精度浮点数或 长整数。类型lua_Integer是一种整数类型，它足以存储大型字符串的长度，通常定义为ptrdiff_t类型。

Lua中的字符串不是以零结尾的，它们可以包含任意二进制数据。因此，它们必须同时保存一个显示的长度。将字符串压入栈的基本函数是 lua_pushlstring，它要求传入一个显示的长度参数。对于零结尾的字符串，可以使用使用函数lua_pushstring，这个函数通过strlen来计算字符串的长度。Lua不会持有指向外部字符串的指针。对于所有Lua持有的字符串，它都会生成一个内部副本，或者复用现有的内容。因此，即使在这些函数返回后立即释放或修改这些字符串，也不会出现问题。

向栈中压入一个元素时，应该确保栈中具有足够的 空间。当Lua启动时，或Lua调用C语言时，栈中至少会有20个空闲槽。这些空间对于普通的应用是足够了，所以一般我们无须顾及空间上的问题。然而有些任务会需要更多的空间，例如一个具有很多参数的函数，在这些情况中，就要调用 lua_checkstack来检查栈中是否有足够的空间：

int lua_checkstack(lua *L, int sz）；

查询元素

API是使用“索引”来引用栈中的元素。第一个压入栈中的元素的索引为1；第二个压入的元素索引为2， 以此类推直到栈顶。还可以以栈顶为参考物，使用负数的索引来访问栈中的元素。此时，-1表示栈顶元素（最后压入的元素），-2表示栈顶下面的元素， 以此类推。例如，调用lua_tostring(L, -1)会将栈顶的值作为一个字符串返回。其中有些情况适用于从栈底索引栈，而另一些情况则便于使用负数索引。

为了检查一个元素是否为特定的类型，API提供了一系列的 函数lua_is*，其中*可以是任意lua类型。这些函数有lua_isnumber、lua_isstring和lua_istable等。所有这些函数都有同样的原型：

int lua_is* (lua_State *L, int index);

实际上，lua_isnumber不会检查值是否为数字类型，而是检查值是否能转换为数字类型。lua_isstring也具有同样的行为。因此，对于任意数字，lua_isstring都返回真。

还有一个函数lua_type，它会返回栈中元素的类型。每种类型都对应于一个常量，这些常量定义在头文件lua.h中，它们是LUA_TNIL,LUA_TBOOLEAN，LUA_TNUMBER，LUA_TSTRING、LUA_TTABLE、LUA_TTHREAD、 LUA_TUSERDATA和LUA_TFUNCTION。这个函数一般可用在一个switch语句中。另外，若要检查一个元素是否为真正的字符串或数字（无须转换的），也可以使用这个函数。

lua_to*函数用于从栈中获取一个值：

int lua_toboolean (lua_State *L, int index);

lua_Number lua_tonumber (lua_State *L, int index);

lua_Integer lua_tointeger (lua_State *L, int index);

const char *lua_tolstring (lua_State *L, int index, size_t *len);

size_t lua_objlen (lua_State *L, int index);

如果指定的元素不具有正确的类型，调用这些函数也不会有问题。在这种情况下， lua_toboolean、lua_tonumber、 lua_tointeger和 lua_objlen会返回0，而其他函数会返回 NULL。返回0并不是很有用，但ANSI C也没有提供其他可以表示错误的值。至于其他lua_to*函数，通常不先使用lua_is*函数，只需在调用它们之后测试返回结果是否为NULL就可以了。

lua_tolstring函数会返回一个指向内部字符串副本的指针，并将字符串的长度存入最后一个参数len中。这个内部副本不能修改，返回 类型中的const也说明了这点。Lua 保证只要这个对应的字符串值还在栈中，那么这个指针就是有效的。当Lua调用的一个C函数返回时，Lua就会清空它的栈。这就形成了一条规则，不要在C函数之外使用在C函数内获得的指向Lua字符串的指针。

所有 lua_tolstring返回字符串在其末尾都会有一个额外的零，不过这些字符串的中间也有可能会有零。字符串长度通过第三个参数len返回，这才是真正的字符串长度。进一步说 ，假设栈顶的值是一个字符串，如下总是为真：

size_t l;

const char *s = lua_tolstring(L, -1, &l); /*任何Lua字符串*/

assert(s[l] == '\0');

assert(strlen(s) <= l);

如果不需要长度信息，可以将第三个参数设为NULL来调用lua_tolstring。或者使用宏lua_tostring，这个宏就是用NULL作为第三个参数来调用lua_tolstring。

lua_objlen函数可以返回一个对象的“长度”。对于字符串和table，这个值是长度操作符‘#’的结果。这个函数可以用于获取一个“完全userdata”的大小。

为了演示这些函数的使用，以下代码实现了一个有用的辅助函数，它会打印整个栈的内容，这个 函数会由下而上地遍历栈，并根据每个元素的类型打印其值，字符串放在一对单引号内打印，数字使用格式“%g”来打印，其他值（table、函数等）则只打印它们的类型。其中， lua_typename可将一个类型编码转换为一个类型名。

static void stackDump (lua_State *L)

{

int i;

int top = lua_gettop(L);

for (i = 1; i <= top; ++i)

{

//遍历所有层

int t = lua_type(L, i);

switch (t)

{

case LUA_TSTRING:

{

//字符串

printf("'%s'", lua_tostring(L, i));

break;

}

case LUA_TBOOLEAN:

{

//布尔

printf(lua_toboolean(L, i) ? "true" : "false");

break;

}

case LUA_TNUMBER:

{

//数字

printf("%g", lua_tonumber(L, i));

break;

}

default:

{

//其他值

printf("%s", lua_typename(L, i));

break;

}

}

printf(" "); //打印一个分隔符

}

printf("\n"); //列表结尾

}

其他栈操作

除了在C语言和栈之间交换数据的函数外，API还提供了以下这些用于普通栈操作的函数：

//返回栈中元素的个数，也可以说是栈顶元素的索引。

int lua_gettop (lua_State *L);

//将栈顶设置为一个指定的位置，即修改栈中元素的数量。如果之前的栈顶比新设置的更高，那么高出来的部分会被丢弃;反之，会向栈中压入nil来补足大小。有一个特例，调用lua_settop(L, 0)能清空栈。也可以用负数索引 来使用 lua_settop。另外，API根据这个函数还提供了一个宏，用于从栈中弹出n个元素：#define lua_pop(L, n) lua_settop(L, -(n) - 1)

void lua_settop (lua_State *L, int index);

//lua_pushvalue函数会将指定索引上值的副本压入栈。

void lua_pushvalue (lua_State *L, int index);

//lua_remove删除指定索引上的元素，并将该位置之上的所有元素下移以填补空缺。

void lua_remove (lua_State *L, int index);

//lua_insert会上移指定位置之上的所有元素以开辟一个槽的空间，然后将栈顶元素移到该位置。

void lua_insert (lua_State *L, int index);

//lua_replace弹出栈顶的值，并将该值设置到指定索引上，但它不会移动任何东西。

void lua_replace (lua_State *L, int index);

# include <stdio.h>

#include "lua.h"

#include "luaxlib.h"

static void stackDump (lua_State *L)

{

<如之前的示例>

}

int main (void)

{

lua_State *L = luaL_newstate();

lua_pushboolean(L, 1);

lua_pushnumber(L, 10);

lua_pushnil(L);

lua_pushstring(L, "hello");

stackDump(L); //true 10 nil 'hello'

lua_pushvalue(L, -4);

stackDump(L); //true 10 nil 'hello' true

lua_replace(L, 3);

stackDump(L); //true 10 true 'hello'

lua_settop(L, 6);

stackDump(L); //true 10 true 'hello' nil nil

lua_remove(L, -3);

stackDump(L); //true 10 true nil nil

lua_settop(L, -5);

stackDump(L); //true

lua_close(L);

return 0;

}

C API中的错误处理

C语言不同于C++和Java，它没有提供异常处理机制。为了克服这个困难，Lua使用C语言中的setjmp机制，这是一种类似与异常处理的机制。

Lua中的所有结构都是动态的，它们会根据 需要来增长，或者缩小。在Lua中有许多地方可能会发生内存分配错误。几乎所有的函数都要面对这种潜在的错误。那么在发生错误时，与其让API中的每个函数返回错误代码，不如使用异常来标记这些错误。因此，几乎所有的API函数都会抛出错误（即调用longjmp），而 不是返回错误。

当编写库代码 时（被Lua调用的C函数），使用longjmp几乎和使用异常处理机制一样方便，Lua会捕获所有可能的错误。而当编写应用程序代码（调用Lua的C代码），必须提供一种捕获错误的方式。

应用程序代码中的错误处理

通常情况下，应用程序代码是以“无保护”模式运行的。由于它们不是由Lua调用的，Lua无法设置适当的上下文来捕获错误。因此，当Lua发现了例如“内存不足”这类错误时，它基本上不会 进行太多的处理。此时，Lua会调用一个“紧急函数“，当这个函数返回后，Lua就会结束应用程序。用户可以通过函数set_atpanic来设置自己的”紧急“函数。

如果发生了内存分配错误，而又不想结束应用程序，那么有两种做法。第一种是设置一个“紧急”函数，让它不要把控制权返回给Lua。例如，可以调用longjmp转到之前setjmp所设置的位置。第二种做法是让代码在“保护模式”下运行。

大多数应用程序 （包括Lua解释器程序）都采用第二种做法，它们调用lua_pcall来运行Lua代码。因而这些Lua代码 也都是运行在保护模式中的。如果发生了内存分配错误，lua_pcall会返回一个错误代码，并将解释器 封固在 一致的状态。如果要保护那些与Lua交互的C代码，可以使用 lua_cpcall。这个函数类似于lua_pcall，但它接受一个C函数作为参数，然后调用这个C 函数 。将一个函数压入栈中不会有内存分配失败的可能。

库代码中的错误处理

Lua是一种安全的语言，无论写什么，写出来的内容是否正确，都能用Lua自身的术语来理解程序的行为。此外，错误也是通过Lua的 术语来检测和解释的。可以用C语言来做一个对比，许多C程序的错误行为只能用底层硬件的术语来解释，而错误位置则是由“程序计数器”寄存器给出的。

当将新的C函数加入Lua时，就有可能打破这种安全性。例如，添加一个函数poke，它能在任意内存地址上存储任意字节。这个函数就有可能引起各种内存破坏。因此必须确保新加入的函数对Lua是安全的，并提供良好的错误处理。

正如之前所说的，每个C程序都有各自处理错误的方法。然而，当为Lua 编写库函数时，却只有一种标准的 错误处理方法。当一个C函数检测到一个错误时，它就应该调用lua_error。lua_error函数会清理Lua中所有需要清理的东西，然后 跳转回发起执行的那个lua_pcall，并附上一条错误消息。