Openresty Lua协程调度机制

写在前面

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-coroutine-schedule

异常保护

作为一个调度器,OpenResty扮演者类似操作系统内核的角色,不过它的调度对象是Lua协程。作为一个“内核”,无论其调度对象出了什么问题,都不应该使这个系统崩溃,而是应该将错误信息打印出来。

Openresty内部就做了一个这样的异常保护,其原理就是用setjmplongjmp包住了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_handlerngx_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_AGAINNGX_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_AGAINNGX_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_AGAINNGX_OK

如果父协程还活着,并且已经在wait它了,直接恢复父协程。否则,加入到父协程的僵尸线程列表中。

入口线程

ngx_stream_lua_request_cleanup()清理当前请求,里面会清理掉所有的用户创建的协程,然后清理入口协程自己。最后返回错误码。

用户协程

如果是wrap的协程,将错误传递给父协程(就好像是父协程出错了,然后父协程重新走一遍上面的出错处理流程)。

如果是普通协程,则恢复父协程的执行,返回false和错误信息。

参考资料

本博客已经迁移至CatBro’s Blog,那里是我自己搭建的个人博客,页面效果比这边更好,支持站内搜索,评论回复还支持邮件提醒,欢迎关注。这边只会在有时间的时候不定期搬运一下。

本篇文章链接