12、《Libevent中文帮助文档》学习笔记12：evbufferIO实用功能

LibEvent的bufferevent实现了向后添加数据和前面移除数据的优化字节序列。evbuffer用于处理完IO的缓冲部分。它不提供调度IO或当IO就绪时触发IO的功能：这就是bufferevent所做的事。
除了特定说明外，本章的函数定义在<event2/buffer.h>中。

1 创建或释放一个evbuffer

接口

struct evbuffer* evbuffer_new(void); void evbuffer_free(struct evbuffer* buf);

这些函数应该相当清晰：evbuffer_new()分配了一个空的evbuffer，evbuffer_free()删除一个或全部的内容。

2 evbuffer和线程安全

接口

int evbuffer_enable_locking(struct evbuffer* buf, void * lock); 
void evbuffer_lock(struct evbuffer* buf); 
void evbuffer_unlock(struct evbuffer* buf);

默认情况下，在多个线程中同时访问evbuffer是不安全的。如果需要这样的访问，可以调用evbuffer_enable_locking()。如果lock参数为NULL，libevent会使用evthread_set_lock_creation_callback提供的锁创建函数创建一个锁。否则，libevent将lock参数用作锁。
evbuffer_lock()和evbuffer_unlock()函数分别请求和释放evbuffer上的锁，可以使用这两个函数让一系列操作是原子的。如果evbuffer没有启用锁，这两个函数不做任何操作。(注意：对于单个操作，不需要调用evbuffer_lock()和evbuffer_unlock()；如果evbuffer启用了锁，单个操作就已经是原子的。只有在需要多个操作连续执行，不让其线程介入的时候，才需要手动锁evbuffer)

3 检查evbuffer

接口

size_t evbuffer_get_length(const struct evbuffer* buf);

这个函数返回evbuffer存储的字节数。

接口

size_t evbuffer_get_contiguous_space(const struct evbuffer* buf);

这个函数返回连续地存储在evbuffer前面的字节数。evbuffer中的数据可能存储在多个分隔开的内存块中。这个函数返回当前第一个块中的字节数。

4 向evbuffer添加数据

接口

int evbuffer_add(struct evbuffer* buf, const void * data, size_t datlen);

这个函数添加data处的datalen字节到buf的末尾，成功时返回0，失败时返回-1。

接口

int evbuffer_add_printf(struct evbuffer* buf, const char * fmt, ...);
int evbuffer_add_vprintf(struct evbuffer* buf, const char * fmt, va_list ap);

这些函数添加格式化的数据到buf末尾。格式参数和其他参数的处理分别与C库函数printf和vprintf相同。函数返回添加的字节数。

接口

int evbuffer_expand(struct evbuffer* buf, size_t datlen);

这个函数修改缓冲区的最后一块，或者添加一个新的块，使得缓冲区足以容纳datlen字节，而不需要更多的内存分配。

5 将数据从一个Evbuffer移动到另一个 

待补充。

6 添加数据到Evbuffer的前面

待补充。

7 重新排列evbuffer的内部布局

待补充。

8 从evbuffer移除数据

待补充。

9 从evbuffer中复制出数据

待补充。

10 面向行的输入

接口

enum evbuffer_eol_style 
{ 
    EVBUFFER_EOL_ANY, 
    EVBUFFER_EOL_CRLF, 
    EVBUFFER_EOL_CRLF_STRICT, 
    EVBUFFER_EOL_LF, 
    EVBUFFER_EOL_NUL
}; 

char* evbuffer_readln(struct evbuffer * buffer, size_t * n_read_out, enum evbuffer_eol_style eol_style);

很多互联网协议使用基于行的格式。evbuffer_readln()函数从evbuffer前面取出一行，用一个新分配的空字符结束的字符串返回这一行。如果n_read_out不是NULL，则它被设置为返回的字符串的字节数。如果没有整行供读取，函数返回空。返回的字符串不包括行结束符。

evbuffer_readln()理解4种行结束格式：

• EVBUFFER_EOL_LF：行尾是单个换行符(也就是\n，ASCII 值是 0x0A)；
• EVBUFFER_EOL_CRLF_STRICT：行尾是一个回车符，后随一个换行符(也就是\r\n，ASCII值是0x0D0x0A)
• EVBUFFER_EOL_CRLF：行尾是一个可选的回车。后随一个换行符(也就是说，可以是\r\n或者\n)。这种格式对于解析基于文本的互联网协议很有用，因为标准通常要求\r\n的行结束符，而不遵循标准的客户端有时候只使用\n。
• EVBUFFER_EOL_ANY：行尾是任意数量、任意次序的回车和换行符。这种格式不是特别有用，它的存在主要是为了向后兼容。

11 在evbuffer中搜索

待补充。

12 检测数据而不复制

待补充。

13 直接向evbuffer添加数据

待补充。

14 使用evbuffer的网络IO

待补充。

15 evbuffer和回调

待补充。

16 为基于evbuffer的IO避免数据复制

待补充。

17 增加一个文件到evbuffer

待补充。

18 细粒度控制文件段

待补充。

19 添加一个evbuffer引用到另一个evbuffer

待补充。

20 让evbuffer只能添加和删除

待补充。