skynet 常用lua函数汇总

service_snlua.c 

int lua_gc (lua_State *L, int what, int data);

控制垃圾收集器。这个函数根据其参数 what 发起几种不同的任务：

LUA_GCSTOP: 停止垃圾收集器。

LUA_GCRESTART: 重启垃圾收集器。

LUA_GCCOLLECT: 发起一次完整的垃圾收集循环。

LUA_GCCOUNT: 返回 Lua 使用的内存总量（以 K 字节为单位）。

LUA_GCCOUNTB: 返回当前内存使用量除以 1024 的余数。

LUA_GCSTEP: 发起一步增量垃圾收集。

LUA_GCSETPAUSE: 把 data 设为 垃圾收集器间歇率 （参见 §2.5），并返回之前设置的值。

LUA_GCSETSTEPMUL: 把 data 设为 垃圾收集器步进倍率 （参见 §2.5），并返回之前设置的值。

LUA_GCISRUNNING: 返回收集器是否在运行（即没有停止）。

关于这些选项的细节，参见 collectgarbage 。

void lua_setfield (lua_State *L, int index, const char *k);

做一个等价于 t[k] = v 的操作， 这里 t 是给出的索引处的值， 而 v 是栈顶的那个值。

这个函数将把这个值弹出栈。 跟在 Lua 中一样，这个函数可能触发一个 "newindex" 事件的元方法 （参见 §2.4）。

void luaL_openlibs (lua_State *L);

打开指定状态机中的所有 Lua 标准库。

void lua_pushlightuserdata (lua_State *L, void *p);

把一个轻量用户数据压栈。

用户数据是保留在 Lua 中的 C 值。 轻量用户数据 表示一个指针 void*。 

它是一个像数字一样的值： 你不需要专门创建它，它也没有独立的元表，而且也不会被收集（因为从来不需要创建）。 

只要表示的 C 地址相同，两个轻量用户数据就相等。

void luaL_requiref (lua_State *L, const char *modname, lua_CFunction openf, int glb);

如果 modname 不在 package.loaded 中,则调用函数 openf ,并传入字符串 modname。 将其返回值置入 package.loaded[modname]。 这个行为好似该函数通过 require 调用过一样。

如果 glb 为真,同时也讲模块设到全局变量 modname 里。

在栈上留下该模块的副本

void lua_setglobal (lua_State *L, const char *name);

从堆栈上弹出一个值，并将其设为全局变量 name 的新值。

void lua_pushcfunction (lua_State *L, lua_CFunction f);

将一个 C 函数压栈。 这个函数接收一个 C 函数指针， 并将一个类型为 function 的 Lua 值压栈。

当这个栈顶的值被调用时，将触发对应的 C 函数。

注册到 Lua 中的任何函数都必须遵循正确的协议来接收参数和返回值 （参见 lua_CFunction ）。

lua_pushcfunction 是作为一个宏定义出现的：

     #define lua_pushcfunction(L,f)  lua_pushcclosure(L,f,0)
 
int luaL_loadfile (lua_State *L, const char *filename);

等价于 luaL_loadfilex， 其 mode 参数等于 NULL。
int luaL_loadfilex (lua_State *L, const char *filename, const char *mode);

把一个文件加载为 Lua 代码块。 这个函数使用 lua_load 加载文件中的数据。 代码块的名字被命名为 filename。 

如果 filename 为 NULL， 它从标准输入加载。 如果文件的第一行以 # 打头，则忽略这一行。

mode 字符串的作用同函数 lua_load。

此函数的返回值和 lua_load 相同， 不过它还可能产生一个叫做 LUA_ERRFILE 的出错码。这种错误发生于无法打开或读入文件时，或是文件的模式错误。

和 lua_load 一样，这个函数仅加载代码块不运行。

void lua_call (lua_State *L, int nargs, int nresults);

调用一个函数。

