// redis-v7.2/src/eval.c#183

/* 初始化 lua 环境
 *
 * redis 首次启动时调用，此时 setup 为 1,
 * 这个函数也会在 redis 的其他生命周期中被调用，此时 setup 为 0，但是被简化为 scriptingReset 调用。
 */ 
void scriptingInit(int setup) {
    lua_State *lua = lua_open();

    if (setup) {
        // 首次启动时，初始化 lua 环境 和 ldb (Lua debugger) 的一些数据结构
        lctx.lua_client = NULL;
        server.script_disable_deny_script = 0;
        ldbInit();
    }

    /* 初始化 lua 脚本字典，用于存储 sha1 -> lua 脚本的映射
     * 用户使用 EVALSHA 命令时，从这个字典中查找对应的 lua 脚本。
     */
    lctx.lua_scripts = dictCreate(&shaScriptObjectDictType);
    lctx.lua_scripts_mem = 0;

    /* 注册 redis 的一些 api 到 lua 环境中 */
    luaRegisterRedisAPI(lua);

    /* 注册调试命令 */
    lua_getglobal(lua,"redis");

    /* redis.breakpoint */
    lua_pushstring(lua,"breakpoint");
    lua_pushcfunction(lua,luaRedisBreakpointCommand);
    lua_settable(lua, -3);
    /* redis.debug */
    lua_pushstring(lua,"debug");
    lua_pushcfunction(lua,luaRedisDebugCommand);
    lua_settable(lua,-3);
    /* redis.replicate_commands */
    lua_pushstring(lua, "replicate_commands");
    lua_pushcfunction(lua, luaRedisReplicateCommandsCommand);
    lua_settable(lua, -3);

    lua_setglobal(lua,"redis");

    /* 注册一个错误处理函数，用于在 lua 脚本执行出错时，打印出错信息。
     * 需要注意的是，当错误发生在 C 函数中时，我们需要打印出错的 lua 脚本的信息，
     * 这样才能帮助用户调试 lua 脚本。
     */
    {
        char *errh_func =       "local dbg = debug\n"
                                "debug = nil\n"
                                "function __redis__err__handler(err)\n"
                                "  local i = dbg.getinfo(2,'nSl')\n"
                                "  if i and i.what == 'C' then\n"
                                "    i = dbg.getinfo(3,'nSl')\n"
                                "  end\n"
                                "  if type(err) ~= 'table' then\n"
                                "    err = {err='ERR ' .. tostring(err)}"
                                "  end"
                                "  if i then\n"
                                "    err['source'] = i.source\n"
                                "    err['line'] = i.currentline\n"
                                "  end"
                                "  return err\n"
                                "end\n";
        luaL_loadbuffer(lua,errh_func,strlen(errh_func),"@err_handler_def");
        lua_pcall(lua,0,0,0);
    }

    /* 创建一个 lua client (没有网络连接)，用于在 lua 环境中执行 redis 命令。
     * 这个客户端没必要在 scriptingReset() 调用时重新创建。
     */
    if (lctx.lua_client == NULL) {
        lctx.lua_client = createClient(NULL);
        lctx.lua_client->flags |= CLIENT_SCRIPT;

        /* We do not want to allow blocking commands inside Lua */
        lctx.lua_client->flags |= CLIENT_DENY_BLOCKING;
    }

    /* Lock the global table from any changes */
    lua_pushvalue(lua, LUA_GLOBALSINDEX);
    luaSetErrorMetatable(lua);
    /* Recursively lock all tables that can be reached from the global table */
    luaSetTableProtectionRecursively(lua);
    lua_pop(lua, 1);

    lctx.lua = lua;
}

-- 模块实例化
local cjson = require "cjson"
local cjson2 = cjson.new()
local cjson_safe = require "cjson.safe"

-- 在 lua 和 json 之间转换
text = cjson.encode(value)
value = cjson.decode(text)

-- 读取 lua json 中的值
setting = cjson.decode_invalid_numbers([setting])
setting = cjson.encode_invalid_numbers([setting])
keep = cjson.encode_keep_buffer([keep])
depth = cjson.encode_max_depth([depth])
depth = cjson.decode_max_depth([depth])
convert, ratio, safe = cjson.encode_sparse_array([convert[, ratio[, safe]]])

make
cp cjson.so $LUA_MODULE_DIRECTORY

#include <stdarg.h>
#include <stdio.h>
#include <stdlib.h>
#include <lua.h>
#include <lauxlib.h>
#include <lualib.h>

