七、Bufferevent：高级话题
本章介绍了Libevent的bufferevent实现的一些高级功能，这些功能对于典型用途不是必需的。 如果您只是在学习如何使用bufferevents，则应该暂时跳过本章，然后继续阅读evbuffer章。
1. 成对的 bufferevent
有时候网络程序需要与自身通信。比如说，通过某些协议对用户连接进行隧道操作的程序，有时候也需要通过同样的协议对自身的连接进行隧道操作。当然，可以通过打开一个到自身监听端口的连接，让程序使用这个连接来达到这种目标。但是，通过网络栈来与自身通信比较浪费资源。
替代的解决方案是，创建一对成对的 bufferevent。这样，写入到一个 bufferevent 的字节都被另一个接收（反过来也是），但是不需要使用套接字。
接口
int bufferevent_pair_new(struct event_base *base, int options,
struct bufferevent *pair[2]);
调用 bufferevent_pair_new()会设置 pair[0]和 pair[1]为一对相互连接的 bufferevent。除了 BEV_OPT_CLOSE_ON_FREE 无效、BEV_OPT_DEFER_CALLBACKS 总是打开的之外， 所有通常的选项都是支持的。
为什么 bufferevent 对需要带延迟回调运行？通常某一方上的操作会调用一个通知另一方的回调，从而调用另一方的回调，如此这样进行很多步。如果不延迟回调，这种调用链常常会导致栈溢出或者饿死其他连接，而且还要求所有的回调是可重入的。
成对的 bufferevent 支持 flush：设置模式参数为 BEV_NORMAL 或者 BEV_FLUSH 会强制要求所有相关数据从对中的一个 bufferevent 传输到另一个中，而忽略可能会限制传输的水位设置。增加 BEV_FINISHED 到模式参数中还会让对端的 bufferevent 产生 EOF 事件。
释放对中的任何一个成员不会自动释放另一个，也不会产生 EOF 事件。释放仅仅会使对中的另一个成员成为断开的。bufferevent 一旦断开，就不能再成功读写数据或者产生任何事件了。
接口
struct bufferevent *bufferevent_pair_get_partner(struct bufferevent *bev)
有时可能只需要给一个缓冲事件对中的另一个成员。 为此，您可以调用bufferevent_pair_get_partner（）函数。 如果bev是该对中的一个成员，并且另一个成员仍然存在，它将返回该对中的另一个成员。 否则，它返回NULL。
bufferevent 对由2.0.1-alpha 版本引入，而 bufferevent_pair_get_partner()函数由2.0.6版本引入。
2. 过滤 bufferevent
有时候需要转换传递给某 bufferevent 的所有数据，这可以通过添加一个压缩层，或者将协议包装到另一个协议中进行传输来实现。
接口
enum bufferevent_filter_result {
BEV_OK = 0,
BEV_NEED_MORE = 1,
BEV_ERROR = 2
};
typedef enum bufferevent_filter_result (*bufferevent_filter_cb)(
struct evbuffer *source, struct evbuffer *destination, ev_ssize_t dst_limit,
enum bufferevent_flush_mode mode, void *ctx);
struct bufferevent *bufferevent_filter_new(struct bufferevent *underlying,
bufferevent_filter_cb input_filter,
bufferevent_filter_cb output_filter,
int options,
void (*free_context)(void *),
void *ctx);
bufferevent_filter_new（）函数创建一个封装现有的“底层”bufferevent 的过滤 bufferevent。所有通过底层 bufferevent 接收的数据在到达过滤 bufferevent 之前都会经过“输入”过滤器的转换；所有通过底层 bufferevent 发送的数据在被发送到底层 bufferevent 之前都会经过“输出”过滤器的转换。
向底层 bufferevent 添加过滤器将替换其回调函数。可以向底层 bufferevent 的 evbuffer 添加回调函数，但是如果想让过滤器正确工作，就不能再设置 bufferevent 本身的回调函数。
input_filter 和 output_filter 函数将随后描述。options 参数支持所有通常的选项。如果设置了 BEV_OPT_CLOSE_ON_FREE ， 那 么 释 放 过 滤 bufferevent 也会同时释放底层bufferevent。ctx 参数是传递给过滤函数的任意指针；如果提供了 free_context，则在释放 ctx 之前它会被调用。
底层输入缓冲区有数据可读时，输入过滤器函数会被调用；过滤器的输出缓冲区有新的数据待写入时，输出过滤器函数会被调用。两个过滤器函数都有一对 evbuffer 参数：从 source 读取数据；向 destination 写入数据，而 dst_limit 参数描述了可以写入 destination 的字节数 上限。过滤器函数可以忽略这个参数，但是这样可能会违背高水位或者速率限制。如果dst_limit 是-1，则没有限制。mode 参数向过滤器描述了写入的方式。值 BEV_NORMAL 表示应该在方便转换的基础上写入尽可能多的数据；而 BEV_FLUSH 表示写入尽可能多的数据；BEV_FINISHED 表示过滤器函数应该在流的末尾执行额外的清理操作。最后，过滤器函数的 ctx 参数就是传递给 bufferevent_filter_new（）函数的指针（ctx 参数）。
如果成功向目标缓冲区写入了任何数据，过滤器函数应该返回 BEV_OK；如果不获得更多的输入，或者不使用不同的清空（flush）模式，就不能向目标缓冲区写入更多的数据，则应该返回 BEV_NEED_MORE；如果过滤器上发生了不可恢复的错误，则应该返回BEV_ERROR。
创建过滤器将启用底层 bufferevent 的读取和写入。随后就不需要自己管理读取和写入了：过滤器在不想读取的时候会自动挂起底层 bufferevent 的读取。从2.0.8-rc 版本开始，可以在过滤器之外独立地启用/禁用底层 bufferevent 的读取和写入。然而，这样可能会让过滤器不能成功取得所需要的数据。
不需要同时指定输入和输出过滤器：没有给定的过滤器将被一个不进行数据转换的过滤器取代。
3. 限制最大单读/写大小
默认情况下，每次事件循环调用时，bufferevent都不会读取或写入最大可能的字节数； 这样做会导致奇怪的不公平行为和资源匮乏。 另一方面，默认值可能并非在所有情况下都合理。
接口
int bufferevent_set_max_single_read（struct bufferevent * bev，size_t size）;
int bufferevent_set_max_single_write（struct bufferevent * bev，size_t size）;
ev_ssize_t bufferevent_get_max_single_read（struct bufferevent * bev）;
ev_ssize_t bufferevent_get_max_single_write（struct bufferevent * bev）;
这两个“设置”功能分别替换了当前的最大读取和写入最大值。 如果大小值为0或大于EV_SSIZE_MAX，则将最大值设置为默认值。 这些函数成功返回0，失败返回-1。
这两个“ get”函数分别返回当前的每个循环读取和写入最大值。
这些功能已添加到2.1.1-alpha中。
4. bufferevent 和速率限制
某些程序需要限制单个或者一组 bufferevent 使用的带宽。2.0.4-alpha 和2.0.5-alpha 版本添加了为单个或者一组 bufferevent 设置速率限制的基本功能。
4.1 速率限制模型
libevent 的速率限制使用记号存储器（token bucket）算法确定在某时刻可以写入或者读取多少字节。每个速率限制对象在任何给定时刻都有一个“读存储器（read bucket）”和一个“写存储器（write bucket）”，其大小决定了对象可以立即读取或者写入多少字节。每个存储器有一个填充速率，一个最大突发尺寸，和一个时间单位，或者说“滴答（tick）”。一个时间单位流逝后，存储器被填充一些字节（决定于填充速率）——但是如果超过其突发尺寸，则超出的字节会丢失。
因此，填充速率决定了对象发送或者接收字节的最大平均速率，而突发尺寸决定了在单次突发中可以发送或者接收的最大字节数；时间单位则确定了传输的平滑程度。
4.2 为 bufferevent 设置速率限制
接口
#define EV_RATE_LIMIT_MAX EV_SSIZE_MAX
struct ev_token_bucket_cfg;
struct ev_token_bucket_cfg *ev_token_bucket_cfg_new(
size_t read_rate, size_t read_burst,
size_t write_rate, size_t write_burst,
const struct timeval *tick_len);
void ev_token_bucket_cfg_free(struct ev_token_bucket_cfg *cfg);
int bufferevent_set_rate_limit(struct bufferevent *bev,
struct ev_token_bucket_cfg *cfg);
ev_token_bucket_cfg 结构体代表用于限制单个或者一组 bufferevent 的一对记号存储器的配置值。要创建 ev_token_bucket_cfg，调用 ev_token_bucket_cfg_new 函数，提供最大平均读取速率、最大突发读取量、最大平均写入速率、最大突发写入量，以及一个滴答的长度。如果 tick_len 参数为 NULL，则默认的滴答长度为一秒。如果发生错误，函数会返回 NULL。
注意：read_rate 和 write_rate 参数的单位是字节每滴答。也就是说，如果滴答长度是十分之一秒，read_rate 是300，则最大平均读取速率是3000字节每秒。此外，不支持大于EV_RATE_LIMIT_MAX 的速率或者突发量。
要 限 制 bufferevent的传输速率，使用一个 ev_token_bucket_cfg ， 对其调用bufferevent_set_rate_limit（）。成功时函数返回0，失败时返回-1。可以对任意数量的bufferevent 使 用 相 同 的 ev_token_bucket_cfg 。 要 移 除 速 率 限 制 ， 可 以 调 用bufferevent_set_rate_limit（），传递 NULL 作为 cfg 参数值。
调用 ev_token_bucket_cfg_free（）可以释放 ev_token_bucket_cfg。注意：当前在没有任何 bufferevent 使用 ev_token_bucket_cfg 之前进行释放是不安全的。
4.3 为一组 bufferevent 设置速率限制
如果要限制一组 bufferevent 总的带宽使用，可以将它们分配到一个速率限制组中。
接口
struct bufferevent_rate_limit_group;
struct bufferevent_rate_limit_group *bufferevent_rate_limit_group_new(
struct event_base *base,
const struct ev_token_bucket_cfg *cfg);
int bufferevent_rate_limit_group_set_cfg(
struct bufferevent_rate_limit_group *group,
const struct ev_token_bucket_cfg *cfg);
void bufferevent_rate_limit_group_free(struct bufferevent_rate_limit_group *);
int bufferevent_add_to_rate_limit_group(struct bufferevent *bev,
struct bufferevent_rate_limit_group *g);
int bufferevent_remove_from_rate_limit_group(struct bufferevent *bev);
要创建速率限制组，使用一个 event_base 和一个已经初始化的 ev_token_bucket_cfg 作为参数调用 bufferevent_rate_limit_group_new 函 数 。使用bufferevent_add_to_rate_limit_group 将 bufferevent 添 加 到 组中 ；使用bufferevent_remove_from_rate_limit_group 从组中删除 bufferevent。这些函数成功时返回
0，失败时返回-1。
单个 bufferevent 在某时刻只能是一个速率限制组的成员。bufferevent 可以同时有单独的速率限制（通过 bufferevent_set_rate_limit 设置）和组速率限制。设置了这两个限制时，对每个 bufferevent，较低的限制将被应用。
调用 bufferevent_rate_limit_group_set_cfg 修改组的速率限制。函数成功时返回0，失败时返回-1。bufferevent_rate_limit_group_free 函数释放速率限制组，移除所有成员。
在2.0版本中，组速率限制试图实现总体的公平，但是具体实现可能在小的时间范围内并不公平。如果你强烈关注调度的公平性，请帮助提供未来版本的补丁。
4.4 检查当前速率限制
有时候需要得知应用到给定 bufferevent 或者组的速率限制，为此，libevent 提供了函数：
接口
ev_ssize_t bufferevent_get_read_limit(struct bufferevent *bev);
ev_ssize_t bufferevent_get_write_limit(struct bufferevent *bev);
ev_ssize_t bufferevent_rate_limit_group_get_read_limit(
struct bufferevent_rate_limit_group *);
ev_ssize_t bufferevent_rate_limit_group_get_write_limit(
struct bufferevent_rate_limit_group *);
上述函数返回以字节为单位的 bufferevent 或者组的读写记号存储器大小。注意：如果bufferevent 已经被强制超过其配置（清空(flush)操作就会这样），则这些值可能是负数。
接口
ev_ssize_t bufferevent_get_max_to_read(struct bufferevent *bev);
ev_ssize_t bufferevent_get_max_to_write(struct bufferevent *bev);
这些函数返回在考虑了应用到 bufferevent 或者组（如果有）的速率限制，以及一次最大读写数据量的情况下，现在可以读或者写的字节数。
接口
void bufferevent_rate_limit_group_get_totals(
struct bufferevent_rate_limit_group *grp,
ev_uint64_t *total_read_out, ev_uint64_t *total_written_out);
void bufferevent_rate_limit_group_reset_totals(
struct bufferevent_rate_limit_group *grp);
每个 bufferevent_rate_limit_group 跟踪经过其发送的总的字节数，这可用于跟踪组中所有bufferevent 总的使用情况。对一个组调用 bufferevent_rate_limit_group_get_totals 会分别设置 total_read_out 和 total_written_out 为组的总读取和写入字节数。组创建的时候这些计数从0开始，调用 bufferevent_rate_limit_group_reset_totals 会复位计数为0。
4.5 手动调整速率限制
对于有复杂需求的程序，可能需要调整记号存储器的当前值。比如说，如果程序不通过使用bufferevent 的方式产生一些通信量时。
接口
int bufferevent_decrement_read_limit(struct bufferevent *bev, ev_ssize_t decr);
int bufferevent_decrement_write_limit(struct bufferevent *bev, ev_ssize_t decr);
int bufferevent_rate_limit_group_decrement_read(
struct bufferevent_rate_limit_group *grp, ev_ssize_t decr);
int bufferevent_rate_limit_group_decrement_write(
struct bufferevent_rate_limit_group *grp, ev_ssize_t decr);
这些函数减小某个 bufferevent 或者速率限制组的当前读或者写存储器。注意：减小是有符号的。如果要增加存储器，就传入负值。
4.6 设置速率限制组的最小可能共享
通常，不希望在每个滴答中为速率限制组中的所有 bufferevent 平等地分配可用的字节。比如说，有一个含有10000个活动 bufferevent 的速率限制组，它在每个滴答中可以写入10000字节，那么，因为系统调用和 TCP 头部的开销，让每个 bufferevent 在每个滴答中仅写入1字节是低效的。
为解决此问题，速率限制组有一个“最小共享（minimum share）”的概念。在上述情况下，不是允许每个 bufferevent 在每个滴答中写入1字节，而是在每个滴答中允许某个 bufferevent写入一些（最小共享）字节，而其余的 bufferevent 将不允许写入。允许哪个 bufferevent写入将在每个滴答中随机选择。
默认的最小共享值具有较好的性能，当前（2.0.6-rc 版本）其值为64。可以通过这个函数调整最小共享值：
接口
int bufferevent_rate_limit_group_set_min_share(
struct bufferevent_rate_limit_group *group, size_t min_share);
设置 min_share 为0将会完全禁止最小共享。
速率限制功能从引入开始就具有最小共享了，而修改最小共享的函数在2.0.6-rc 版本首次引入。
4.7 速率限制实现的限制
2.0版本的 libevent 的速率限制具有一些实现上的限制：
- 不是每种 bufferevent 类型都良好地或者说完整地支持速率限制。
- bufferevent 速率限制组不能嵌套，一个 bufferevent 在某时刻只能属于一个速率限制组。
- 速率限制实现仅计算 TCP 分组传输的数据，不包括 TCP 头部。
- 读速率限制实现依赖于 TCP 栈通知应用程序仅仅以某速率消费数据，并且在其缓冲区
满的时候将数据推送到 TCP 连接的另一端。 - 某些 bufferevent 实现（特别是 Windows 中的 IOCP 实现）可能调拨过度。
- 存储器开始于一个滴答的通信量。这意味着 bufferevent 可以立即开始读取或者写入，
而不用等待一个滴答的时间。但是这也意味着速率被限制为 N.1个滴答的 bufferevent
可能传输 N+1个滴答的通信量。 - 滴答不能小于1毫秒，毫秒的小数部分都被忽略。
5. bufferevent 和 SSL
bufferevent 可以使用 OpenSSL 库实现 SSL/TLS 安全传输层。因为很多应用不需要或者不想链接 OpenSSL，这部分功能在单独的 libevent_openssl 库中实现。未来版本的 libevent可能会添加其他 SSL/TLS 库，如 NSS 或者 GnuTLS，但是当前只有 OpenSSL。
OpenSSL 功能在2.0.3-alpha 版本引入，然而直到2.0.5-beta 和2.0.6-rc 版本才能良好工作。
这一节不包含对 OpenSSL、SSL/TLS 或者密码学的概述。
这一节描述的函数都在 event2/bufferevent_ssl.h 中声明。
创建和使用基于 OpenSSL 的 bufferevent
接口
enum bufferevent_ssl_state {
BUFFEREVENT_SSL_OPEN = 0,
BUFFEREVENT_SSL_CONNECTING = 1,
BUFFEREVENT_SSL_ACCEPTING = 2
};
struct bufferevent *
bufferevent_openssl_filter_new(struct event_base *base,
struct bufferevent *underlying,
SSL *ssl,
enum bufferevent_ssl_state state,
int options);
struct bufferevent *
bufferevent_openssl_socket_new(struct event_base *base,
evutil_socket_t fd,
SSL *ssl,
enum bufferevent_ssl_state state,
int options);
可以创建两种SSL bufferevent：基于过滤器的bufferevent，该事件通过另一个基础bufferevent进行通信，或者基于套接字的bufferevent，通知OpenSSL直接通过网络与网络进行通信。无论哪种情况，都必须提供SSL对象和SSL对象状态的描述。如果SSL当前正在作为客户端进行协商，则状态应为BUFFEREVENT_SSL_CONNECTING；如果SSL当前正在作为服务器进行协商，则状态应为BUFFEREVENT_SSL_ACCEPTING；如果SSL握手已完成，则状态应为BUFFEREVENT_SSL_OPEN。
接受常规选项； BEV_OPT_CLOSE_ON_FREE使当关闭openssl bufferevent本身时，SSL对象和基础fd或bufferevent关闭。
握手完成后，将使用标志中的BEV_EVENT_CONNECTED调用新的bufferevent的事件回调。
如果您要创建基于套接字的bufferEvent，并且SSL对象已经设置了套接字，则无需自己提供套接字：只需传递-1。您还可以稍后使用bufferevent_setfd（）设置fd。
/// TODO：bufferevent_shutdown（）API完成后，请删除此代码。
请注意，在SSL缓冲区事件中设置BEV_OPT_CLOSE_ON_FREE时，将不会在SSL连接上执行干净关闭。这有两个问题：首先，连接似乎已被另一端“断开”，而不是被完全关闭：另一方将无法告知您是否关闭了连接，或断开了连接攻击者或第三方。其次，OpenSSL将会话视为“不良”会话，并从会话缓存中删除。这可能导致负载下的SSL应用程序性能显着下降。
当前，唯一的解决方法是手动关闭惰性SSL。虽然这破坏了TLS RFC，但可以确保会话一旦关闭就将保留在缓存中。下面的代码实现此解决方法。
示例
SSL *ctx = bufferevent_openssl_get_ssl(bev);
/*
* SSL_RECEIVED_SHUTDOWN tells SSL_shutdown to act as if we had already
* received a close notify from the other end. SSL_shutdown will then
* send the final close notify in reply. The other end will receive the
* close notify and send theirs. By this time, we will have already
* closed the socket and the other end's real close notify will never be
* received. In effect, both sides will think that they have completed a
* clean shutdown and keep their sessions valid. This strategy will fail
* if the socket is not ready for writing, in which case this hack will
* lead to an unclean shutdown and lost session on the other end.
*/
SSL_set_shutdown(ctx, SSL_RECEIVED_SHUTDOWN);
SSL_shutdown(ctx);
bufferevent_free(bev);
接口
SSL *bufferevent_openssl_get_ssl(struct bufferevent *bev);
这个函数返回 OpenSSL bufferevent 使用的 SSL 对象。如果 bev 不是一个基于 OpenSSL 的 bufferevent，则返回 NULL。
接口
unsigned long bufferevent_get_openssl_error(struct bufferevent *bev);
这个函数返回给定 bufferevent 的第一个未决的 OpenSSL 错误；如果没有未决的错误，则返回0。错误值的格式与 openssl 库中的 ERR_get_error（）返回的相同。
接口
int bufferevent_ssl_renegotiate(struct bufferevent *bev);
调用这个函数要求 SSL 重新协商，bufferevent 会调用合适的回调函数。这是个高级功能，通常应该避免使用，除非你确实知道自己在做什么，特别是有些 SSL 版本具有与重新协商相关的安全问题。
接口
int bufferevent_openssl_get_allow_dirty_shutdown(struct bufferevent *bev);
void bufferevent_openssl_set_allow_dirty_shutdown(struct bufferevent *bev,
int allow_dirty_shutdown);
SSL协议的所有良好版本（即SSLv3和所有TLS版本）都支持经过身份验证的关闭操作，该操作使各方可以区分下意识缓冲区中的故意关闭与意外或恶意引发的终止。 默认情况下，我们将正确关闭以外的所有内容都视为连接错误。 但是，如果allow_dirty_shutdown标志设置为1，则将连接中的关闭视为BEV_EVENT_EOF。
Libevent 2.1.1-alpha中添加了allow_dirty_shutdown函数。
示例：一个简单的基于SSL的回显服务器
#include
#include
#include
#include
#include
#include
#include
#include
static void
echo_read_cb(struct bufferevent *bev, void *ctx)
{
/* This callback is invoked when there is data to read on bev. */
struct evbuffer *input = bufferevent_get_input(bev);
struct evbuffer *output = bufferevent_get_output(bev);
/* Copy all the data from the input buffer to the output buffer. */
evbuffer_add_buffer(output, input);
}
static void
echo_event_cb(struct bufferevent *bev, short events, void *ctx)
{
if (events & BEV_EVENT_ERROR)
perror("Error from bufferevent");
if (events & (BEV_EVENT_EOF | BEV_EVENT_ERROR)) {
bufferevent_free(bev);
}
}
static void
accept_conn_cb(struct evconnlistener *listener,
evutil_socket_t fd, struct sockaddr *address, int socklen,
void *ctx)
{
/* We got a new connection! Set up a bufferevent for it. */
struct event_base *base = evconnlistener_get_base(listener);
struct bufferevent *bev = bufferevent_socket_new(
base, fd, BEV_OPT_CLOSE_ON_FREE);
bufferevent_setcb(bev, echo_read_cb, NULL, echo_event_cb, NULL);
bufferevent_enable(bev, EV_READ|EV_WRITE);
}
static void
accept_error_cb(struct evconnlistener *listener, void *ctx)
{
struct event_base *base = evconnlistener_get_base(listener);
int err = EVUTIL_SOCKET_ERROR();
fprintf(stderr, "Got an error %d (%s) on the listener. "
"Shutting down.\n", err, evutil_socket_error_to_string(err));
event_base_loopexit(base, NULL);
}
int
main(int argc, char **argv)
{
struct event_base *base;
struct evconnlistener *listener;
struct sockaddr_in sin;
int port = 9876;
if (argc > 1) {
port = atoi(argv[1]);
}
if (port<=0 || port>65535) {
puts("Invalid port");
return 1;
}
base = event_base_new();
if (!base) {
puts("Couldn't open event base");
return 1;
}
/* Clear the sockaddr before using it, in case there are extra
* platform-specific fields that can mess us up. */
memset(&sin, 0, sizeof(sin));
/* This is an INET address */
sin.sin_family = AF_INET;
/* Listen on 0.0.0.0 */
sin.sin_addr.s_addr = htonl(0);
/* Listen on the given port. */
sin.sin_port = htons(port);
listener = evconnlistener_new_bind(base, accept_conn_cb, NULL,
LEV_OPT_CLOSE_ON_FREE|LEV_OPT_REUSEABLE, -1,
(struct sockaddr*)&sin, sizeof(sin));
if (!listener) {
perror("Couldn't create listener");
return 1;
}
evconnlistener_set_error_cb(listener, accept_error_cb);
event_base_dispatch(base);
return 0;
}
