libevent之bufferevents
Bufferevents：概念和基础知识
大多数情况下，应用程序希望执行一定数量的数据 除了仅响应事件之外，还进行缓冲。当我们想要的时候 写入数据，例如，通常的模式运行如下：
- 决定我们要将一些数据写入连接;把那个 缓冲区中的数据。
- 等待连接变为可写
- 尽可能多地写入数据
- 记住我们写了多少，如果我们还有更多的数据要写， 等待连接再次变为可写。
这种缓冲 IO 模式很常见，以至于 Libevent 提供了一个 它的通用机制。“缓冲事件”由 底层传输（如套接字）、读取缓冲区和写入 缓冲区。而不是常规事件，这些事件在 基础传输已准备好读取或写入，即 BufferEvent 在读取或写入足够多的内容时调用其用户提供的回调 数据。
有多种类型的缓冲事件，它们都共享一个共同点 接口。在撰写本文时，存在以下类型：
-
基于套接字的缓冲事件
从基础发送和接收数据的缓冲事件 stream socket，使用 event_* 接口作为其后端。
-
异步 IO 缓冲区事件
使用 Windows IOCP 接口发送和 将数据接收到基础流套接字。（仅限 Windows; 实验性的。
-
筛选缓冲区事件
之前处理传入和传出数据的缓冲事件 将其传递给基础 BufferEvent 对象，例如，传递给 压缩或翻译数据。
-
配对缓冲事件
两个相互传输数据的缓冲事件。
注意
从 Libevent 2.0.2-alpha 开始，这里的 bufferevents 接口仍然是 在所有 BufferEvent 类型中不完全正交。换言之， 并非下面描述的每个接口都适用于所有 BufferEvent 类型。 Libevent 开发人员打算在未来的版本中纠正此问题。
另请注意
缓冲区事件目前仅适用于面向流的协议，如 TCP。 将来可能会支持面向数据报的协议，如 UDP。
本节中的所有函数和类型都在 event2/bufferevent.h文件。与 evbuffers 特别相关的函数包括 在 event2/buffer.h 中声明;有关以下方面的信息，请参阅下一章 那些。
Bufferevents 和 evbuffers
每个缓冲区事件都有一个输入缓冲区和一个输出缓冲区。这些是 类型为“struct evbuffer”。当您有数据要写入时 buffer事件，将其添加到输出缓冲区;当 bufferevent 具有 数据供您读取，请将其从输入缓冲区中排出。
evbuffer 接口支持多种操作;我们讨论它们 后面的部分。
回调和水印
每个 bufferevent 都有两个与数据相关的回调：一个读取回调 和写入回调。默认情况下，读取回调被调用 每当从基础传输中读取任何数据时，写入 每当输出缓冲区中的足够数据被清空时，就会调用回调 基础传输。您可以覆盖这些函数的行为 通过调整 bufferevent 的读写“水印”。
每个缓冲事件都有四个水印：
-
读取低水位线
每当发生离开 bufferevent 的输入缓冲区的读取时 在此级别或更高级别，将调用 BufferEvent 的 Read 回调。 默认为 0，因此每次读取都会产生读取回调被调用。
-
读取高水位线
如果 bufferevent 的输入缓冲区达到此级别，则 buffer事件停止读取，直到从输缓冲区，再次将我们带到它下方。默认为无限制，所以 我们永远不会因为输入缓冲区的大小而停止读取。
-
写下低水位线
每当发生将我们带到此级别或更低级别的写入时，我们 调用写入回调。默认值为 0，因此写入回调 除非清空输出缓冲区，否则不会调用。
-
写高水位线
不直接由缓冲区事件使用，此水印可以具有特殊的 这意味着当 bufferevent 用作 另一个 BufferEvent。请参阅下面有关筛选缓冲区事件的说明。
bufferevent 还具有 “error” 或 “event” 回调，该回调将 调用以告知应用程序有关非面向数据的事件，例如 当连接关闭或发生错误时。以下事件 标志的定义如下：
-
BEV_EVENT_READING
在对 bufferevent 执行读取操作期间发生事件。看 其他标志是哪个事件。
-
BEV_EVENT_WRITING
在对 bufferevent 执行写入操作期间发生事件。看 其他标志是哪个事件。
-
BEV_EVENT_ERROR
bufferevent 操作期间发生错误。查看更多 有关错误的信息，请调用 EVUTIL_SOCKET_ERROR（）。
-
BEV_EVENT_TIMEOUT
缓冲事件的超时已过期。
-
BEV_EVENT_EOF
我们在 bufferevent 上得到了文件结束指示。
-
BEV_EVENT_CONNECTED
我们在 bufferevent 上完成了请求的连接。
（上述事件名称在 Libevent 2.0.2-alpha 中是新增的。
延迟回调
默认情况下，在以下情况下会立即执行 bufferevent 回调 发生相应的情况。（evbuffer 也是如此 回调也是如此;我们稍后会谈到这些。此即时调用 当依赖关系变得复杂时，可能会造成麻烦。例如，假设 有一个回调，当数据增长时，它会将数据移动到 evbuffer A 中 empty，以及另一个从 evbuffer A 处理数据的回调 它长得很饱满。由于这些调用都发生在堆栈上，因此 如果依赖项变得足够讨厌，则可能会面临堆栈溢出的风险。
为了解决这个问题，你可以告诉 bufferevent（或 evbuffer）它的 回调应该被推迟。当满足条件时 延迟回调，而不是立即调用它，而是排队 作为 event_loop（） 调用的一部分，并在常规事件之后调用。 回调。
（延迟回调是在 Libevent 2.0.1-alpha 中引入的。
缓冲区事件的选项标志
在创建 bufferevent 时，可以使用一个或多个标志来更改其 行为。识别的标志包括：
-
BEV_OPT_CLOSE_ON_FREE
释放缓冲事件后，关闭基础传输。 这将关闭底层套接字，释放底层 bufferevent 等。
-
BEV_OPT_THREADSAFE
自动为 bufferevent 分配锁，以便它 可从多个线程安全使用。
-
BEV_OPT_DEFER_CALLBACKS
设置此标志后，bufferevent 会延迟其所有回调， 如上所述。
-
BEV_OPT_UNLOCK_CALLBACKS
默认情况下，当 bufferevent 设置为线程安全时， 每当任何用户提供 调用回调。设置此选项可使 Libevent 发布 bufferEvent 调用回调时的锁定。
（Libevent 2.0.5-beta 于 BEV_OPT_UNLOCK_CALLBACKS 年推出。其他选项 以上是 Libevent 2.0.1-alpha 中的新功能。
使用基于套接字的缓冲区事件
要使用的最简单的缓冲区事件是基于套接字的类型。一个 基于 socket 的 bufferevent 使用 Libevent 的底层事件机制来 检测底层网络套接字何时准备好读取和/或写入 操作，并使用底层网络调用（如 readv、writev、 WSASend 或 WSARecv） 来传输和接收数据。
创建基于套接字的缓冲区事件
可以使用以下方法创建基于套接字的缓冲区事件 bufferevent_socket_new（）：
接口
struct bufferevent *bufferevent_socket_new(
struct event_base *base,
evutil_socket_t fd,
enum bufferevent_options options);
base 是 event_base，options 是 bufferevent 的位掩码 选项（BEV_OPT_CLOSE_ON_FREE等）。fd 参数是一个 套接字的可选文件描述符。如果出现以下情况，您可以将 fd 设置为 -1 您希望稍后设置文件描述符。
| 提示 | [确保您提供给bufferevent_socket_new的套接字是 在非阻塞模式下。Libevent 提供了方便的方法 evutil_make_socket_nonblocking为此。 |
|---|---|
此函数在成功时返回 bufferevent，在失败时返回 NULL。
bufferevent_socket_new（） 函数是在 Libevent 2.0.1-alpha 中引入的。
在基于套接字的缓冲区事件上启动连接
如果 bufferevent 的套接字尚未连接，则可以启动新的 连接。
接口
int bufferevent_socket_connect(struct bufferevent *bev,
struct sockaddr *address, int addrlen);
address 和 addrlen 参数与标准调用相同 connect（） 中。如果 bufferevent 尚未设置套接字， 调用此函数会为其分配一个新的流套接字，并使 它不阻塞。
如果 bufferevent 确实已经有套接字，则调用 bufferevent_socket_connect（） 告诉 Libevent 套接字不是 连接，并且在套接字上不执行任何读取或写入操作，直到 连接操作已成功。
在连接之前将数据添加到输出缓冲区是可以的 做。
如果连接已成功启动，则此函数返回 0，并且 -1 如果发生错误。
例
#include <event2/event.h>
#include <event2/bufferevent.h>
#include <sys/socket.h>
#include <string.h>
void eventcb(struct bufferevent *bev, short events, void *ptr)
{
if (events & BEV_EVENT_CONNECTED) {
/* We're connected to 127.0.0.1:8080. Ordinarily we'd do
something here, like start reading or writing. */
} else if (events & BEV_EVENT_ERROR) {
/* An error occured while connecting. */
}
}
int main_loop(void)
{
struct event_base *base;
struct bufferevent *bev;
struct sockaddr_in sin;
base = event_base_new();
memset(&sin, 0, sizeof(sin));
sin.sin_family = AF_INET;
sin.sin_addr.s_addr = htonl(0x7f000001); /* 127.0.0.1 */
sin.sin_port = htons(8080); /* Port 8080 */
bev = bufferevent_socket_new(base, -1, BEV_OPT_CLOSE_ON_FREE);
bufferevent_setcb(bev, NULL, NULL, eventcb, NULL);
if (bufferevent_socket_connect(bev,
(struct sockaddr *)&sin, sizeof(sin)) < 0) {
/* Error starting connection */
bufferevent_free(bev);
return -1;
}
event_base_dispatch(base);
return 0;
}
bufferevent_socket_connect（） 函数是在 libevent-2.0.2-alpha。 在此之前，您必须手动调用 connect（） 在您的套接字上，以及连接的时间 完成后，BufferEvent 会将其报告为写入。
请注意BEV_EVENT_CONNECTED，只有在启动 使用 bufferevent_socket_connect（） 尝试 connect（）。如果您调用 connect（） 时，连接会报告为写入。
如果您想自己调用 connect（），但仍然收到一个 BEV_EVENT_CONNECTED 事件 连接成功时，调用 bufferevent_socket_connect（bev， NULL， 0） 后 connect（） 返回 -1 和 errno 等于 EAGAIN 或 EINPROGRESS。
此函数是在 Libevent 2.0.2-alpha 中引入的。
按主机名启动连接
很多时候，您希望将解析主机名和连接到主机名结合起来 变成一个操作。有一个接口：
接口
int bufferevent_socket_connect_hostname(struct bufferevent *bev,
struct evdns_base *dns_base, int family, const char *hostname,
int port);
int bufferevent_socket_get_dns_error(struct bufferevent *bev);
此函数解析 DNS 名称主机名，查找 family 类型的地址。（允许的家庭类型为 AF_INET、AF_INET6 和 AF_UNSPEC。如果 名称解析失败，它会使用错误事件调用事件回调。 如果成功，它会像bufferevent_connect一样启动连接尝试 愿意。
dns_base 参数是可选的。如果它为 NULL，则 Libevent 会阻塞 等待名称查找完成，这通常不是您想要的。如果 它提供了，然后 Libevent 使用它异步查找主机名。 有关 DNS 的更多信息，请参阅第 R9 章。
与 bufferevent_socket_connect（） 一样，此函数告诉 Libevent 任何 BufferEvent 上的现有套接字未连接，并且没有读取或写入 应该在套接字上完成，直到解析完成并连接 操作成功。
如果发生错误，则可能是 DNS 主机名查找错误。你可以找到 通过调用找出最近的错误是什么 bufferevent_socket_get_dns_error（）。如果返回的错误代码为 0，则没有 DNS 检测到错误。
示例：简单的 HTTP v0 客户端。
/* Don't actually copy this code: it is a poor way to implement an
HTTP client. Have a look at evhttp instead.
*/
#include <event2/dns.h>
#include <event2/bufferevent.h>
#include <event2/buffer.h>
#include <event2/util.h>
#include <event2/event.h>
#include <stdio.h>
void readcb(struct bufferevent *bev, void *ptr)
{
char buf[1024];
int n;
struct evbuffer *input = bufferevent_get_input(bev);
while ((n = evbuffer_remove(input, buf, sizeof(buf))) > 0) {
fwrite(buf, 1, n, stdout);
}
}
void eventcb(struct bufferevent *bev, short events, void *ptr)
{
if (events & BEV_EVENT_CONNECTED) {
printf("Connect okay.\n");
} else if (events & (BEV_EVENT_ERROR|BEV_EVENT_EOF)) {
struct event_base *base = ptr;
if (events & BEV_EVENT_ERROR) {
int err = bufferevent_socket_get_dns_error(bev);
if (err)
printf("DNS error: %s\n", evutil_gai_strerror(err));
}
printf("Closing\n");
bufferevent_free(bev);
event_base_loopexit(base, NULL);
}
}
int main(int argc, char **argv)
{
struct event_base *base;
struct evdns_base *dns_base;
struct bufferevent *bev;
if (argc != 3) {
printf("Trivial HTTP 0.x client\n"
"Syntax: %s [hostname] [resource]\n"
"Example: %s www.google.com /\n",argv[0],argv[0]);
return 1;
}
base = event_base_new();
dns_base = evdns_base_new(base, 1);
bev = bufferevent_socket_new(base, -1, BEV_OPT_CLOSE_ON_FREE);
bufferevent_setcb(bev, readcb, NULL, eventcb, base);
bufferevent_enable(bev, EV_READ|EV_WRITE);
evbuffer_add_printf(bufferevent_get_output(bev), "GET %s\r\n", argv[2]);
bufferevent_socket_connect_hostname(
bev, dns_base, AF_UNSPEC, argv[1], 80);
event_base_dispatch(base);
return 0;
}
bufferevent_socket_connect_hostname（） 函数是 Libevent 中的新功能 2.0.3-阿尔法;bufferevent_socket_get_dns_error（） 是 2.0.5-beta 中的新功能。
通用 bufferevent 操作
本节中的函数适用于多个缓冲区事件 实现。
释放缓冲区事件
接口
void bufferevent_free(struct bufferevent *bev);
此函数释放缓冲区事件。缓冲区事件在内部 reference-counted，因此如果 bufferevent 有待处理的延迟 回调 当你释放它时，它不会被删除，直到回调 都完成了。
但是，bufferevent_free（） 函数会尝试释放 Buffer事件。如果有待处理的数据要写入 BufferEvent，它可能不会在 BufferEvent 之前刷新 释放。
如果设置了 BEV_OPT_CLOSE_ON_FREE 标志，并且此 bufferevent 具有 套接字或与之关联的底层缓冲事件作为其传输， 释放 BufferEvent 时，该传输将关闭。
此函数是在 Libevent 0.8 中引入的。
操作回调、水印和启用的操作
接口
typedef void (*bufferevent_data_cb)(struct bufferevent *bev, void *ctx);
typedef void (*bufferevent_event_cb)(struct bufferevent *bev,
short events, void *ctx);
void bufferevent_setcb(struct bufferevent *bufev,
bufferevent_data_cb readcb, bufferevent_data_cb writecb,
bufferevent_event_cb eventcb, void *cbarg);
void bufferevent_getcb(struct bufferevent *bufev,
bufferevent_data_cb *readcb_ptr,
bufferevent_data_cb *writecb_ptr,
bufferevent_event_cb *eventcb_ptr,
void **cbarg_ptr);
bufferevent_setcb（） 函数更改一个或多个回调 缓冲事件。readcb、writecb 和 eventcb 函数是 当读取足够多的数据时，调用（分别），当读取足够的数据时 写入，或事件发生时。每个参数的第一个参数是 发生事件的 bufferEvent。最后一个参数是 用户在 cbarg 参数中提供的值 bufferevent_callcb（）：你可以用它来将数据传递给你的 回调。事件回调的 events 参数是一个位掩码 事件标志：请参阅上面的“回调和水印”。
您可以通过传递 NULL 而不是回调来禁用回调 功能。请注意，bufferevent 上的所有回调函数都共享 单个 cbarg 值，因此更改它将影响所有值。
您可以通过传送 bufferevent 来检索当前设置的回调 指向 bufferevent_getcb（） 的指针，该指针将 readcb_ptr 设置为当前读取 回调，writecb_ptr当前写入回调，*eventcb_ptr 当前事件回调，以及 *cbarg_ptr 当前回调参数 田。任何设置为 NULL 的指针都将被忽略。
bufferevent_setcb（） 函数是在 Libevent 1.4.4 中引入的。类型 名称“bufferevent_data_cb”和“bufferevent_event_cb”在 Libevent 中是新的 2.0.2-阿尔法。bufferevent_getcb（） 函数是在 2.1.1-alpha 中添加的。
接口
void bufferevent_enable(struct bufferevent *bufev, short events);
void bufferevent_disable(struct bufferevent *bufev, short events);
short bufferevent_get_enabled(struct bufferevent *bufev);
您可以启用或禁用事件 EV_READ、EV_WRITE 或 EV_READ|EV_WRITE在缓冲事件上。当阅读或写作不是 启用后，BufferEvent 将不会尝试读取或写入数据。
当输出缓冲区为空时，无需禁用写入： BufferEvent 自动停止写入，然后再次重新启动 当有数据要写入时。
同样，当输入缓冲区 达到其高水位线：缓冲事件自动停止 读取，并在有阅读空间时重新启动。
默认情况下，新创建的 bufferevent 已启用写入功能，但未启用 读数。
您可以调用 bufferevent_get_enabled（） 来查看当前正在发生的事件 在 BufferEvent 上启用。
这些函数是在 Libevent 0.8 中引入的，但 bufferevent_get_enabled（），在 2.0.3-alpha 版本中引入。
接口
void bufferevent_setwatermark(struct bufferevent *bufev, short events,
size_t lowmark, size_t highmark);
bufferevent_setwatermark（） 函数调整读取水印， 写入单个 BufferEvent 的水印，或同时写入水印。（如果EV_READ 在事件字段中设置，则调整读取的水印。如果 EV_WRITE在事件字段中设置，则会调整写入水印。
高水位线 0 等同于“无限”。
此函数在 Libevent 1.4.4 中首次公开。
例
#include <event2/event.h>
#include <event2/bufferevent.h>
#include <event2/buffer.h>
#include <event2/util.h>
#include <stdlib.h>
#include <errno.h>
#include <string.h>
struct info {
const char *name;
size_t total_drained;
};
void read_callback(struct bufferevent *bev, void *ctx)
{
struct info *inf = ctx;
struct evbuffer *input = bufferevent_get_input(bev);
size_t len = evbuffer_get_length(input);
if (len) {
inf->total_drained += len;
evbuffer_drain(input, len);
printf("Drained %lu bytes from %s\n",
(unsigned long) len, inf->name);
}
}
void event_callback(struct bufferevent *bev, short events, void *ctx)
{
struct info *inf = ctx;
struct evbuffer *input = bufferevent_get_input(bev);
int finished = 0;
if (events & BEV_EVENT_EOF) {
size_t len = evbuffer_get_length(input);
printf("Got a close from %s. We drained %lu bytes from it, "
"and have %lu left.\n", inf->name,
(unsigned long)inf->total_drained, (unsigned long)len);
finished = 1;
}
if (events & BEV_EVENT_ERROR) {
printf("Got an error from %s: %s\n",
inf->name, evutil_socket_error_to_string(EVUTIL_SOCKET_ERROR()));
finished = 1;
}
if (finished) {
free(ctx);
bufferevent_free(bev);
}
}
struct bufferevent *setup_bufferevent(void)
{
struct bufferevent *b1 = NULL;
struct info *info1;
info1 = malloc(sizeof(struct info));
info1->name = "buffer 1";
info1->total_drained = 0;
/* ... Here we should set up the bufferevent and make sure it gets
connected... */
/* Trigger the read callback only whenever there is at least 128 bytes
of data in the buffer. */
bufferevent_setwatermark(b1, EV_READ, 128, 0);
bufferevent_setcb(b1, read_callback, NULL, event_callback, info1);
bufferevent_enable(b1, EV_READ); /* Start reading. */
return b1;
}
操作缓冲区事件中的数据
从网络读取和写入数据对您没有好处，如果您不能看它。Bufferevents 为您提供了这些方法来提供它们 要写入的数据，以及要读取的数据：
接口
struct evbuffer *bufferevent_get_input(struct bufferevent *bufev);
struct evbuffer *bufferevent_get_output(struct bufferevent *bufev);
这两个函数是非常强大的基本函数：它们返回 分别输入和输出缓冲器。有关所有的完整信息 可以对 EVPud 类型执行的操作，请参见下一篇 章。
请注意，应用程序只能从输入中删除（而不是添加）数据 缓冲区，并且只能向输出缓冲区添加（而不是删除）数据。
如果写入缓冲事件由于数据太少而停止 （或者如果读取因太多而停滞不前），然后将数据添加到 输出缓冲区（或从输入缓冲区中删除数据）将 自动重新启动它。
这些函数是在 Libevent 2.0.1-alpha 中引入的。
接口
int bufferevent_write(struct bufferevent *bufev,
const void *data, size_t size);
int bufferevent_write_buffer(struct bufferevent *bufev,
struct evbuffer *buf);
这些函数将数据添加到 bufferevent 的输出缓冲区。叫 bufferevent_write（） 将内存中的**大小字节添加到 输出缓冲区的末尾。调用 bufferevent_write_buffer（） 删除 BUF 的全部内容，并将它们放在输出的末尾 缓冲区。如果成功，两者都返回 0，如果发生错误，则返回 -1。
这些函数从 Libevent 0.8 开始就已经存在了。
接口
size_t bufferevent_read(struct bufferevent *bufev, void *data, size_t size);
int bufferevent_read_buffer(struct bufferevent *bufev,
struct evbuffer *buf);
这些函数从 bufferevent 的输入缓冲区中删除数据。这 bufferevent_read（） 函数从输入中删除最大size的字节 缓冲区，将它们存储在data存储器中。它返回数字 实际删除的字节数。bufferevent_read_buffer（） 函数 排出输入缓冲区的全部内容并将它们放入 BUF;成功时返回 0，失败时返回 -1。
请注意，使用 bufferevent_read（），数据中的内存块必须 实际上有足够的空间来容纳大小字节的数据。
bufferevent_read（） 函数自 Libevent 0.8 以来就已存在; bufferevent_read_buffer（） 是在 Libevent 2.0.1-alpha 中引入的。
例
#include <event2/bufferevent.h>
#include <event2/buffer.h>
#include <ctype.h>
void
read_callback_uppercase(struct bufferevent *bev, void *ctx)
{
/* This callback removes the data from bev's input buffer 128
bytes at a time, uppercases it, and starts sending it
back.
(Watch out! In practice, you shouldn't use toupper to implement
a network protocol, unless you know for a fact that the current
locale is the one you want to be using.)
*/
char tmp[128];
size_t n;
int i;
while (1) {
n = bufferevent_read(bev, tmp, sizeof(tmp));
if (n <= 0)
break; /* No more data. */
for (i=0; i<n; ++i)
tmp[i] = toupper(tmp[i]);
bufferevent_write(bev, tmp, n);
}
}
struct proxy_info {
struct bufferevent *other_bev;
};
void
read_callback_proxy(struct bufferevent *bev, void *ctx)
{
/* You might use a function like this if you're implementing
a simple proxy: it will take data from one connection (on
bev), and write it to another, copying as little as
possible. */
struct proxy_info *inf = ctx;
bufferevent_read_buffer(bev,
bufferevent_get_output(inf->other_bev));
}
struct count {
unsigned long last_fib[2];
};
void
write_callback_fibonacci(struct bufferevent *bev, void *ctx)
{
/* Here's a callback that adds some Fibonacci numbers to the
output buffer of bev. It stops once we have added 1k of
data; once this data is drained, we'll add more. */
struct count *c = ctx;
struct evbuffer *tmp = evbuffer_new();
while (evbuffer_get_length(tmp) < 1024) {
unsigned long next = c->last_fib[0] + c->last_fib[1];
c->last_fib[0] = c->last_fib[1];
c->last_fib[1] = next;
evbuffer_add_printf(tmp, "%lu", next);
}
/* Now we add the whole contents of tmp to bev. */
bufferevent_write_buffer(bev, tmp);
/* We don't need tmp any longer. */
evbuffer_free(tmp);
}
读写超时
与其他事件一样，如果某个事件，则可以调用超时 时间过去了，没有任何数据成功 由 bufferevent 写入或读取。
接口
void bufferevent_set_timeouts(struct bufferevent *bufev,
const struct timeval *timeout_read, const struct timeval *timeout_write);
将超时设置为 NULL 应该会删除它;然而在 Libevent 之前 2.1.2-alpha 这不适用于所有事件类型。（作为解决方法 旧版本，您可以尝试将超时设置为多天间隔 和/或让你的 eventCB 函数忽略BEV_TIMEOUT事件，而你不这样做 想要他们。
如果 bufferevent 在尝试读取数据时至少等待 timeout_read 秒，则将触发读取超时。写入 如果 bufferevent 在尝试写入数据时至少等待 timeout_write 秒，则将触发超时。
请注意，只有当 bufferevent 想要时，超时才会计算在内 读取或写入。换言之，如果出现以下情况，则不会启用读取超时 在 bufferevent 上禁用读取，或者如果输入缓冲区已满，则读取被禁用 （在其高水位线）。同样，未启用写入超时 如果写入被禁用，或者没有要写入的数据。
当发生读写超时时，相应的读写 在 BufferEvent 上禁用操作。然后事件回调是 使用任一 BEV_EVENT_TIMEOUT|BEV_EVENT_READING 或 BEV_EVENT_TIMEOUT|BEV_EVENT_WRITING。
此函数自 Libevent 2.0.1-alpha 以来一直存在。它没有表现 在 Libevent 2.0.4-alpha 之前，跨 bufferevent 类型保持一致。
在缓冲区事件上启动刷新
接口
int bufferevent_flush(struct bufferevent *bufev,
short iotype, enum bufferevent_flush_mode state);
刷新 bufferevent 会告知 bufferevent 强制执行尽可能多的字节数 尽可能从基础传输中读取或写入， 忽略其他可能阻止他们的限制 正在写。它的详细功能取决于 buffer事件。
iotype 参数应为 EV_READ、EV_WRITE 或 EV_READ|EV_WRITE 指示是否应读取、写入或同时读取和/或写入的字节 处理。状态参数可能是BEV_NORMAL之一， BEV_FLUSH，或BEV_FINISHED。BEV_FINISHED表示另一个 应告知方不会再发送数据;区别 BEV_NORMAL 和 BEV_FLUSH 之间取决于 buffer事件。
bufferevent_flush（） 函数在失败时返回 -1，如果没有数据，则返回 0 已刷新，如果某些数据已刷新，则为 1。
目前（从 Libevent 2.0.5-beta 开始），bufferevent_flush（） 只有 为某些 BufferEvent 类型实现。特别是，基于套接字 bufferEvents 没有它。
特定于类型的 bufferevent 函数
并非所有 bufferevent 都支持这些 bufferevent 函数 类型。
接口
int bufferevent_priority_set(struct bufferevent *bufev, int pri);
int bufferevent_get_priority(struct bufferevent *bufev);
此函数将用于实现 bufev 的事件的优先级调整为 pri。有关以下内容的更多信息，请参见 event_priority_set（） 优先 级。
此函数在成功时返回 0，在失败时返回 -1。它适用于 仅限基于套接字的缓冲事件。
bufferevent_priority_set（） 函数是在 Libevent 1.0 中引入的; bufferevent_get_priority（） 直到 Libevent 2.1.2-alpha 才出现。
接口
int bufferevent_setfd(struct bufferevent *bufev, evutil_socket_t fd);
evutil_socket_t bufferevent_getfd(struct bufferevent *bufev);
这些函数设置或返回基于 fd 的文件描述符 事件。只有基于套接字的 bufferevents 支持 setfd（）。两者都返回 -1 失败;setfd（） 在成功时返回 0。
bufferevent_setfd（） 函数是在 Libevent 1.4.4 中引入的; bufferevent_getfd（） 函数是在 Libevent 2.0.2-alpha 中引入的。
接口
struct event_base *bufferevent_get_base(struct bufferevent *bev);
此函数返回缓冲区事件的event_base。它被引入 2.0.9-rc。
接口
struct bufferevent *bufferevent_get_underlying(struct bufferevent *bufev);
此函数返回另一个 bufferevent 所在的 bufferevent 用作交通工具（如果有）。有关何时出现这种情况的信息 ，请参阅有关筛选缓冲区事件的说明。
此函数是在 Libevent 2.0.2-alpha 中引入的。
手动锁定和解锁缓冲区事件
与 evbuffers 一样，有时您希望确保许多操作 在缓冲区上，事件都是以原子方式执行的。Libevent 公开函数 可用于手动锁定和解锁 BufferEvent。
接口
void bufferevent_lock(struct bufferevent *bufev);
void bufferevent_unlock(struct bufferevent *bufev);
请注意，如果 bufferevent 不是 给定创建时的BEV_OPT_THREADSAFE线程，或者如果 Libevent 的线程 未激活支持。
使用此函数锁定 bufferevent 将锁定其关联的 evbuffers 也。这些函数是递归的：锁定 bufferevent 是安全的 你已经拿着锁了。当然，您必须调用一次解锁 每次锁定 BufferEvent。
这些函数是在 Libevent 2.0.6-rc 中引入的。
过时的缓冲区事件功能
bufferevent 后端代码在 Libevent 1.4 和 Libevent 2.0。在旧界面中，有时是 正常构建并访问结构的内部结构 buffer事件，并使用依赖于此访问的宏。
为了使事情变得混乱，旧代码有时会使用 以“evbuffer”为前缀的 bufferEvent 功能。
以下是以前称呼事物的简要指南 Libevent 2.0：
| 现用名 | 旧名称 |
|---|---|
| bufferevent_data_cb | evbuffercb |
| bufferevent_event_cb | everrorcb |
| BEV_EVENT_READING | EVBUFFER_READ |
| BEV_EVENT_WRITE | EVBUFFER_WRITE |
| BEV_EVENT_EOF | EVBUFFER_EOF |
| BEV_EVENT_ERROR | EVBUFFER_ERROR |
| BEV_EVENT_TIMEOUT | EVBUFFER_TIMEOUT |
| bufferevent_get_input（二） | EVBUFFER_INPUT（二） |
| bufferevent_get_output（二） | EVBUFFER_OUTPUT（二） |
旧函数是在 event.h 中定义的，而不是在 event2/bufferevent.h 中定义的。
如果您仍然需要访问公共部件的内部 bufferEvent 结构，可以包含 event2/bufferevent_struct.h。我们 建议不要这样做：struct bufferevent 的内容将在 Libevent 的版本。在以下情况下，本节中的宏和名称可用 包括 event2/bufferevent_compat.h。
设置缓冲区事件的界面在旧版本中有所不同：
接口
struct bufferevent *bufferevent_new(evutil_socket_t fd,
evbuffercb readcb, evbuffercb writecb, everrorcb errorcb, void *cbarg);
int bufferevent_base_set(struct event_base *base, struct bufferevent *bufev);
bufferevent_new（） 函数仅创建套接字缓冲区事件，并这样做 在已弃用的“默认”event_base上。呼叫bufferevent_base_set调整 仅套接字 Buffer 事件的event_base。
没有将超时设置为结构时间，而是将其设置为 秒数：
接口
void bufferevent_settimeout(struct bufferevent *bufev,
int timeout_read, int timeout_write);
最后，请注意 Libevent 的底层 evbuffer 实现 2.0 之前的版本效率非常低，以至于使用 高性能应用程序的 BufferEvents 有点值得怀疑。
最后更新 世界协调时 2024-02-18 20：10：44
Bufferevents：高级主题
这些文件版权所有 （c） 2009-2012 由 Nick Mathewson 制作 可在知识共享署名-非商业性使用-相同方式共享下使用 许可证，版本 3.0。未来的版本可能会在 限制性许可证。
此外，这些文档中的源代码示例也已获得许可 在所谓的“3-Clause”或“Modified”BSD许可证下。请参阅随这些文档一起分发的 license_bsd 文件 对于完整的条款。
若要获取本文档最新版本的源代码，请安装 git 并运行“git clone git://github.com/libevent/libevent-book.git”
本章介绍了 Libevent 缓冲事件的一些高级功能 对于典型用途不是必需的实现。如果你只是 学习如何使用 BufferEvents，您应该暂时跳过本章 并继续阅读 EVBUFFER 章节。
配对缓冲区事件
有时，您有一个需要自言自语的网络程序。 例如，您可以编写一个程序来隧道用户连接 通过某些协议，有时还希望通过隧道连接 它自己在该协议上。您可以通过打开一个 连接到您自己的收听端口并让您的程序使用 当然，它本身，但这会因为拥有你的程序而浪费资源 通过网络堆栈自言自语。
相反，您可以创建一对成对的缓冲区事件，以便所有字节 一个上写的在另一个上收到（反之亦然），但没有实际的 使用平台套接字。
接口
int bufferevent_pair_new(struct event_base *base, int options,
struct bufferevent *pair[2]);
调用 bufferevent_pair_new（） 将 pair[0] 和 pair[1] 设置为一对 Buffer事件，每个事件都连接到另一个。所有常用的选项都是 支持，但 BEV_OPT_CLOSE_ON_FREE 除外，它没有效果，并且 BEV_OPT_DEFER_CALLBACKS，它总是在线的。
为什么 bufferevent 对需要在延迟回调的情况下运行？很漂亮 对对中的一个元素执行的操作通常用于调用回调 更改 BufferEvent，从而调用其他 BufferEvent 的回调，以及 以此类推，通过许多步骤。当回调没有被延迟时，这个链 的调用会经常溢出堆栈，饿死其他 连接，并要求所有回调都是可重入的。
配对的缓冲区事件支持刷新;将 mode 参数设置为任一 BEV_NORMAL或BEV_FLUSH强制所有相关数据获得 从对中的一个 BufferEvent 转移到另一个 BufferEvent，忽略 否则会限制它的水印。将模式设置为BEV_FINISHED 此外，在相反的缓冲区事件上生成 EOF 事件。
释放对中的任何一个成员不会自动释放另一个成员或 生成 EOF 事件;它只是让这对的另一名成员成为 未链接。一旦 bufferevent 被取消链接，它将不再成功 读取或写入数据或生成任何事件。
接口
struct bufferevent *bufferevent_pair_get_partner(struct bufferevent *bev)
有时，您可能需要给定 bufferevent 对的其他成员 只有一个成员。为此，您可以调用 bufferevent_pair_get_partner（） 函数。它将返回 如果 BEV 是一对的成员，则该对仍然存在。 否则，它将返回 NULL。
Bufferevent 对是 Libevent 2.0.1-alpha 中的新增功能;这 bufferevent_pair_get_partner（） 函数是在 Libevent 2.0.6 中引入的。
筛选缓冲区事件
有时，您希望转换通过缓冲区事件传递的所有数据 对象。您可以这样做来添加压缩层，或将协议包装在 另一种运输协议。
接口
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 之前使用“input”筛选器进行转换 到达 Filtering BufferEvent，以及通过 Filtering 发送的所有数据 buffer事件在发送到 基础 BufferEvent。
将筛选器添加到基础 bufferevent 会替换 基础 bufferevent。您仍然可以向基础添加回调 bufferEvent 的 evbuffers，但无法在 bufferevent 上设置回调 本身，如果您希望过滤器仍然有效。
下面介绍了 input_filter 和 output_filter 函数。 选项中支持所有常用选项。如果BEV_OPT_CLOSE_ON_FREE ，则释放筛选缓冲区事件也会释放基础 buffer事件。ctx 字段是传递给过滤器的任意指针 功能;如果提供了free_context函数，则仅在 CTX 上调用它 在关闭筛选 BufferEvent 之前。
每当有新的可读数据时，都会调用输入过滤器函数 在基础输入缓冲区上。输出过滤器函数被调用 每当筛选器的输出缓冲区上有新的可写数据时。每一个 接收一对 EVBUFFER：一个用于从中读取数据的源 evbuffer，以及一个用于将数据写入的目标 evbuffer。dst_limit参数描述了 要添加到目标的字节的上限。过滤功能为 允许忽略此值，但这样做可能会违反高水位线 或速率限制。如果 dst_limit 为 -1，则没有限制。mode 参数告诉筛选器在写入时要有多激进。如果是 BEV_NORMAL，那么它应该尽可能多地写入可以方便地转换。 BEV_FLUSH值意味着尽可能多地写入，并BEV_FINISHED 表示过滤功能还应执行任何清理 在流的末尾是必需的。最后，filter 函数的 ctx 参数是提供给 bufferevent_filter_new（） 的 void 指针 构造 函数。
筛选器函数必须返回BEV_OK是否有任何数据已成功写入 目标缓冲区，BEV_NEED_MORE如果没有更多数据可以写入 目标缓冲区，无需获取更多输入或使用不同的刷新 模式，并BEV_ERROR筛选器上是否存在不可恢复的错误。
创建筛选器可以在基础上进行读取和写入 buffer事件。您不需要自行管理读取/写入：过滤器 每当它 不想看。对于 2.0.8-rc 及更高版本，允许 启用/禁用对基础 Buffer 事件的读取和写入 独立于过滤器。但是，如果您这样做，则可以保留 筛选成功获取所需数据。
您无需同时指定输入筛选器和输出筛选器：any 省略的过滤器将替换为传递数据而不进行转换的过滤器 它。
限制最大单次读/写大小
默认情况下，bufferevents 不会读取或写入可能的最大数量 每次调用事件循环的字节数;这样做会导致 奇怪的不公平行为和资源匮乏。另一方面， 默认值可能并非在所有情况下都合理。
接口
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);
两个“set”函数取代了当前的读写最大值 分别。如果大小值为 0 或高于 EV_SSIZE_MAX，则 而是将最大值设置为默认值。这些函数返回 0 成功时为 -1，失败时为 -1。
两个“get”函数返回当前每循环的读取和写入 最大值。
这些函数是在 2.1.1-alpha 中添加的。
缓冲事件和速率限制
某些程序希望限制用于任何单个的带宽量 bufferevent，或一组 bufferEvents。Libevent 2.0.4-alpha 和 Libevent 2.0.5-alpha 添加了一个基本功能，可以对个人进行上限 BufferEvents，或将 BufferEvents 分配给速率限制组。
速率限制模型
Libevent 的速率限制使用令牌桶算法来决定数量 一次读取或写入的字节数。每个受速率限制的对象，在任何给定 time，有一个“读桶”和一个“写桶”，其大小决定了 允许对象立即读取或写入的字节数。每 桶具有重新填充率、最大突发大小和 定时单位或“滴答声”。每当计时单元经过时，铲斗就会重新装满 与再填充率成正比，但如果会变得比其爆发率更满 大小，则任何多余的字节都会丢失。
因此，再填充速率决定了物体的最大平均速率 将发送或接收字节，突发大小决定最大数量 将在单个突发中发送或接收的字节数。计时单元 决定了交通的平滑度。
设置缓冲事件的速率限制
接口
#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 或一组 BufferEvents。要创建一个，请调用 ev_token_bucket_cfg_new函数并提供最大平均读取速率， 最大读取突发、最大写入速率、最大写入突发和 刻度的长度。如果 tick_len 参数为 NULL，则刻度的长度 默认值为一秒。该函数可能会在出错时返回 NULL。
请注意，read_rate 和 write_rate 参数以 每个刻度的字节数。也就是说，如果刻度是十分之一秒，read_rate是 300，则最大平均读取速率为每 3000 字节 第二。不支持超过 EV_RATE_LIMIT_MAX 的速率和突发值。
要限制缓冲事件的传输速率，请调用 bufferevent_set_rate_limit（） 它有一个ev_token_bucket_cfg。该函数在成功时返回 0，在成功时返回 -1 失败。您可以为任意数量的缓冲区事件提供相同的内容 ev_token_bucket_cfg。要删除缓冲事件的速率限制，请调用 bufferevent_set_rate_limit（），为 cfg 参数传递 NULL。
要释放ev_token_bucket_cfg，请调用 ev_token_bucket_cfg_free（）。请注意， 目前，在没有缓冲事件使用 ev_token_bucket_cfg。
为一组缓冲区事件设置速率限制
如果要限制，可以将缓冲区事件分配给速率限制组 他们的总带宽使用量。
接口
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);
要构造速率限制组，bufferevent_rate_limit_group请使用 event_base和最初的ev_token_bucket_cfg。您可以将 bufferevents 添加到 具有 bufferevent_add_to_rate_limit_group（） 和 bufferevent_remove_from_rate_limit_group（）;这些函数返回 0 成功和 -1 错误。
单个缓冲区事件可以是不超过一个速率限制组的成员 一次。缓冲事件可以同时具有单独的速率限制（如 bufferevent_set_rate_limit（）） 和组速率限制。当两个限制都是 设置时，每个 BufferEvent 的下限适用。
您可以通过调用来更改现有组的速率限制 bufferevent_rate_limit_group_set_cfg（）。成功时返回 0，成功时返回 -1 失败。bufferevent_rate_limit_group_free（） 函数释放速率限制 组并删除其所有成员。
从 2.0 版开始，Libevent 的组速率限制试图公平 聚合，但在非常小的时间尺度上实施可能是不公平的。如果 您非常关心日程安排的公平性，请帮忙 带有未来版本的补丁。
检查当前速率限制值
有时，您的代码可能想要检查应用的当前速率限制 对于给定的 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 可以执行此操作。
接口
ev_ssize_t bufferevent_get_max_to_read(struct bufferevent *bev);
ev_ssize_t bufferevent_get_max_to_write(struct bufferevent *bev);
这些函数返回 bufferevent 的字节数 愿意立即读取或写入，同时考虑到任何速率限制 适用于 BufferEvent、其速率限制组（如果有）和任何 Libevent 作为一个整体施加的最大读/写值。
接口
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跟踪发送的总字节数 它，总共。您可以使用它来跟踪总使用量 Buffer事件。叫 组上的 bufferevent_rate_limit_group_get_totals（） 将 *total_read_out 和 *total_written_out 设置为在 BufferEvent 组。当组为 创建，并在 bufferevent_rate_limit_group_reset_totals（） 时重置为 0 在组上被调用。
手动调整速率限制
对于具有真正复杂需求的程序，您可能需要调整当前 令牌存储桶的值。您可能希望这样做，例如，如果您的 程序以某种方式生成流量，而不是通过 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);
这些函数递减缓冲区事件中的当前读取或写入存储桶，或者 速率限制组。请注意，递减是有符号的：如果要 递增一个存储桶，传递一个负值。
在速率受限的组中设置尽可能小的份额
通常，您不希望在速率限制中划分可用的字节 在每个刻度的所有缓冲事件中均匀分组。例如，如果您 在具有 10,000 字节的速率限制组中有 10,000 个活动缓冲区事件 可用于写入每个刻度，让每个刻度都不会有效 由于系统调用的开销，BufferEvent 每次调用仅写入 1 个字节 和 TCP 标头。
为了解决这个问题，每个限速组都有一个“最小份额”的概念。 在上面的情况下，而不是允许每个缓冲事件写入 1 字节/刻度，允许 10,000/SHARE 缓冲事件写入 SHARE 字节 每个刻度，其余的将被允许不写任何东西。哪 Buffer允许先写入的事件是每个刻度随机选择的。
选择默认最小份额以提供不错的性能，并且是 当前（截至 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 将完全禁用最小共享代码。
Libevent的速率限制自首次以来就具有最低份额 介绍。更改它们的函数首先在 Libevent 中公开 2.0.6-rc。
速率限制实现的局限性
从 Libevent 2.0 开始，速率限制存在一些限制 你应该知道的实现。
- 并非每种 bufferevent 类型都支持速率限制，或者根本不支持速率限制。
- Bufferevent 速率限制组不能嵌套，而 bufferevent 只能是 一次在单个速率限制组中。
- 速率限制实现仅计算在 TCP 中传输的字节数 数据包作为数据，不包括 TCP 标头。
- 读取限制实现依赖于 TCP 堆栈，注意到 应用程序仅以一定的速度消耗数据，然后推回 当 TCP 连接的缓冲区已满时，TCP 连接的另一端。
- 缓冲区事件的一些实现（特别是 Windows IOCP implementation）可能会过度承诺。
- 存储桶开始时有一整块流量。这意味着 buffer事件可以立即开始读取或写入，而不是等到 完整的勾号已经过去了。不过，这也意味着具有 N.1 个报价的速率限制可能会转移 N+1 个报价价值 交通。
- 刻度不能小于 1 毫秒，并且 毫秒被忽略。
TODO：写一个限速的例子
Bufferevents 和 SSL
Bufferevents 可以使用 OpenSSL 库来实现 SSL/TLS 安全 传输层。因为许多应用程序不需要或不想链接 OpenSSL，此功能在单独的库中实现，安装为 “libevent_openssl”。Libevent 的未来版本可以添加对其他 SSL/TLS 库，例如 NSS 或 GnuTLS，但现在 OpenSSL 就是全部 那里。
OpenSSL 功能是在 Libevent 2.0.3-alpha 中引入的，尽管它没有 在 Libevent 2.0.5-beta 或 Libevent 2.0.6-rc 之前运行良好。
本节不是关于 OpenSSL、SSL/TLS 或一般加密的教程。
这些函数都在标头“event2/bufferevent_ssl.h”中声明。
设置和使用基于 OpenSSL 的缓冲区事件
接口
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 缓冲区事件：一种是基于筛选器的缓冲区事件，它 通过另一个基础缓冲区事件或基于套接字的 Buffer Event 进行通信 buffer事件，告诉 OpenSSL 直接通过网络进行通信。在 无论哪种情况，都必须提供 SSL 对象和 SSL 的描述 对象的状态。如果 SSL 是BUFFEREVENT_SSL_CONNECTING 目前作为客户进行谈判，BUFFEREVENT_SSL_ACCEPTING 如果 SSL 当前正在作为服务器执行协商，或者 BUFFEREVENT_SSL_OPEN SSL 握手是否完成。
接受通常的选项;BEV_OPT_CLOSE_ON_FREE使 SSL 对象 当 openSSL BufferEvent 关闭时，基础 FD 或 BufferEvent 将关闭 本身是封闭的。
握手完成后，将调用新 bufferevent 的事件回调 旗帜中BEV_EVENT_CONNECTED。
如果已创建基于套接字的缓冲区事件和 SSL 对象 有套接字，不需要自己提供套接字：通过就行了 -1.您也可以稍后使用 bufferevent_setfd（） 设置 fd。
TODO：bufferevent_shutdown（） API 完成后将其删除。
请注意，当在 SSL bufferevent 上设置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 缓冲区事件或 NULL 使用的 SSL 对象 如果 bev 不是基于 OpenSSL 的缓冲事件。
接口
unsigned long bufferevent_get_openssl_error(struct bufferevent *bev);
此函数返回给定的第一个挂起的 OpenSSL 错误 bufferEvent 的操作，如果没有挂起的错误，则为 0。错误 format 由 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） versions） 支持经过身份验证的关机操作，该操作启用 当事方区分故意关闭与意外关闭或 在底层缓冲区中恶意诱导终止。默认情况下，我们 将正确关机以外的任何内容视为连接错误。 但是，如果 allow_dirty_shutdown 标志设置为 1，则我们处理收盘价 在连接中作为BEV_EVENT_EOF。
allow_dirty_shutdown函数是在 Libevent 2.1.1-alpha 中添加的。
示例：基于 SSL 的简单回显服务器
/* Simple echo server using OpenSSL bufferevents */
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <arpa/inet.h>
#include <openssl/ssl.h>
#include <openssl/err.h>
#include <openssl/rand.h>
#include <event.h>
#include <event2/listener.h>
#include <event2/bufferevent_ssl.h>
static void
ssl_readcb(struct bufferevent * bev, void * arg)
{
struct evbuffer *in = bufferevent_get_input(bev);
printf("Received %zu bytes\n", evbuffer_get_length(in));
printf("----- data ----\n");
printf("%.*s\n", (int)evbuffer_get_length(in), evbuffer_pullup(in, -1));
bufferevent_write_buffer(bev, in);
}
static void
ssl_acceptcb(struct evconnlistener *serv, int sock, struct sockaddr *sa,
int sa_len, void *arg)
{
struct event_base *evbase;
struct bufferevent *bev;
SSL_CTX *server_ctx;
SSL *client_ctx;
server_ctx = (SSL_CTX *)arg;
client_ctx = SSL_new(server_ctx);
evbase = evconnlistener_get_base(serv);
bev = bufferevent_openssl_socket_new(evbase, sock, client_ctx,
BUFFEREVENT_SSL_ACCEPTING,
BEV_OPT_CLOSE_ON_FREE);
bufferevent_enable(bev, EV_READ);
bufferevent_setcb(bev, ssl_readcb, NULL, NULL, NULL);
}
static SSL_CTX *
evssl_init(void)
{
SSL_CTX *server_ctx;
/* Initialize the OpenSSL library */
SSL_load_error_strings();
SSL_library_init();
/* We MUST have entropy, or else there's no point to crypto. */
if (!RAND_poll())
return NULL;
server_ctx = SSL_CTX_new(SSLv23_server_method());
if (! SSL_CTX_use_certificate_chain_file(server_ctx, "cert") ||
! SSL_CTX_use_PrivateKey_file(server_ctx, "pkey", SSL_FILETYPE_PEM)) {
puts("Couldn't read 'pkey' or 'cert' file. To generate a key\n"
"and self-signed certificate, run:\n"
" openssl genrsa -out pkey 2048\n"
" openssl req -new -key pkey -out cert.req\n"
" openssl x509 -req -days 365 -in cert.req -signkey pkey -out cert");
return NULL;
}
SSL_CTX_set_options(server_ctx, SSL_OP_NO_SSLv2);
return server_ctx;
}
int
main(int argc, char **argv)
{
SSL_CTX *ctx;
struct evconnlistener *listener;
struct event_base *evbase;
struct sockaddr_in sin;
memset(&sin, 0, sizeof(sin));
sin.sin_family = AF_INET;
sin.sin_port = htons(9999);
sin.sin_addr.s_addr = htonl(0x7f000001); /* 127.0.0.1 */
ctx = evssl_init();
if (ctx == NULL)
return 1;
evbase = event_base_new();
listener = evconnlistener_new_bind(
evbase, ssl_acceptcb, (void *)ctx,
LEV_OPT_CLOSE_ON_FREE | LEV_OPT_REUSEABLE, 1024,
(struct sockaddr *)&sin, sizeof(sin));
event_base_loop(evbase, 0);
evconnlistener_free(listener);
SSL_CTX_free(ctx);
return 0;
}
关于线程和 OpenSSL 的一些说明
Libevent 的内置线程机制不包括 OpenSSL 锁定。 由于 OpenSSL 使用无数的全局变量，因此您仍必须进行配置 OpenSSL 是线程安全的。虽然此过程超出了 Libevent 的范围， 这个话题足以引起讨论。
示例：如何启用线程安全 OpenSSL 的非常简单的示例
/*
* Please refer to OpenSSL documentation to verify you are doing this correctly,
* Libevent does not guarantee this code is the complete picture, but to be used
* only as an example.
*/
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <pthread.h>
#include <openssl/ssl.h>
#include <openssl/crypto.h>
pthread_mutex_t * ssl_locks;
int ssl_num_locks;
#ifndef WIN32
#define _SSLtid (unsigned long)pthread_self()
#else
#define _SSLtid pthread_self().p
#endif
/* Implements a thread-ID function as requied by openssl */
#if OPENSSL_VERSION_NUMBER < 0x10000000L
static unsigned long
get_thread_id_cb(void)
{
return _SSLtid;
}
#else
static void
get_thread_id_cb(CRYPTO_THREADID *id)
{
CRYPTO_THREADID_set_numeric(id, _SSLtid);
}
#endif
static void
thread_lock_cb(int mode, int which, const char * f, int l)
{
if (which < ssl_num_locks) {
if (mode & CRYPTO_LOCK) {
pthread_mutex_lock(&(ssl_locks[which]));
} else {
pthread_mutex_unlock(&(ssl_locks[which]));
}
}
}
int
init_ssl_locking(void)
{
int i;
ssl_num_locks = CRYPTO_num_locks();
ssl_locks = malloc(ssl_num_locks * sizeof(pthread_mutex_t));
if (ssl_locks == NULL)
return -1;
for (i = 0; i < ssl_num_locks; i++) {
pthread_mutex_init(&(ssl_locks[i]), NULL);
}
#if OPENSSL_VERSION_NUMBER < 0x10000000L
CRYPTO_set_id_callback(get_thread_id_cb);
#else
CRYPTO_THREADID_set_callback(get_thread_id_cb);
#endif
CRYPTO_set_locking_callback(thread_lock_cb);
return 0;
}
原文档地址：https://libevent.org/libevent-book/Ref6_bufferevent.html