static int sumForLua(lua_State *lua)
{
    // 如果给定虚拟栈中索引处的元素可以转换为数字，则返回转换后的数字，否则报错。
    double a = luaL_checknumber(lua, 1);
    double b = luaL_checknumber(lua, 2);

    // push 计算结果到 lua 虚拟栈中
    lua_pushnumber(lua, a+b); 

    /* 返回值用于提示该C函数的返回值数量。
     * 
     * 这里可以看出，C可以返回给Lua多个结果，
     * 通过多次调用lua_push*()，之后return返回结果的数量。
     */
    return 1;  
}

int main(void)
{
    lua_State *lua = lua_open(); // 创建 Lua 环境
    luaL_openlibs(lua);          // 打开Lua状态机"L"中的所有Lua标准库。

    // 注册 C函数到 lua 中 csum 函数
    lua_register(lua, "csum", sumForLua);  

    // 执行 Lua 脚本
    const char* script = "print(csum(3.14, 2.0))";
    if(luaL_dostring(lua, script))    
        printf("Failed to invoke.\n");
    lua_close(lua); 

    return 0;
}

// https://github.com/mpx/lua-cjson/blob/master/lua_cjson.c#1416
CJSON_EXPORT int luaopen_cjson(lua_State *l)
{   
    // local cjson = require "cjson"
    lua_cjson_new(l);

// 如果编译时定义了 ENABLE_CJSON_GLOBAL，注册 cjson (table) 到全局变量中
#ifdef ENABLE_CJSON_GLOBAL
    lua_pushvalue(l, -1);
    // #define CJSON_MODNAME "cjson"
    lua_setglobal(l, CJSON_MODNAME);
#endif

    return 1;
}

// cjson 模块（table）的初始化
static int lua_cjson_new(lua_State *l)
{
    // 函数注册表, 这些函数的函数原型都满足：
    // int (*lua_CFunction) (lua_State *L); return value: number of results
    // 
    // 注册表结构体：
    // typedef struct luaL_Reg {
    //   const char *name;
    //   lua_CFunction func;
    // } luaL_Reg;
    // 
    luaL_Reg reg[] = {
        { "encode", json_encode },
        { "decode", json_decode },
        { "encode_sparse_array", json_cfg_encode_sparse_array },
        { "encode_max_depth", json_cfg_encode_max_depth },
        { "decode_max_depth", json_cfg_decode_max_depth },
        { "encode_number_precision", json_cfg_encode_number_precision },
        { "encode_keep_buffer", json_cfg_encode_keep_buffer },
        { "encode_invalid_numbers", json_cfg_encode_invalid_numbers },
        { "decode_invalid_numbers", json_cfg_decode_invalid_numbers },
        { "new", lua_cjson_new },
        { NULL, NULL } /* 以 NULL, NULL 结束 */
    };
    // ...

    // 创建一个新的 table, 并且将其压入栈中
    lua_newtable(l);
    // ...

    json_create_config(l);
    // 将 reg 中的函数注册到 table 中
    // void luaL_setfuncs (lua_State *L, const luaL_Reg *l, int nup);
    // nup = 1 (不等于0) 表示将 nup 位置的值副本来初始化所有的函数，这些值会弹出栈。
    // 因此这里是给 reg 中的所有函数都隐式的传入了一个 config 参数, 函数内部可以通过
    // int lua_upvalueindex(int i); lua_to* 函数来获取这个参数。
    luaL_setfuncs(l, reg, 1);

    // 设置 table.null = nil, userdata 代表 Lua中的 C 值
    lua_pushlightuserdata(l, NULL);
    // void lua_setfield (lua_State *L, int index, const char *k);
    // table = stack[index]; table[k] = v (stack[-1]), 设置后 v会从栈中弹出
    lua_setfield(l, -2, "null");

    // 下面的类似，都是在设置 table 中的字段, 如: _NAME, _VERSION
    lua_pushliteral(l, CJSON_MODNAME);
    lua_setfield(l, -2, "_NAME");
    lua_pushliteral(l, CJSON_VERSION);
    lua_setfield(l, -2, "_VERSION");

    // 此时栈中还剩下 1 个 table
    return 1;
}

// redis-v7.2/src/eval.c#183
void scriptingInit(int setup) {
    // ... some codes ignored

    // 声明全局变量 redis, 同时压入栈中
    lua_getglobal(lua, "redis"); 
    // 往虚拟栈中压入 字符串 "breakpoint"
    lua_pushstring(lua, "breakpoint");
    // 往虚拟栈中压入 C 函数 luaRedisBreakpointCommand
    lua_pushcfunction(lua, luaRedisBreakpointCommand);
    // 设置 redis["breakpoint"] = luaRedisBreakpointCommand
    lua_settable(lua, -3);

    // 将 redis 弹出栈
    lua_setglobal(lua, "redis");

    // ... some codes ignored
}

