Server 对象由应用程序创建并初始化到 Base 对象中运行。当服务器结束或当其从属的 Base 对象销毁时，可配置自动销毁 Server 对象。
Session 对象由处于会话模式（session mode）的 Server 对象自动创建，并调用应用程序指定的程序入口运行；当会话结束时（函数调用 return）或其从属的 Server 对象服务结束时，由 Server 对象自动销毁。

Client 对象由应用程序调用 Procedure 对象的接口创建，用于与第三方服务交互。应用程序可提前调用接口要求销毁 Client 对象，也可以待 Procedure 服务结束时自动统一销毁。

Base 和 Event 类

Base 类用于运行 libcoevent 的各个服务。每个 Base 类的实例应对应着一个线程，所有的服务以协程的方式在 Base 实例中运行。从上图可知，Base 类包含一个 libevent 库的 event_base 对象和本协程库的一系列 Event 对象。

Event 类其实是借用了 libevent 的 struct event 名称，因为每一个 Event 类的实例，对应着 libevent 的一个 event 对象。我们需要关注的重点，是 Procedure 和 Client 类。

Procedure 类

Procedure 类有两个关键特点：

每个对象都拥有一个 libco 协程，即拥有自己独立的上下文信息，可以用于编写一个独立的服务器过程（procedure）；
Procesure 的子类可以创建 Client 对象与第三方服务器通信和交互。

Procedure 类拥有两个子类，分别是 Server 和 Session。

Server 类

Server 类由应用程序创建并初始化到 Base 对象中运行。Server 类有三个子类：

SubRoutine：实际上不作为任何服务器程序，但提供了最基本的 sleep() 函数，并支持 Procedure 类的创建 Client 对象的功能，因此应用程序可以用来作为临时创建或常驻的内部程序来使用。
UDPServer：应用程序创建并初始化 UDPServer 对象后，程序会自动绑定到一个数据报 socket 接口上。应用可以通过在网络接口中收发数据包来实现网络服务。UDPServer 同时提供普通模式和会话模式。
TCPServer：应用程序创建并初始化 TCPPServer 对象后，程序会自动绑定并监听流 socket。TCPServer 只支持会话模式。

所谓的 “普通模式”，也就是应用程序注册 Server 对象的入口函数，并且由应用程序操作 Server 对象的行为。

所谓的 “会话模式”，指的是 UDPServer 或 TCPServer 对象，在接收到传入数据后，自动区分客户端，并单独创建 Session 对象进行处理。每个 Session 对象只服务于一个客户端。

Session 类

Session 对象不能由应用主动创建，而是由处于会话模式的 Server 类自动按需创建。Session 对象的特点是，只能与单一一个客户端（相比起 UDPServer 对象而言）进行通信，因此没有 send() 函数，只有 reply() 。

在头文件 coevent.h 声明的 Session 类及其子类均为纯虚类，目的是防止应用程序显式地构建 Session 对象并隐藏实现细节。

Client 类

Client 对象由 Procedure 对象创建，并且由 Procedure 对象进行回收。Client 对象的作用是主动向远程服务器发起通信。由于从客户-服务结构的角度，这个动作属于客户端，所以命名为 Client。

DNSClient

Client 的子类中比较特别的是 DNSClient 类，这个类的存在是为了解决在异步 I/O 中的 getaddrinfo() 阻塞问题。DNSClient 的实现原理请参见代码和我之前的文章《DNS 报文结构和个人 DNS 解析代码实现》。

而对于 DNSClient 类而言，具体实现原理，就是封装了一个 UDPClient 对象，通过该对象完成 DNS 报文的收发，并在类中实现报文的解析。

UDPServer——基于 libevent 的协程实现

UDPServer 类普通模式的原理，就是一个非常典型的基于 libevent 的同步协程服务器框架。其代码实现中，核心功能就是以下几个函数：

_libco_routine()，协程的入口函数，使用这个函数，转化成为 liboevent 的统一服务入口函数
_libevent_callback()，libevent 时间回调函数，在这个函数里，实现协程上下文的恢复。
UDPServer::recv_in_timeval()，数据接收函数，在这个函数中，实现关键的数据等待功能，同时实现了协程上下文的保存

上述三个函数的代码总量，加上空行也不超过 200 行，我相信还是很容易看明白的。以下具体解释实现原理：

libco 协程接口

正如前文所说，我使用的是 libco 作为协程库。协程对于应用程序是透明的，但是对于库的实现而言，这才是核心。

下面解释一下 libco 的协程功能所提供的几个接口（libco 的文档数量简直 “感人”，这也是网上经常被吐槽的……）：

创建和销毁协程

Libco 使用结构体 struct stCoRoutine_t * 保存协程，通过调用 co_create() 可以创建协程对象；使用 co_release() 销毁协程资源。

进入协程

创建了协程之后，调用 co_resume() 可以从协程函数的开头开始执行协程。

暂停协程

当协程到了需要交出 CPU 使用权的时候，可以调用 co_yield() 释放协程、切换掉上下文。调用之后，上下文会恢复到上一个调用 co_resume() 的协程中。调用 co_yield() 的位置可以视为一个 “断点”。

恢复协程

恢复协程和创建协程所用的函数都是 co_resume()，调用该函数，将当前堆栈切换为指定协程的上下文，协程会从上文提到的 “断点” 恢复执行。

协程调度实现