要调用一个函数请遵循以下协议： 首先，要调用的函数应该被压入栈； 接着，把需要传递给这个函数的参数按正序压栈； 这是指第一个参数首先压栈。 最后调用一下 lua_call； 

nargs 是你压入栈的参数个数。 当函数调用完毕后，所有的参数以及函数本身都会出栈。 而函数的返回值这时则被压栈。 返回值的个数将被调整为 nresults 个， 除非 nresults 被设置成 LUA_MULTRET。 在这种情况下，所有的返回值都被压入堆栈中。 Lua 会保证返回值都放入栈空间中。 函数返回值将按正序压栈（第一个返回值首先压栈）， 因此在调用结束后，最后一个返回值将被放在栈顶。

被调用函数内发生的错误将（通过 longjmp ）一直上抛。

下面的例子中，这行 Lua 代码等价于在宿主程序中用 C 代码做一些工作：

     a = f("how", t.x, 14)

这里是 C 里的代码：

     lua_getglobal(L, "f");                  /* function to be called */

     lua_pushliteral(L, "how");                       /* 1st argument */

     lua_getglobal(L, "t");                    /* table to be indexed */

     lua_getfield(L, -1, "x");        /* push result of t.x (2nd arg) */

     lua_remove(L, -2);                  /* remove 't' from the stack */

     lua_pushinteger(L, 14);                          /* 3rd argument */

     lua_call(L, 3, 1);     /* call 'f' with 3 arguments and 1 result */

     lua_setglobal(L, "a");                         /* set global 'a' */

注意上面这段代码是 平衡 的： 到了最后，堆栈恢复成原有的配置。 这是一种良好的编程习惯

int lua_pcall (lua_State *L, int nargs, int nresults, int msgh);

以保护模式调用一个函数。

nargs 和 nresults 的含义与 lua_call 中的相同。 如果在调用过程中没有发生错误， lua_pcall 的行为和 lua_call 完全一致。 但是，如果有错误发生的话， lua_pcall 会捕获它， 然后把唯一的值（错误消息）压栈，然后返回错误码。 同 lua_call 一样， lua_pcall 总是把函数本身和它的参数从栈上移除。

如果 msgh 是 0 ， 返回在栈顶的错误消息就和原始错误消息完全一致。 否则， msgh 就被当成是 错误处理函数 在栈上的索引位置。 （在当前的实现里，这个索引不能是伪索引。） 在发生运行时错误时， 这个函数会被调用而参数就是错误消息。 错误处理函数的返回值将被 lua_pcall 作为错误消息返回在堆栈上。

典型的用法中，错误处理函数被用来给错误消息加上更多的调试信息， 比如栈跟踪信息。 这些信息在 lua_pcall 返回后， 由于栈已经展开，所以收集不到了。

lua_pcall 函数会返回下列常数 （定义在 lua.h 内）中的一个：

LUA_OK (0): 成功。

LUA_ERRRUN: 运行时错误。

LUA_ERRMEM: 内存分配错误。对于这种错，Lua 不会调用错误处理函数。

LUA_ERRERR: 在运行错误处理函数时发生的错误。

LUA_ERRGCMM: 在运行 __gc 元方法时发生的错误。 （这个错误和被调用的函数无关。）



int lua_pcallk (lua_State *L,

                int nargs,

                int nresults,

                int msgh,

                lua_KContext ctx,

                lua_KFunction k);

这个函数的行为和 lua_pcall 完全一致，只不过它还允许被调用的函数让出 （参见 §4.7）。

void lua_settop (lua_State *L, int index);

参数允许传入任何索引以及 0 。 它将把堆栈的栈顶设为这个索引。 如果新的栈顶比原来的大， 超出部分的新元素将被填为 nil 。 如果 index 为 0 ， 把栈上所有元素移除。

int lua_getfield (lua_State *L, int index, const char *k);

把 t[k] 的值压栈， 这里的 t 是索引指向的值。 在 Lua 中，这个函数可能触发对应 "index" 事件对应的元方法 （参见 §2.4 ）。

函数将返回压入值的类型。