redis = {}
redis["breakpoint"] = luaRedisBreakpointCommand

+----bottom----+
|      {}      | [1, -3]  lua_getglobal(lua, "redis");
+--------------+
| "breakpoint" | [2, -2]  lua_pushstring(lua,"breakpoint");
+--------------+
|   function   | [3, -1]  lua_pushcfunction(lua,luaRedisBreakpointCommand);
+------top-----+


+---------------------bottom--------------------------+
|      {"breakpoint": luaRedisBreakpointCommand}      | [1, -1]  lua_settable(lua, -3);
+-----------------------top---------------------------+

// 普通调用
void lua_call (lua_State *L, int nargs, int nresults);
// 异常捕获调用
// msgh 用于是否使用自定义的错误处理函数，如果为 0，那么使用默认的错误处理函数
// 否则，msgh 用于说明：异常消息处理函数在堆栈中的位置
int lua_pcall (lua_State *L, int nargs, int nresults, int msgh);

// redis-v7.2/src/eval.c#183
void scriptingInit(int setup) {
    // ...

    /* 注册一个错误处理函数，用于在 lua 脚本执行出错时，打印出错信息。
     * 需要注意的是，当错误发生在 C 函数中时，我们需要打印出错的 lua 脚本的信息，
     * 这样才能帮助用户调试 lua 脚本。
     */
    {
        char *errh_func =       "local dbg = debug\n"
                                "debug = nil\n"
                                "function __redis__err__handler(err)\n"
                                "  local i = dbg.getinfo(2,'nSl')\n"
                                "  if i and i.what == 'C' then\n"
                                "    i = dbg.getinfo(3,'nSl')\n"
                                "  end\n"
                                "  if type(err) ~= 'table' then\n"
                                "    err = {err='ERR ' .. tostring(err)}"
                                "  end"
                                "  if i then\n"
                                "    err['source'] = i.source\n"
                                "    err['line'] = i.currentline\n"
                                "  end"
                                "  return err\n"
                                "end\n";
        // int luaL_loadbuffer (lua_State *L, const char *buff, size_t sz, const char *name);
        // 加载 lua 块，但是不执行，会将编译后的 lua 块压入栈中，如果出错会将错误信息压入栈中
        luaL_loadbuffer(lua, errh_func, strlen(errh_func), "@err_handler_def");
        // int lua_pcall (lua_State *L, int nargs, int nresults, int msgh);
        // 执行 lua 块，如果出错，pcall 会将错误信息压入栈中
        lua_pcall(lua, 0, 0, 0);
    }
    // ...
}

// redis-v7.2/src/eval.c#472
void evalGenericCommand(client *c, int evalsha) {
    // ...

    // 将 __redis__err__handler 压入栈中，已经在初始化过程中通过 lua 块定义成了全局变量
    lua_getglobal(lua, "__redis__err__handler");
    // ... 

    // void luaCallFunction(scriptRunCtx* run_ctx, lua_State *lua, robj** keys, size_t nkeys, robj** args, size_t nargs, int debug_enabled)
    luaCallFunction(&rctx, lua, c->argv+3, numkeys, c->argv+3+numkeys, c->argc-3-numkeys, ldb.active);

    // 从栈中移除 __redis__err__handler 
    lua_pop(lua,1);
    // ...
}

// redis-v7.2/src/script_lua.c#L1615
void luaCallFunction(scriptRunCtx* run_ctx, lua_State *lua, robj** keys, size_t nkeys, robj** args, size_t nargs, int debug_enabled) {
    // ...

    // 创建一个数组，用于存储 keys
    luaCreateArray(lua,keys,nkeys);
    if (run_ctx->flags & SCRIPT_EVAL_MODE){
        // EVAL模式：KEYS 从栈中弹出成为全局变量 KEYS
        lua_enablereadonlytable(lua, LUA_GLOBALSINDEX, 0);
        lua_setglobal(lua,"KEYS");
        lua_enablereadonlytable(lua, LUA_GLOBALSINDEX, 1);
    }
    // 下同，创建一个数组，用于存储 args
    luaCreateArray(lua,args,nargs);
    if (run_ctx->flags & SCRIPT_EVAL_MODE){
        lua_enablereadonlytable(lua, LUA_GLOBALSINDEX, 0);
        lua_setglobal(lua,"ARGV");
        lua_enablereadonlytable(lua, LUA_GLOBALSINDEX, 1);
    }

    /* 执行 lua 脚本
     * 如果是 EVAL 模式, 那么 lua 代码应该没有参数，然后接受一个返回值，此时 error_handler 在 -2 的位置。
     * 如果是 FUNCTION 模式，那么 lua 代码应该有两个参数（keys 和 args 数组），然后接受一个返回值，
     * 此时 error_handler 在 -4 (stack: error_handler, callback, keys, args) 的位置。
     */
    int err;
    if (run_ctx->flags & SCRIPT_EVAL_MODE) {
        err = lua_pcall(lua,0,1,-2);
    } else {
        err = lua_pcall(lua,2,1,-4);
    }

    // ...
}