从上一小节可以看到，我们使用到的 libco 协程功能函数中，虽然包含了协程的切换函数，但什么时候切换、切换之后 CPU 如何分配，这是我们需要实现并封装起来的工作。

创建和销毁协程的时机，自然就是在 UDPServer 类初始化和析构的时候。下文重点解析进入、暂停和恢复协程的操作：

进入协程

进入 / 恢复协程的代码，是在 _libevent_callback() 中，有这么一行：

// handle control to user application
co_resume(arg->coroutine);

登录后复制

如果当前协程还没有被执行过，那么执行了这句代码之后，程序会切换到创建 libco 协程时指定的协程函数开始执行。对于 UDPServer，也就是 _libco_routine() 函数。这个函数非常简单，只有三行：

static void *_libco_routine(void *libco_arg)
{
    struct _EventArg *arg = (struct _EventArg *)libco_arg;
    (arg->worker_func)(arg->fd, arg->event, arg->user_arg);
    return NULL;
}

登录后复制

通过传入参数，将 libco 回调函数转换为应用程序指定的服务器函数执行。

但是如何实现第一次的 libevent 回调呢？这还是很简单的，只需要在调用 libevent 的 event_add()时，将超时时间设置为 0 即可，这会导致 libevent 事件立即超时。通过这个机制，我们也就实现了在 Base 运行之后立即执行各 Procedure 服务函数的目的。

暂停和恢复协程

在什么时候调用 co_yield是本协程实现的重点，调用 co_yield 的位置，是一个可能会导致上下文切换的地方，也是将异步编程框架转换为同步框架的关键技术点。这里可以参照 UDPServer 的 recv_in_timeval() 函数。函数的基本逻辑如下：

其中最重要的分支，就是对 libevent 事件标志的判断；而最重要的逻辑，就是 event_add() 和 co_yield() 函数的调用。函数片段如下：

struct timeval timeout_copy;
timeout_copy.tv_sec = timeout.tv_sec;
timeout_copy.tv_usec = timeout.tv_usec;
    ...
event_add(_event, &timeout_copy);
co_yield(arg->coroutine);

登录后复制

这里，我们把 co_yield() 函数理解为一个断点，当程序执行到这里的时候，CPU 的使用权会被交出，程序回到调用 co_resume() 的上一级函数手中。这个 “上一级函数” 究竟是哪里呢？实际上就是前文提到的 _libevent_callback() 函数。

从 _libevent_callback() 的角度来看，程序会从 co_resume() 函数返回，并且继续往下执行。此时我们可以这么理解：协程的调度，实际上是借用了 libevent来进行的。这里我们要关注一下 co_resume() 上方的几句：

// switch into the coroutine
if (arg->libevent_what_ptr) {
    *(arg->libevent_what_ptr) = (uint32_t)what;
}

登录后复制

这里将 libevent 事件 flag 值传递给了协程，而这是前文进行事件判断的重要依据。当时间到来，_libevent_callback() 会在下面调用 co_resume() 的位置，将 CPU 使用权交回给协程。

销毁协程

除了 ci_yield() 之外，协程函数调用 return 也会导致从 co_resume() 返回，所以在 _libevent_callback() 中，我们还需要判断协程是否已经结束。如果协程结束，那么就应当销毁相关的协程资源了。参见 if (is_coroutine_end(arg->coroutine)) {...} 条件体内的代码。

会话模式（Session Mode）

在本工程的实现中，提供了被称为 “会话模式” 的一个服务器设计模式。会话模式指的是 UDPServer 或 TCPServer 对象，在接收到传入数据后，自动区分客户端，并单独创建 Session 对象进行处理。每个 Session 对象只服务于一个客户端。

对于 TCPServer 而言，实现上述的功能比较简单，因为监听一个 TCP socket 之后，当有传入连接的时候，只要调用 accept()，就可以获得一个新的文件描述符，为这个文件描述符创建一个新的 Server 的子类就行了——这就是 TCPSession 类。

但是 UDPServer 就比较麻烦了，因为 UDP 不能这么做。我们只能自行实现所谓的 session。

UDPSession 实现

设计目标

我们需要实现 UDPSession 类的如下效果：

类调用 recv 函数时，只会接收到对应的远程客户端发来的数据
类调用 send 函数（实际实现是 reply()）时，可以使用 UDPServer 的端口进行回复

recv()

在工程中，UDPSession 是抽象类，实际实现是 UDPItnlSession。但是准确而言，UDPItnlSession 的实现，密切依赖于 UDPServer。这一部分，可以参照 UDPServer 的 _session_mode_worker() 函数中的 do-while() 循环体代码。程序思路如下：

UDPServer 维护一个 UDPSession 字典，以远程 IP + 端口名的组合作为 key。
当数据到来时，判断远程 IP + 端口的组合是否在字典中，如果在，那么就把数据复制给对应的 session；如果不存在，则创建 session

复制数据的代码，参见 UDPItnlSession 类的 forward_incoming_data() 函数实现。

reply()

发送数据其实就很简单，直接对 UDPServer 的 fd 进行 sendto() 就可以了。

quit

对于 session mode 的 Server 对象，代码中提供了一个可以由其 session 调用的、要求 server 退出并销毁资源的函数：quit_session_mode_server()。实现原理是向 server 触发一个 EV_SIGNAL 事件。对于普通的 I/O 事件而言，这是不应当出现的，我们这里活用来作为退出信号。如果 server 发现了这个信号，则触发退出逻辑。