写在前面
OpenResty（后面简称：OR）是一个基于Nginx和Lua的高性能Web平台，它内部集成大量的Lua API以及第三方模块，可以利用它快速搭建支持高并发、极具动态性和扩展性的Web应用、Web服务或动态网关。
OR最大的特点就是，将Lua协程与Nginx事件驱动模型及非阻塞I/O结合起来。使用户可以在handler中使用 同步但是依然是非阻塞 的方式编写其应用代码，而无需关心底层的协程调度以及与Nginx事件驱动模型的交互。
本文将先从总体上介绍OR的协程调度机制，然后结合源码以及Lua栈的情况来详细了解各个部分是如何实现的，包括其异常保护、协程初始化、协程的恢复和执行、协程的挂起、协程的执行结束、协程出错的情况。
本文主要关注调度函数内部的逻辑，如果想了解外部的调用流程。可以参看Openresty Lua钩子调用完整流程
注：lua-nginx模块与stream-lua-nginx模块的主体部分类似，后者实现相对简单一点。下面的讨论将基于stream-lua模块。
为了防止歧义，文中用到的一些术语明确一下：
-
主线程：表示外层调用run_thread()的OS线程 -
入口线程：每个handler被调用时会创建一个入口线程，用于执行lua代码 -
用户线程：用户在Lua代码中通过ngx.thread.spawn()创建的线程 -
用户协程：用户在Lua代码中通过coroutine.create()创建的协程 -
协程：泛指所有协程，包括入口线程、用户线程和用户协程 -
vm：表示Lua虚拟机 -
L：视出现的上下文，一般表示父协程，在创建入口线程的时候表示Lua VM -
co：一般表示新创建的协程 -
L栈： |协程表|新协程|顶|：表示Lua栈结构，最右边是栈顶
关键数据结构
在深入了解协程调度机制之前，我们先来认识一下主要的数据结构：
- 协程上下文：
ngx_stream_lua_co_ctx_t- 协程内部栈（
coctx->co） - 协程状态（
coctx->co_status） - 维护协程之间关系的数据（父协程
coctx->parent_co_ctx、僵尸子线程coctx->zombie_child_threads） - 用户相关数据（
coctx->data） - 在Lua的registry表中对应该线程指针的引用值（
co_ref） - 一些状态标记（是否是用户线程
is_uthread、是否因创建新线程thread_spawn_yielded被yield)
- 协程内部栈（
- 模块上下文：
ngx_stream_lua_ctx_t-
ctx->cur_co_ctx（当前调度协程上下文） -
ctx->co_op（协程是以何种方式YIELD）
-
- 核心调度函数：
ngx_stream_lua_run_thread()
协程调度
首先你可能很好奇OR为什么要在C引擎层面自己实现协程的调度？或者说这么做的好处是什么？我觉得最主要的原因还是减轻开发者的负担。
原生Lua coroutine接口
我们知道Lua是个非常轻巧的语言，它不像Go有自己的调度器。Lua原生的对协程的操作无非就是coroutine.resume()和coroutine.yield()。这两者是成对出现的，协程coroutine.yield()之后肯定回到父协程coroutine.resume()的地方，恢复子协程需要显式再次coroutine.resume()。如果要在Lua代码层面实现非阻塞I/O，那么父协程必须处理子协程I/O等待的情况，并在事件发生时恢复子协程的执行。如果需要同时进行多个任务，那么父协程就需要负责多个协程间的调度。因为协程的拓扑可能是一个复杂的树状结构，所以协程的调度管理将变得异常复杂。
OpenResty实现
OR在C引擎层帮我们把这些事情都做了，你无须再关心所有这些，只需专心写你的业务逻辑。为了支持同步非阻塞的方式编写应用代码，OR重写了coroutine的接口函数，从而接管了协程的调度，并在coroutine基础上封装抽象出了thread的概念。无论是coroutine还是thread，I/O等待对于用户都是透明的，用户无需关心。两者的主要区别是，coroutine父子之间的协作度更高，coroutine.yield()和coroutine.resume()成对出现。在子协程执行完成（出错）或者显式coroutine.yield()之前，父协程一直处于等待状态。而thread则由调度器进行调度，子thread一旦开始执行就不再受父协程控制了，在需要并发请求时很有用。thread提供了spawn()、wait()等接口，spawn()执行参数中指定的函数，直到执行完毕、出错或者I/O等待时返回。wait()则使父协程可以同步等待子线程执行完毕、获取结果。
OR在对协程调度上，最核心的改动是其创建新协程时的行为（coroutine.resume(), ngx.thread.spawn()）。它不会直接调用lua_resume()，而是先lua_yield()回到主线程，然后由主线程再根据情况lua_resume()下一个协程。Lua代码域内从来不会直接调用lua_resume()，理解了这一点你就理解了OpenResty协程调度的精髓。
所以OR中协程拓扑是一个单层的结构，它只有一个入口点。这样使得协程调度更加灵活，I/O事件的触发时回调函数也更容易实现。
OR调度器根据lua_resume()的返回值，确定协程是挂起了、结束了还是出错了。因为OR改动了创建新协程时行为，同时又抽象了thread概念，所以如果是协程挂起的情况，还需要知道是什么原因挂起，以便做相应的不同处理。是继续调度？还是返回上层？我们前面提到的ctx->co_op便是做这个用途。
协程的调度在核心调度函数ngx_stream_lua_run_thread()中进行，它是创建或恢复协程的唯一入口点。最初是由配置的Lua钩子调用（图中ssl_cert_handler()），如果碰到了I/O等待的情况，后续则由对应的事件handler（图中的sleep_handler()和read_handler()）再次拉起。run_thread()里面实现了一个调度循环，循环里面先从ctx->cur_co_ctx获取下一个待resume的协程上下文，然后lua_resume()执行或恢复该协程，其返回值LUA_YIELD表示协程挂起，0表示协程执行结束，其余的表示协程出错了。其中协程挂起又分为四种不同的情况：即等待I/O、新建thread、coroutine.resume()和coroutine.yield()。根据不同的情况，决定是跳到循环前面继续恢复下一个协程，还是返回上层函数。
下图是协程调度主要逻辑的示意图，可以看到在Lua代码域中无论是新建、挂起或恢复协程，都是先调用lua_yield()回到主线程。I/O操作例如ngx.tcp.receive()如果碰到了I/O等待，会在内部注册epoll事件（对于sleep的情况是定时器），然后自动lua_yield()，当事件触发时继续未完成的I/O操作，完成之后再调用run_thread()恢复之前被挂起的协程。
异常保护
作为一个调度器，OpenResty扮演者类似操作系统内核的角色，不过它的调度对象是Lua协程。作为一个“内核”，无论其调度对象出了什么问题，都不应该使这个系统崩溃，而是应该将错误信息打印出来。
Openresty内部就做了一个这样的异常保护，其原理就是用setjmp、longjmp包住了run_thread()里面的整个协程调度逻辑。
/* 首先注册虚拟机的panic回调 */
lua_atpanic(L, ngx_stream_lua_atpanic);
/* setjmp保存环境 */
NGX_LUA_EXCEPTION_TRY {
/* 执行调度逻辑 */
} NGX_LUA_EXCEPTION_CATCH {
/* 出现异常时走到这里 */
dd("nginx execution restored");
}
ngx_stream_lua_atpanic()的实现也非常简单，只是简单地打印崩溃日志，然后调用NGX_LUA_EXCEPTION_THROW(1);恢复nginx的执行。
int
ngx_stream_lua_atpanic(lua_State *L)
{
#ifdef NGX_LUA_ABORT_AT_PANIC
abort();
#else
u_char *s = NULL;
size_t len = 0;
if (lua_type(L, -1) == LUA_TSTRING) {
s = (u_char *) lua_tolstring(L, -1, &len);
}
if (s == NULL) {
s = (u_char *) "unknown reason";
len = sizeof("unknown reason") - 1;
}
ngx_log_stderr(0, "lua atpanic: Lua VM crashed, reason: %*s", len, s);
ngx_quit = 1;
/* restore nginx execution */
NGX_LUA_EXCEPTION_THROW(1);
/* impossible to reach here */
#endif
}
这几个宏定义分别如下：
#define NGX_LUA_EXCEPTION_TRY \
if (setjmp(ngx_stream_lua_exception) == 0)
#define NGX_LUA_EXCEPTION_CATCH \
else
#define NGX_LUA_EXCEPTION_THROW(x) \
longjmp(ngx_stream_lua_exception, (x))
协程初始化
钩子的入口线程
ngx_stream_lua_new_thread()用于创建入口线程
OR中需要在Registry表中存储每个创建出来的Lua线程的reference，这个存储协程的表在Registry表中对应的key是全局变量ngx_stream_lua_coroutines_key的地址，因此下面这段代码就是从Registry表中查询这个储存协程的表，返回到栈顶：
/* 返回栈顶元素的索引，等于栈中元素的个数 */
base = lua_gettop(L);
/* 将存储协程的表对应的key压栈 */
lua_pushlightuserdata(L, ngx_stream_lua_lightudata_mask(
coroutines_key));
/* 将key出栈，获取Registry表中key对应的元素，然后将结果入栈 */
lua_rawget(L, LUA_REGISTRYINDEX);
接下来创建一个新的协程，同时初始化其全局表：
/* 创建Lua协程，返回的新lua_State跟原有的lua_State共享所有的全局对象（如表），
但是有一个独立的执行栈。 协程依赖垃圾回收销毁 */
/* L栈： |协程表|新协程|顶| */
co = lua_newthread(L);
/* 创建该协程的全局表，设置_G field为全局表自己 */
/* L栈： |协程表|新协程|协程新的全局表|顶| */
ngx_stream_lua_create_new_globals_table(co, 0, 0);
/* 再创建一个新表 */
/* L栈： |协程表|新协程|协程新的全局表|新表|顶| */
lua_createtable(co, 0, 1);
/* 拿到全局表 */
/* L栈： |协程表|新协程|协程新的全局表|新表|旧全局表|顶| */
ngx_stream_lua_get_globals_table(co);
/* 新表的__index的值为栈顶的值，也即就全局表 */
/* L栈： |协程表|新协程|协程新的全局表|新表|顶| */
lua_setfield(co, -2, "__index");
/* 新表出栈，将其设为索引-2处即协程新的全局表的元表 */
/* L栈： |协程表|新协程|协程新的全局表|顶| */
lua_setmetatable(co, -2);
/* 设置协程新的全局表到对应索引，其_G field是自己，
其元表是新表，新表的__index是父协程的全局表 */
/* L栈： |协程表|新协程|顶| */
ngx_stream_lua_set_globals_table(co);
这一块的逻辑有点绕，我们来稍微理一下，其实就是用新建的全局表替换了旧的全局表，其中新的全局表的_G字段是它自己，新全局表的元表中__index元方法是旧的全局表。
此时的Lua虚拟机栈顶情况如下图所示：
L->top | 栈顶 |
L->top - 1 |Lua_State*| 新创建的协程
L->top -2 | Lua Table| 存储协程引用的表
下面一步就是在Lua虚拟机中为这个新协程创建一个reference：
/* 为栈顶对象（即新协程），创建并返回一个协程表中的引用 */
/* 当前栈： |协程表|顶| */
*ref = luaL_ref(L, -2);
if (*ref == LUA_NOREF) {
lua_settop(L, base); /* restore main thread stack */
return NULL;
}
最后恢复堆栈
/* 设置栈顶索引 */
/* 当前栈： |顶| */
lua_settop(L, base);
return co;
以上步骤还只是创建了一个什么都不能做的Lua协程，回到_by_chunk()函数之后还需要把入口函数放入协程中。
/* 将lua虚拟机VM栈上的入口函数闭包移到新创建的协程栈上，
这样新协程就有了虚拟机已经解析完毕的代码了。*/
lua_xmove(L, co, 1);
/* 拿到co全局表，放到栈顶 */
/* 当前栈： |入口closure|全局表|顶| */
ngx_stream_lua_get_globals_table(co);
/* 将全局表设为入口closure的环境表 */
/* 当前栈： |入口closure|顶|*/
lua_setfenv(co, -2);
至此，协程入口函数以及环境表已经设置好。接下来就是让它能够运行起来，让调度器能够调度它运行：
/* 将nginx请求保存到协程全局表 */
ngx_stream_lua_set_req(co, r);
ctx->cur_co_ctx = &ctx->entry_co_ctx;
ctx->cur_co_ctx->co = co;
ctx->cur_co_ctx->co_ref = co_ref;
接下来就是注册cleanup钩子，然后ngx_stream_lua_run_thread()。
用户创建的uthread
用户线程由ngx.thread.spawn()创建，对应的C实现是ngx_stream_lua_uthread_spawn()。首先它会调ngx_stream_lua_coroutine_create_helper()创建一个新的协程。
创建协程
注意协程都是在worker的虚拟机上创建的（不考虑cache off的情况的话）。但是用户协程会继承父协程的全局表，其父子关系由OR进行维护。
/* 获取虚拟机 */
vm = ngx_stream_lua_get_lua_vm(r, ctx);
/* 创建新协程 */
co = lua_newthread(vm);
/* 然后创建coctx，设置其co、co_status值 */
coctx = ngx_stream_lua_create_co_ctx;
coctx->co = co;
coctx->co_status = NGX_STREAM_LUA_CO_SUSPENDED;
此时父协程的栈如下:
/* 当前栈: |entry_func|args|顶| */
接下来将父协程的全局表给新创建的协程：
/* make new coroutine share globals of the parent coroutine.
* NOTE: globals don't have to be separated! */
/* 拷贝父协程的全局表到栈上 */
/* L栈: |entry_func|args|全局表|顶| */
ngx_stream_lua_get_globals_table(L);
/* 将全局表移动到新创建的协程co的栈上 */
/* L栈: |entry_func|args|顶| */
lua_xmove(L, co, 1);
/* 从新协程栈上写入其的全局表 */
ngx_stream_lua_set_globals_table(co);
/* 将新协程从进程虚拟机，移动到父协程中 */
/* L栈: |entry_func|args|新协程|顶| */
lua_xmove(vm, L, 1);
/* 入口函数拷贝到L栈顶 */
/* L栈: |entry_func|args|新协程|entry_func|顶|*/
lua_pushvalue(L, 1);
/* 将入口函数从L移到co栈中 */
/* L栈: |entry_func|args|新协程|顶| */
/* co栈: |entry_func|顶|*/
lua_xmove(L, co, 1);
create_helper函数返回之后，L的栈顶是新协程，co的栈顶是入口函数。
初始化uthread
ngx_stream_lua_coroutine_create_helper返回之后，进行uthread的初始化。
此时，父协程L是这样的：
- 栈顶是新创建的协程
- 然后是参数和入口函数
在此之前，先在registry表中保存一个该协程的ref。（到现在还没搞明白这个ref是干嘛用的？除了创建线程和删除线程，貌似只有检查线程是否活着的时候会查一下这个ref，只是检查状态用coctx->co_status不是也能做到么？8.12更新，之所以要把线程锚定到注册表上，是为了防止被当成垃圾回收。这也解释了为什么只有线程需要锚定到注册表上，而用户协程不需要。因为用户协程肯定由其父协程保留着一个引用。）
/* anchor the newly created coroutine into the Lua registry */
/* 把新创建的协程写入Lua registry表中 */
/* 将ngx_stream_lua_coroutines_key的地址压入栈中 */
lua_pushlightuserdata(L, &ngx_stream_lua_coroutines_key);
/* 从registry表中获取协程表 */
/* L栈: |entry_func|args|新协程|协程表|顶|*/
lua_rawget(L, LUA_REGISTRYINDEX);
/* 将新协程压栈 */
/* L栈: |entry_func|args|新协程|协程表|新协程|顶|*/
lua_pushvalue(L, -2);
/* -2位置是注册表，为新协程创建在报表中的索引 */
/* L栈: |entry_func|args|新协程|协程表|顶| */
coctx->co_ref = luaL_ref(L, -2); //
/* 弹出协程表 */
/* L栈: |entry_func|args|新协程|顶| */
lua_pop(L, 1);
接下来是初始化运行环境：
此时的，L的栈情况如下：
|entry_func|参数1|...|参数n|新协程|
1 2 ... -2 -1
if (n > 1) {
/* 由于lua函数压栈顺序是从左到右
* 因此1就是压入的第一个参数，而spawn的第一个参数就是入口函数
* 把栈顶元素（即新协程）移动到1，覆盖入口函数，入口函数前面已经拷贝到新协程栈上了
*/
/* L栈: |新协程|args|顶| */
lua_replace(L, 1);
/* 将参数移到新协程栈中 */
/* L栈: |新协程|顶|*/
/* co栈: |入口函数|args|顶| */
lua_xmove(L, coctx->co, n - 1);
}
设置状态，将父协程放入post_thread队列中，设置协程的父子关系，设置新协程为下一个调度的线程
/* 设置状态 */
coctx->co_status = NGX_STREAM_LUA_CO_RUNNING;
ctx->co_op = NGX_STREAM_LUA_USER_THREAD_RESUME;
ctx->cur_co_ctx->thread_spawn_yielded = 1;
/* 将父协程放入post_thread队列中 */
ngx_stream_lua_post_thread(r, ctx, ctx->cur_co_ctx)
/* 保存子线程的父协程上下文为当前协程 */
coctx->parent_co_ctx = ctx->cur_co_ctx;
/* 切换当前协程为新创建的协程 */
ctx->cur_co_ctx = coctx;
最后，spawn函数的返回值是新创建的协程
/* 将原协程的执行权切换出去，这里的参数1表示栈上留了一个值，这里是指新创建的协程
* 主线程并不会取这个值，而是等到新线程spawn返回时作为返回值。
* 此时L栈中是新协程，co栈中是参数和入口函数。
*/
return lua_yield(L, 1);
用户创建的coroutine
OR替换了原生的coroutine接口，当存在getfenv(0).__ngx_req时（全局环境保存了nginx请求），使用重写后的coroutine接口函数。
coroutine.create()创建新协程部分跟uthread是一样的，都是调用ngx_stream_lua_coroutine_create_helper()。Lua函数返回新协程。此时新协程栈中是入口函数。
coroutine.resume()用于开始或恢复新协程，其对应的C函数是ngx_http_lua_coroutine_resume()。
/* 首先，获取到协程 */
/* L栈: |co|参数|, co栈: |入口函数| */
co = lua_tothread(L, 1);
/* 然后设置状态和父子关系 */
/* 父协程为normal */
p_coctx->co_status = NGX_HTTP_LUA_CO_NORMAL;
coctx->parent_co_ctx = p_coctx;
dd("set coroutine to running");
/* 子协程为running */
coctx->co_status = NGX_HTTP_LUA_CO_RUNNING;
/* 设置co_op告知主线程yield类型 */
ctx->co_op = NGX_HTTP_LUA_USER_CORO_RESUME;
/* 设置下一个调度协程为新协程 */
ctx->cur_co_ctx = coctx;
接下来，将控制权交还给主协程，并把参数传给主线程。
/* 此时L栈: |co|参数|， co栈: |入口函数| */
/* lua_gettop(L) - 1表示留在栈中的返回值个数，
* 由主线程取用之后，在lua_resume新协程时传递 */
/* 减一个，表示不传底下的co */
return lua_yield(L, lua_gettop(L) - 1);
协程执行和恢复
OR中协程的执行和恢复总是由主线程来进行，不管是coroutine.resume()还是ngx.thread.spawn()，都是先lua_yield()回到主线程之后，在主线程中lua_resume()。
注意到前面创建阶段，thread是lua_yield(L, 1)，coroutine是lua_yield(L, lua_gettop(L) - 1)。yield到主线程之后，我们继续看调度程序的处理。
uthread
先获取参数个数
/* 因为入口函数和参数已经在新线程栈中了,所以从新协程中获取参数个数，-1是除掉入口函数 */
nrets = lua_gettop(ctx->cur_co_ctx->co) - 1;
然后跳到主循环的前面，执行新线程
/* 保存新协程coctx */
orig_coctx = ctx->cur_co_ctx;
/* 执行新线程，其中nrets为参数个数 */
rv = lua_resume(orig_coctx->co, nrets);
在lua_resume中就会开始新线程的执行。当新线程执行完毕或因I/O中断yield之后，会恢复父协程。在恢复父协程之前，先设置参数个数为1，即之前留在栈上的新协程co。恢复父协程之后，ngx.thread.spawn()函数就返回了。
if (ctx->cur_co_ctx->thread_spawn_yielded) {
ctx->cur_co_ctx->thread_spawn_yielded = 0;
nrets = 1;
}
coroutine
同样是先获取参数个数
/* 获取父协程 */
old_co = ctx->cur_co_ctx->parent_co_ctx->co;
/* 因为参数还在父协程栈中，所以从父协程栈中获取参数个数 */
nrets = lua_gettop(old_co);
if (nrets) {
/* 将参数从父协程移到子协程 */
lua_xmove(old_co, ctx->cur_co_ctx->co, nrets);
}
此时子协程栈中是参数和入口函数。
然后跳到主循环的前面，执行新协程，跟前面uthread时一样。
协程挂起
协程的挂起分为两种情况：
- 一种是内部在I/O等待时自动挂起，这种情况用户不用参与，OR会自动将相应的事件及其handler挂到事件驱动上，当事件被唤醒时继续未完成的I/O操作，完成之后由调度器恢复之前挂起的协程。
- 另一种是用户在Lua代码主动调用
coroutine.yield()挂起。此时由调度器根据情况决定执行下一个执行的协程。
显式主动挂起
我们先来看用户主动挂起的情况，coroutine.yield()对应的C函数为ngx_stream_lua_coroutine_yield()。我们先来看看它里面干了些什么。
/* 首先修改当前协程的状态为挂起 */
coctx = ctx->cur_co_ctx;
coctx->co_status = NGX_STREAM_LUA_CO_SUSPENDED;
/* 设置co_op */
ctx->co_op = NGX_STREAM_LUA_USER_CORO_YIELD;
/* 如果不是用户线程（也即是普通coroutine），且有父协程，
将其父协程状态设置为running */
if (!coctx->is_uthread && coctx->parent_co_ctx) {
coctx->parent_co_ctx->co_status = NGX_STREAM_LUA_CO_RUNNING;
}
/* 最后将控制权交还主线程，将所有yield参数传递给主线程 */
return lua_yield(L, lua_gettop(L));
回到主线程之后，根据待挂起协程是thread还是corotine进行不同处理。
thread
if (ngx_stream_lua_is_thread(ctx)) {
/* 丢弃coroutine.yield()的任何参数 */
lua_settop(ctx->cur_co_ctx->co, 0);
/* 因为thread由调度器负责调度，所以将当前线程的状态改为running，为什么不在前面一起改？*/
ctx->cur_co_ctx->co_status = NGX_STREAM_LUA_CO_RUNNING;
/* 如果已经有pending的线程，则放到队列中 */
if (ctx->posted_threads) {
ngx_stream_lua_post_thread(r, ctx, ctx->cur_co_ctx);
ctx->cur_co_ctx = NULL;
return NULL;
}
/* 否则，立即恢复线程 */
}
coroutine
/* 获取当前栈的高度，也即coroutine.yield()的参数个数 */
nrets = lua_gettop(ctx->cur_co_ctx->co);
/* 设置父协程为下一个调度的协程 */
next_coctx = ctx->cur_co_ctx->parent_co_ctx;
next_co = next_coctx->co;
/* 将参数从子协程栈中移到父协程栈中 */
if (nrets) {
dd("moving %d return values to next co", nrets);
lua_xmove(ctx->cur_co_ctx->co, next_co, nrets);
#ifdef NGX_LUA_USE_ASSERT
ctx->cur_co_ctx->co_top -= nrets;
#endif
}
/* 如果不是wrap封装的，还要加一个true，作为第一个参数 */
if (!ctx->cur_co_ctx->is_wrap) {
/* prepare return values for coroutine.resume
* (true plus any retvals)
*/
lua_pushboolean(next_co, 1);
/* 插入1的位置，作为第一个参数 */
lua_insert(next_co, 1);
nrets++; /* add the true boolean value */
}
ctx->cur_co_ctx = next_coctx;
/* 回到主循环的前面，resume父协程 */
break;
I/O等待场景
I/O等待的场景有很多，不过其背后的原理都差不多：
- 定义一个事件，设置恢复时的handler及对应协程上下文，然后
lua_yield()回到run_thread()。 - 主线程将
ctx->cur_co_ctx设为空之后，直接返回NGX_AGAIN，如果有posted_thread会继续执行，否则将控制权交还给nginx层 - 后续当事件发生时，继续未完成的操作，完成之后将保存的协程上下文设为
ctx->cur_co_ctx，然后调用ngx_stream_lua_run_thread()恢复协程的执行。
这里举两个典型的例子:
ngx.sleep()
它的C函数实现是ngx_stream_lua_ngx_sleep()，先定义设置好handler和coctx，挂上定时器，然后lua_yield()
ngx_stream_lua_cleanup_pending_operation(coctx);
coctx->cleanup = ngx_stream_lua_sleep_cleanup;
coctx->data = r;
/* 保存恢复时的handler和协程上下文 */
coctx->sleep.handler = ngx_stream_lua_sleep_handler;
coctx->sleep.data = coctx;
coctx->sleep.log = r->connection->log;
/* 当delay为0时，放入post_event队列或添加定时器 */
if (delay == 0) {
#ifdef HAVE_POSTED_DELAYED_EVENTS_PATCH
dd("posting 0 sec sleep event to head of delayed queue");
coctx->sleep.delayed = 1;
ngx_post_event(&coctx->sleep, &ngx_posted_delayed_events);
#else
ngx_log_error(NGX_LOG_WARN, r->connection->log, 0, "ngx.sleep(0)"
" called without delayed events patch, this will"
" hurt performance");
ngx_add_timer(&coctx->sleep, (ngx_msec_t) delay);
#endif
} else { /* 添加定时器 */
ngx_add_timer(&coctx->sleep, (ngx_msec_t) delay);
}
/* 外层函数*/
return lua_yield(L, 0);
在run_thread()里将当前协程上下文置为NULL，然后返回NGX_AGAIN
在by_chunk()里会先检查有没有在post队列里的线程，如果没有则返回
rc = ngx_stream_lua_run_thread(L, r, ctx, 0);
if (rc == NGX_ERROR || rc >= NGX_OK) {
/* do nothing */
} else if (rc == NGX_AGAIN) {
rc = ngx_stream_lua_content_run_posted_threads(L, r, ctx, 0);
} else if (rc == NGX_DONE) { /* 这里DONE的情况只有HTTP子请求的时候会出现 */
rc = ngx_stream_lua_content_run_posted_threads(L, r, ctx, 1);
} else {
rc = NGX_OK;
}
当定时器超时时，它会执行sleep_handler()，设置ctx->cur_co_ctx然后执行run_thread()恢复协程调度。
ngx.tcp.receive()
其对应的C函数实现是ngx_stream_lua_socket_tcp_receive()，里面会调ngx_stream_lua_socket_tcp_receive_helper()。碰到读等待的情况，也是先设置好handler和coctx，然后lua_yield()。我们来看下里面代码：
/* 这里0表示还未进行协程切换 */
u->read_waiting = 0;
u->read_co_ctx = NULL;
/* 读取的主要逻辑由此函数处理 */
rc = ngx_stream_lua_socket_tcp_read(r, u);
/* 不管是成功、出错或等待I/O，肯定会返回 */
if(rc == NGX_ERROR) {
/*...*/
}
if(rc == NGX_OK) {
/*...*/
}
/* rc == NGX_AGAIN */
/* 如果是等待I/O的情况，设置事件触发时的handler、当前协程上下文 */
u->read_event_handler = ngx_stream_lua_socket_read_handler;
coctx = lctx->cur_co_ctx;
/* 设置请求的写事件handler，这个是返回到Lua层前调用的handler */
r->write_event_handler = ngx_stream_lua_content_wev_handler;
/* 保存当前协程上下文到u上 */
u->read_co_ctx = coctx;
/* 表示是后续是需要协程恢复的 */
u->read_waiting = 1;
/* 设置准备返回值的回调 */
u->read_prepare_retvals = ngx_stream_lua_socket_tcp_receive_retval_handler;
return lua_yield(L, 0);
回到run_thread()，同样是将当前协程上下文置为NULL，然后返回NGX_AGAIN。
当事件被触发时，执行前面设置的ngx_stream_lua_socket_read_handler()，里面又会调用读取操作核心函数ngx_stream_lua_socket_tcp_read()。如果继续碰到等待I/O，handler直接结束，等待下一次事件。如果是完成或出错，会执行如下操作：
/* 恢复该值为0 */
u->read_waiting = 0;
/* 获取协程上下文 */
coctx = u->read_co_ctx;
/* 设置协程恢复的handler */
ctx->resume_handler = ngx_stream_lua_socket_tcp_read_resume;
/* 设置下一个调度的上下文，为之前调用读取操作的协程 */
ctx->cur_co_ctx = coctx;
/* 这个handler就是yield之前设置的那个，它里面调用 ctx->resume_handler */
r->write_event_handler(r);
r->write_event_handler(r);是返回Lua层前调用的handler，里面会调用resume_handler。ngx_stream_lua_socket_tcp_read_resume()只是封装了一下，最终都是调用的ngx_stream_lua_socket_tcp_resume_helper()，我们看来下它的代码：
/* 待恢复协程上下文 */
coctx = ctx->cur_co_ctx;
u = coctx->data;
prepare_retvals = u->read_prepare_retvals;
/* 准备返回值 */
nret = prepare_retvals(r, u, ctx->cur_co_ctx->co);
/* 恢复协程调度，回到Lua层 */
rc = ngx_stream_lua_run_thread(vm, r, ctx, nret);
至于完成的条件，取决与不同的调用方式。如果是读取固定字节数的话，会维护一个剩余待读取的字节数u->rest。如果是读取一行，则读取到\n就结束。如果是readall，则一直读到u->eof为止。
协程执行完毕
为了不失完整性，再说一下正常结束和出错时的情况。正常执行完毕时，会设置协程状态，然后清理它的僵尸子线程：
/* 将当前协程状态置为DEAD */
ctx->cur_co_ctx->co_status = NGX_STREAM_LUA_CO_DEAD;
/* 如果子线程有僵尸线程，则清理之 */
if (ctx->cur_co_ctx->zombie_child_threads) {
ngx_stream_lua_cleanup_zombie_child_uthreads(
r, L, ctx, ctx->cur_co_ctx);
}
接下来，根据结束的协程的类型不同执行不同的操作：
入口线程
此时直接删除线程即可，然后根据是否还有用户线程，选择返回NGX_AGAIN或NGX_OK
if (ngx_stream_lua_is_entry_thread(ctx)) {
/* 将虚拟机栈清空 */
lua_settop(L, 0);
/* 删除当前线程，会从REGISTY表中解引用当前协程的`coctx->co_ref` */
ngx_stream_lua_del_thread(r, L, ctx, ctx->cur_co_ctx);
/* 如果还有其他用户线程，返回NGX_AGAIN */
if (ctx->uthreads) {
ctx->cur_co_ctx = NULL;
return NGX_AGAIN;
}
/* all user threads terminated already */
goto done; /* 到这就圆满结束了 return NGX_OK; */
}
用户线程
此时如果父协程已经死了，处理方式跟入口线程一样，即删除线程，然后根据是否还有任何用户线程或入口线程，选择返回NGX_AGAIN或NGX_OK。
如果父协程还活着，并且已经在wait它了，直接恢复父协程。否则，加入到父协程的僵尸线程列表中。
if (ctx->cur_co_ctx->is_uthread) {
/* 清空虚拟机栈 */
lua_settop(L, 0);
/* 获取父协程 */
parent_coctx = ctx->cur_co_ctx->parent_co_ctx;
/* 如果父协程还活着 */
if (ngx_stream_lua_coroutine_alive(parent_coctx)) {
/* 并且在wait当前线程，则恢复父协程 */
if (ctx->cur_co_ctx->waited_by_parent) {
ngx_stream_lua_probe_info("parent already waiting");
ctx->cur_co_ctx->waited_by_parent = 0;
success = 1;
goto user_co_done;
}
/* 否则将当前线程挂到父协程的僵尸子线程中 */
if (ngx_stream_lua_post_zombie_thread(r, parent_coctx,
ctx->cur_co_ctx)
!= NGX_OK)
{
return NGX_ERROR;
}
/* 压入第一个返回值true，以备后续wait时返回 */
lua_pushboolean(ctx->cur_co_ctx->co, 1);
lua_insert(ctx->cur_co_ctx->co, 1);
/* 设置当前线程状态为ZOMBIE */
ctx->cur_co_ctx->co_status = NGX_STREAM_LUA_CO_ZOMBIE;
ctx->cur_co_ctx = NULL;
return NGX_AGAIN; /* 返回上层 */
}
/* 如果父协程已经死了，直接删除当前线程
* 会从REGISTY表中解引用当前协程的`coctx->co_ref` */
ngx_stream_lua_del_thread(r, L, ctx, ctx->cur_co_ctx);
ctx->uthreads--;
/* 如果没有用户线程了 */
if (ctx->uthreads == 0) {
/* 入口线程在活着，返回上层 */
if (ngx_stream_lua_entry_thread_alive(ctx)) {
ctx->cur_co_ctx = NULL;
return NGX_AGAIN;
}
/* all threads terminated already */
goto done; /* 到这就圆满结束了 return NGX_OK; */
}
/* 如果还有其他用户线程，返回上层 */
ctx->cur_co_ctx = NULL;
return NGX_AGAIN;
}
用户协程
剩下的就是用户协程的情况，这个情况跟用户线程被父协程wait的情况是一样的。主要是将返回值移动到父协程栈中，然后跳到主循环前面恢复父协程的执行。
success = 1;
/* 获取返回值个数 */
nrets = lua_gettop(ctx->cur_co_ctx->co);
next_coctx = ctx->cur_co_ctx->parent_co_ctx;
next_co = next_coctx->co;
/* 将返回值移到父协程栈中 */
if (nrets) {
lua_xmove(ctx->cur_co_ctx->co, next_co, nrets);
}
/* 如果是用户线程，删除之 */
if (ctx->cur_co_ctx->is_uthread) {
ngx_stream_lua_del_thread(r, L, ctx, ctx->cur_co_ctx);
ctx->uthreads--;
}
/* 除了wrap的用户协程，加上第一个true的返回值 */
if (!ctx->cur_co_ctx->is_wrap) {
/* ended successfully, coroutine.resume returns true plus
* any return values
*/
lua_pushboolean(next_co, success);
lua_insert(next_co, 1);
nrets++;
}
/* 设置父协程的状态为RUNNING */
ctx->cur_co_ctx = next_coctx;
next_coctx->co_status = NGX_STREAM_LUA_CO_RUNNING;
/* 回到主循环前面，恢复父协程的执行 */
continue;
出错的情况
大致处理步骤是，恢复cur_co_ctx，获取虚拟机L栈上错误信息，获取当前协程栈中错误信息，后面的操作类似协程执行完毕时，根据不同的情况选择恢复父协程或者返回上层。
/* 恢复cur_co_ctx */
if (ctx->cur_co_ctx != orig_coctx) {
ctx->cur_co_ctx = orig_coctx;
}
/* 设置当前协程状态为DEAD */
ctx->cur_co_ctx->co_status = NGX_HTTP_LUA_CO_DEAD;
/* 获取错误信息 */
if (orig_coctx->is_uthread
|| orig_coctx->is_wrap
|| ngx_http_lua_is_entry_thread(ctx))
{
ngx_http_lua_thread_traceback(L, orig_coctx->co, orig_coctx);
trace = lua_tostring(L, -1);
if (lua_isstring(orig_coctx->co, -1)) {
msg = lua_tostring(orig_coctx->co, -1);
dd("user custom error msg: %s", msg);
} else {
msg = "unknown reason";
}
}
用户线程
跟正常结束的处理一样，除了第一个返回值是false。
此时如果父协程已经死了，直接删除线程，然后根据是否还有任何用户线程或入口线程，选择返回NGX_AGAIN或NGX_OK。
如果父协程还活着，并且已经在wait它了，直接恢复父协程。否则，加入到父协程的僵尸线程列表中。
入口线程
ngx_stream_lua_request_cleanup()清理当前请求，里面会清理掉所有的用户创建的协程，然后清理入口协程自己。最后返回错误码。
用户协程
如果是wrap的协程，将错误传递给父协程（就好像是父协程出错了，然后父协程重新走一遍上面的出错处理流程）。
如果是普通协程，则恢复父协程的执行，返回false和错误信息。
参考资料
本博客已经迁移至CatBro's Blog，那里是我自己搭建的个人博客，页面效果比这边更好，支持站内搜索，评论回复还支持邮件提醒，欢迎关注。这边只会在有时间的时候不定期搬运一下。