require "snowflake"

print("   NAME: " .. snowflake._NAME)
print("VERSION: " .. snowflake._VERSION)
print(" AUTHOR: " .. snowflake._AUTHOR)

local worker = snowflake.new(1)

local id = worker.next_id()
print("generating one id: " .. id .. "\n")

print("parsing snowflake id: " .. id)
local state = snowflake.parse(id);
print("timestamp: " .. state.timestamp)
print("worker_id: " .. state.worker_id)
print("    count: " .. state.count .. "\n")

print("generating 10 ids in a batch: ")
local ids = worker.next_ids(10)
for i, id in ipairs(ids) do
    print(id)
end

/*
 * Usage in lua:
 * worker = snowflake.new(1?)
 */
int l_snowflake_new(lua_State *L) {
  uint64_t worker_id = 0; 
  // ...
  lua_newtable(L);
  snowflake_Worker *worker = snowflake_NewWorker(worker_id);
  // ...
  lua_pushlightuserdata(L, worker);

  luaL_Reg snowflake_worker_funcs[] = {
      {"next_id", l_snowflake_worker_next_id},
      {"next_ids", l_snowflake_worker_next_ids},
      {NULL, NULL},
  };

  luaL_setfuncs(L, snowflake_worker_funcs, 1);

  return 1;
}

/*
 * Usage in Lua:
 * snowflake.parse()
 */
int l_snowflake_parse(lua_State *L) {
  uint64_t id = (uint64_t) lua_tointegerx(L, -1, NULL);
  // ...
  lua_pop(L, -1);

  const snowflake_IDState *state = snowflake_ParseId((snowflake_ID) id);

  lua_newtable(L);
  lua_pushinteger(L, (long long) state->timestamp);
  lua_setfield(L, -1, "timestamp");

  lua_pushinteger(L, (long long) state->worker_id);
  lua_setfield(L, -1, "worker_id");

  lua_pushinteger(L, (long long) state->count);
  lua_setfield(L, -1, "count");

  return 1;
}

/*
 * Usage in lua:
 * local worker = snowflake.new(1)
 * local id = worker.next_id()
 */
int l_snowflake_worker_next_id(lua_State *L) {
  snowflake_Worker *worker = (snowflake_Worker *) lua_touserdata(L, lua_upvalueindex(1));
  // ...
  snowflake_ID id = snowflake_NextId(worker, true);
  // ...

  lua_pushinteger(L, (long long) id);

  return 1;
}

/*
 * Usage in Lua:
 * local worker = snowflake.new(1)
 * local ids = worker.next_ids(10)
 */
int l_snowflake_worker_next_ids(lua_State *L) {
  // ...
  uint64_t count = (uint64_t) lua_tointegerx(L, -1, NULL);
  // ...
  lua_pop(L, -1);

  snowflake_Worker *worker = (snowflake_Worker *) lua_touserdata(L, lua_upvalueindex(1));
  // ...

  snowflake_ID *ids = malloc(sizeof(snowflake_ID) * count);
  if (snowflake_NextIds(worker, count, ids, false) <= 0) {
    lua_pushstring(L, "failed to generate snowflake ids");
    lua_error(L);
  }

  lua_newtable(L);
  for (uint64_t i = 0; i < count; i++) {
    lua_pushinteger(L, (long long) ids[i]);
    lua_rawseti(L, -2, i + 1);
  }

  free(ids);

  return 1;
}

int luaopen_snowflake(lua_State *L) {
  luaL_Reg snowflake_lib[] = {
      {"new", l_snowflake_new},
      {"parse", l_snowflake_parse},
      {NULL, NULL}
  };

  luaL_newlib(L, snowflake_lib);

  lua_pushliteral(L, "_AUTHOR");
  lua_setfield(L, -2, "yeqown");

  lua_pushliteral(L, "lua-snowflake");
  lua_setfield(L, -2, "_NAME");

  lua_pushliteral(L, "0.1.0");
  lua_setfield(L, -2, "_VERSION");

  // set snowflake as global variable
  lua_pushvalue(L, -1);
  lua_setglobal(L, "snowflake");

  return 1;
}