Libevent：9Evbuffers缓存IO的实用功能

Libevent的evbuffer功能实现了一个字节队列，优化了在队列尾端增加数据，以及从队列前端删除数据的操作。

Evbuffer用来实现缓存网络IO中的缓存部分。它们不能用来在条件发生时调度IO或者触发IO：这是bufferevent做的事情。

本章介绍的函数，除了特别注明的，都是在文件“event2/buffer.h”中声明。

一：创建或者释放evbuffer

struct  evbuffer  *evbuffer_new(void);

void  evbuffer_free(struct  evbuffer *buf);

evbuffer_new分配并且返回一个新的空evbuffer，evbuffer_free删除evbuffer及其所有内容。

二：evbuffer和线程安全

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

void  evbuffer_lock(struct  evbuffer  *buf);

void  evbuffer_unlock(struct  evbuffer  *buf);

默认情况下，同一时间在多个线程中访问evbuffer是不安全的。如果需要多线程使用evbuffer，可以在evbuffer上调用evbuffer_enable_locking函数。如果lock参数为NULL，则Libevent使用提供给      
        evthread_set_lock_creation_callback的锁创建函数来分配一个新锁。否则，使用该参数作为新锁。

evbuffer_lock() 和evbuffer_unlock()函数在evbuffer上进行加锁和解锁。可以使用它们将一些操作原子化。如果evbuffer上没有使能锁机制，则这些函数不做任何事。

注意：不需要在单个操作上调用evbuffer_lock()和 evbuffer_unlock()：如果evbuffer上使能了锁机制，单个操作已经是原子性的了。只在有多余一个操作需要执行，且不希望其他线程打断时，才需要手动锁住evbuffer。

三：检查evbuffer

size_t  evbuffer_get_length(const  struct  evbuffer *buf);

该函数返回evbuffer中存储的字节数。

size_t  evbuffer_get_contiguous_space(const  struct  evbuffer *buf);

该函数返回evbuffer前端的连续存储的字节数。evbuffer中的字节存储在多个分离的内存块中；该函数返回当前存储在evbuffer中的第一个内存块中的字节数。

四：向evbuffer中添加数据：基础

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

该函数向buf的末尾添加缓冲区data中的datlen个字节。该函数成功时返回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中添加格式化的数据。format参数以及后续的其他参数类似于C库中的printf和vprintf函数中的参数。这些函数返回添加到buf中的字节数。

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

扩展evbuffer的可用空间，该函数会改变buffer中的最后一个内存块，或者添加一个新的内存块，将buffer的可用空间扩展到至少datlen个字节。扩展buffer到足够大，从而在不需要进行更多的分配情况下就能容纳datlen个字节。

/* Here are two ways to add"Hello world 2.0.1" to a buffer. */

/* Directly: */

evbuffer_add(buf,  "Hello world 2.0.1",  17);

/* Via printf: */

evbuffer_add_printf(buf,  "Hello %s %d.%d.%d",  "world", 2, 0, 1);

五：evbuffer之间的数据移动

基于性能的考虑，Libevent优化了在evbuffer间移动数据的功能。

int  evbuffer_add_buffer(struct  evbuffer *dst,  struct  evbuffer*src);

int  evbuffer_remove_buffer(struct  evbuffer *src,  struct  evbuffer *dst,

size_t  datlen);

evbuffer_add_buffer函数将src中的所有数据移动到dst的尾端。该函数成功时返回0，失败时返回-1.

evbuffer_remove_buffer函数将src中的datlen个字节的数据移动到dst的末尾，并且尽量少的复制。如果数据量少于datlen，则移动所有数据。该函数返回移动的数据量。

六：向evbuffer的前端添加数据

int  evbuffer_prepend(struct  evbuffer  *buf,  const void  *data,  size_t size);

int  evbuffer_prepend_buffer(struct  evbuffer  *dst,  struct evbuffer *  src);

这些函数类似于evbuffer_add()和 evbuffer_add_buffer()，只不过它们是将数据移动到目标buffer的前端。

这些函数要小心使用，不能用在由bufferevent共享的evbuffer上。

七：重新安排evbuffer的内部布局

有时候希望能够查看（但不取出）evbuffer前端的前N个字节，并将其视为一个连续存储的数组。为此，必须首先保证buffer的前端确实是连续的。

unsigned  char  *evbuffer_pullup(struct evbuffer  *buf,  ev_ssize_t size);

evbuffer_pullup函数将buf的最前面的size个字节“线性化”，通过对其复制或者移动，保证这些字节的连续性并且都存储在同一个内存块中。如果size是个负数，则该函数会将整个buffer进行线性化。如果size大于buffer中的字节数，则该函数返回NULL，否则，该函数返回指向第一个字节的指针。

以一个较大的size调用evbuffer_pullup会很慢，因为可能需要复制整个buffer的内容。

#include  <event2/buffer.h>

#include  <event2/util.h>

#include  <string.h>

int  parse_socks4(struct  evbuffer  *buf,  ev_uint16_t  *port,  ev_uint32_t *addr)

{

/* Let's parse the start of a SOCKS4request!  The format is easy:

* 1 byte of version, 1 byte of command, 2bytes destport, 4 bytes of

* destip. */

unsigned  char  *mem;

mem = evbuffer_pullup(buf,  8);

if (mem == NULL) {

/*Not enough data in the buffer */

return 0;

} else if (mem[0] != 4 || mem[1] != 1) {

/* Unrecognized protocol or command */

return -1;

} else {

memcpy(port,  mem+2,  2);

memcpy(addr,  mem+4,  4);

*port = ntohs(*port);

*addr = ntohl(*addr);

/* Actually remove the data from thebuffer now that we know we

like it. */

evbuffer_drain(buf, 8);

return 1;

}

}

注意，使用evbuffer_get_contiguous_space的返回值作为size，调用evbuffer_pullup，则不会引起任何字节的复制或者移动。

八：从evbuffer中移除数据

int  evbuffer_drain(struct  evbuffer  *buf,  size_t len);

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

evbuffer_remove函数复制并且移动buf前端的datlen个字节到data中。如果buf中的字节数少于datlen个，则该函数会复制所有的字节。该函数失败返回-1，否则返回复制的字节数。

evbuffer_drain()函数类似于evbuffer_remove，不同的是它不复制任何数据，而只是删除buffer前端的数据。该函数成功返回0，失败返回-1。

九：复制evbuffer中的数据

有时希望只是复制buffer前端的数据而不删除它。比如，你可能希望确认某种类型的完整记录是否已经到达，而不删除任何数据（就像evbuffer_remove的动作），也不对buffer内部做任何重新部署（就像evbuffer_pullup那样）

ev_ssize_t  evbuffer_copyout(struct  evbuffer  *buf,  void *data,  size_t  datlen);

ev_ssize_t  evbuffer_copyout_from(struct  evbuffer  *buf,

const  struct  evbuffer_ptr *pos,

void  *data_out,  size_t  datlen);

evbuffer_copyout函数类似于evbuffer_remove，但是并不删除buffer中的任何数据。也就是说，它只是复制buf前端的前datlen个字节到data中。如果buffer中少于datlen个字节，则该函数复制所有存在的字节。该函数失败时返回-1，成功时返回复制的字节数。

evbuffer_copyout_from函数类似于evbuffer_copyout，但它不是复制buffer前端的数据，而是以pos指明的位置为起点进行复制。参考“在evbuffer中搜索”一节，查看evbuffer_ptr结构的更多信息。

如果从buffer中复制数据太慢，则可以使用evbuffer_peek函数。

#include  <event2/buffer.h>

#include  <event2/util.h>

#include  <stdlib.h>

#include  <stdlib.h>

int  get_record(struct  evbuffer  *buf,  size_t *size_out,  char  **record_out)

{

/* Let's assume that we're speaking someprotocol where records

containa 4-byte size field in network order, followed by that

number of bytes.  We will return 1 and set the 'out' fields ifwe

have a whole record, return 0 if the recordisn't here yet, and

-1 on error.  */

size_t  buffer_len = evbuffer_get_length(buf);

ev_uint32_t  record_len;

char  *record;

if (buffer_len < 4)

return 0; /* The size field hasn'tarrived. */

/* We use evbuffer_copyout here so that thesize field will stay on

the buffer for now. */

evbuffer_copyout(buf,  &record_len,  4);

/* Convert len_buf into host order. */

record_len = ntohl(record_len);

if (buffer_len  <  record_len+ 4)

return 0; /* The record hasn't arrived*/

/* Okay, _now_ we can remove the record. */

record = malloc(record_len);

if (record == NULL)

return -1;

evbuffer_drain(buf,  4);

evbuffer_remove(buf,  record,  record_len);

*record_out = record;

*size_out = record_len;

return 1;

}

十：基于行的输入

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的前端取出一行，并且将其复制返回到一个新的以NULL为结尾的字符串中。如果n_read_out非空，则将*n_read_out置为返回字符串的长度。如果buffer中没有可读的一整行，则该函数返回NULL。注意，行结束符不包含在返回的复制字符串中。

evbuffer_readln函数可以处理4种行结束符：

EVBUFFER_EOL_LF：行末尾是单个的换行符（也就是“\n”，ASCII值为0x0A）；

EVBUFFER_EOL_CRLF_STRICT：行末尾是回车符和换行符。（也就是”\r\n”，他们的ASCII码分别为0x0D  0x0A）。

EVBUFFER_EOL_CRLF：行末尾是一个可选的回车符，跟着一个换行符。（也就是说，是”\r\n”或者”\n”）。这种格式在解析基于文本的互联网协议中是很有用的，因为一般而言，协议标准都规定以”\r\n”作为行结束符，但是不符合标准的客户端有时候会使用”\n”。

EVBUFFER_EOL_ANY：行的结尾是任何顺序任何数量的回车符和换行符。这种格式不太常用，它的存在只是为了向后兼容性。

EVBUFFER_EOL_NUL：行结束符是单个的0字节，也就是ASCII中的NULL字节。

注意，如果使用了event_set_mem_functions函数替代默认的malloc，则函数evbuffer_readln 返回的字符串将由指定的malloc替代函数进行分配。

char  *request_line;

size_t  len;

request_line =evbuffer_readln(buf,  &len,  EVBUFFER_EOL_CRLF);

if (!request_line) {

/*The first line has not arrived yet. */

} else {

if (!strncmp(request_line,  "HTTP/1.0 ",  9)) {

/* HTTP 1.0 detected ... */

}

free(request_line);

}

十一：在evbuffer中搜索

evbuffer_ptr结构指向evbuffer内部的某个位置，该结构包含可以用来遍历evbuffer的成员。

struct  evbuffer_ptr {

ev_ssize_t  pos;

struct {

/* internal fields */

} _internal;

};

pos成员是唯一公开的成员；其他成员不能在用户代码中使用。pos指向相对于evbuffer首地址的偏移位置。

struct  evbuffer_ptr  evbuffer_search(struct  evbuffer  *buffer,

const  char  *what, size_t  len,  const struct  evbuffer_ptr  *start);

struct  evbuffer_ptr  evbuffer_search_range(struct  evbuffer  *buffer,

const  char  *what, size_t  len,  const struct  evbuffer_ptr  *start,

const  struct  evbuffer_ptr *end);

struct  evbuffer_ptr  evbuffer_search_eol(struct  evbuffer  *buffer,

struct  evbuffer_ptr  *start,  size_t  *eol_len_out,

enum  evbuffer_eol_style  eol_style);

evbuffer_search函数在buffer中扫描长度为len的what字符串的位置。如果能找到该字符串，则返回的evbuffer_ptr结构中的pos指明该字符串的位置，否则pos为-1。如果提供了start参数，则该参数指定开始搜索的位置；如果没有提供，则表明从从buffer的开头开始搜索。

evbuffer_search_range函数类似于evbuffer_search，但它只在buffer中end参数指明的位置之前进行搜索。

evbuffer_search_eol函数，类似于evbuffer_readlen，探测行结束符，只是该函数并不复制该行。该函数返回evbuffer_ptr结构，其中的pos指明了行结束符的起始地址。如果eol_len_out不是NULL，则其被置为EOL字符串的长度。

enum  evbuffer_ptr_how {

EVBUFFER_PTR_SET,

EVBUFFER_PTR_ADD

};

int  evbuffer_ptr_set(struct  evbuffer  *buffer,  struct  evbuffer_ptr *pos,

size_t  position,  enum  evbuffer_ptr_how how);

evbuffer_ptr_set函数设置evbuffer_ptr结构pos为buffer中的某个位置。如果how为EVBUFFER_PTR_SET，则pos移动到buffer中的position位置，如果是EVBUFFER_PTR_ADD，则pointer向后移动position个字节。因此，如果pos没有初始化的话，则how参数只能为EVBUFFER_PTR_SET。该函数成功时返回0，失败是返回-1.

#include  <event2/buffer.h>

#include  <string.h>

/*Count the total occurrences of 'str' in 'buf'. */

int  count_instances(struct  evbuffer  *buf,  const char  *str)

{

size_t  len = strlen(str);

int  total= 0;

struct  evbuffer_ptr  p;

if (!len)

/* Don't try to count the occurrencesof a 0-length string. */

return  -1;

evbuffer_ptr_set(buf, &p,  0,  EVBUFFER_PTR_SET);

while (1) {

p = evbuffer_search(buf, str, len,&p);

if (p.pos < 0)

break;

total++;

evbuffer_ptr_set(buf, &p, 1, EVBUFFER_PTR_ADD);

}

return total;

}

警告：任何改变evbuffer以及其布局的调用都会使evbuffer_ptr的值失效，使用失效的evbuffer_ptr是不安全的。

十二：检查数据而不进行复制

有时希望在不复制出数据的情况下读取evbuffer中的数据，而且不对evbuffer内部的内存进行重新部署。有时候希望能够检查evbuffer中部的数据，可以使用下面的接口：

struct  evbuffer_iovec {

void  *iov_base;

size_t  iov_len;

};

int  evbuffer_peek(struct  evbuffer  *buffer,  ev_ssize_t  len,

struct  evbuffer_ptr  *start_at,

struct  evbuffer_iovec  *vec_out,  int  n_vec);

当调用evbuffer_peek函数时，在vec_out中给定一个evbuffer_iovec结构的数组。数组长度为n_vec。该函数设置数组中的结构体，使每个结构体的iov_base都指向evbuffer内部的一个内存块，并且将iov_len置为内存块的长度。

，则evbuffer_peek函数会尽可能的设置所有给定的evbuffer_iovec结构。否则，要么至少填充len个字节到evbuffer_iovec中，要么将所有evbuffer_iovec都填充满。如果该函数能够得到所有请求的字节，则该函数将返回实际使用的evbuffer_iovec结构的个数，否则，它返回为了能得到所有数据而需要的evbuffer_iovec的个数。

如果ptr为NULL，则evbuffer_peek从buffer的起始处开始取数据，否则，从start_at参数开始取数据。

{

/* Let's look at the first two chunks of buf, and writethem to stderr. */

int  n,i;

struct  evbuffer_iovec  v[2];

n = evbuffer_peek(buf,  -1,  NULL, v,  2);

for (i=0;  i<n;  ++i) { /* There might be less than two chunksavailable. */

fwrite(v[i].iov_base,  1,  v[i].iov_len, stderr);

}

}

{

/* Let's send the first 4906 bytes tostdout via write. */

int  n, i, r;

struct  evbuffer_iovec  *v;

size_t  written = 0;

/* determine  how  many chunks  we  need. */

n = evbuffer_peek(buf,  4096,  NULL, NULL,  0);

/* Allocate space for the chunks.  This would be a good time to use

alloca() if you have it. */

v = malloc(sizeof(struct  evbuffer_iovec) * n);

/* Actually fill up v. */

n = evbuffer_peek(buf,  4096,  NULL, v,  n);

for (i=0; i<n; ++i) {

size_t  len = v[i].iov_len;

if (written + len > 4096)

len = 4096 - written;

r = write(1 /* stdout */,  v[i].iov_base,  len);

if (r<=0)

break;

/* We keep track of the bytes writtenseparately; if we don't,

we may write more than 4096 bytes ifthe last chunk puts

us over the limit. */

written += len;

}

free(v);

}

{

/*Let's get the first 16K of data after the first occurrence of the

string "start\n", and pass itto a consume() function. */

struct  evbuffer_ptr ptr;

struct  evbuffer_iovec  v[1];

const  char s[] = "start\n";

int  n_written;

ptr  = evbuffer_search(buf,  s,  strlen(s), NULL);

if (ptr.pos == -1)

return; /* no start string found. */

/* Advance the pointer past the start string.*/

if (evbuffer_ptr_set(buf,  &ptr,  strlen(s),  EVBUFFER_PTR_ADD) < 0)

return; /* off the end of the string.*/

while (n_written < 16*1024) {

/* Peek at a single chunk. */

if (evbuffer_peek(buf, -1, &ptr, v,1) < 1)

break;

/* Pass the data to some user-definedconsume function */

consume(v[0].iov_base,  v[0].iov_len);

n_written  +=  v[0].iov_len;

/* Advance the pointer so we see thenext chunk next time. */

if (evbuffer_ptr_set(buf,  &ptr,  v[0].iov_len,  EVBUFFER_PTR_ADD)<0)

break;

}

}

注意：编辑由evbuffer_iovec指向的数据可能会导致未定义的行为；

如果调用了修改evbuffer的函数，则evbuffer_peek中的指针会变得无效；

如果evbuffer在多线程中使用，则调用evbuffer_peek之前应该使用evbuffer_lock进行加锁，而且一旦使用完evbuffer_peek返回的内存块，则需要解锁

十三：直接向evbuffer中添加数据

如果需要向evbuffer中直接插入数据，而不是像evbuffer_add那样，先写入一个字符数组，然后再将字符数组复制到evbuffer中。可以使用下面的函数：evbuffer_reserve_space() 和evbuffer_commit_space()。类似于evbuffer_peek，这些函数使用evbuffer_iovec结构来直接访问evbuffer中的内存。

int  evbuffer_reserve_space(struct  evbuffer *buf,  ev_ssize_t  size,

struct  evbuffer_iovec  *vec,  int n_vecs);

int  evbuffer_commit_space(struct  evbuffer  *buf,

struct  evbuffer_iovec  *vec,  int n_vecs)

evbuffer_reserve_space函数扩充buf的最后一个内存块的空间，返回evbuffer内部空间的指针。它会将buffer的可用空间扩充到至少size个字节；指向这些扩充的内存块的指针以及内存块长度将会存储在vec结构中，n_vec指明了该数组的长度。

n_vec至少为1，如果只给定了一个vector，则Libevent会保证将所有请求的连续空间填充到一个内存块中，但是这样会对buffer重新布局，或者会浪费内存。如果想要更好的性能，则至少应该提供2个vector，该函数返回请求空间需要的vector个数。

写入到这些vector中的数据，直到调用evbuffer_commit_space之前，都不算是buffer的一部分，该函数会使vector中的数据成为buffer中的数据。如果希望提交少于请求的数据，可以减少任一evbuffer_iovec结构体的iov_len，或者还可以传递较少的vector。evbuffer_commit_space函数成功时返回0，失败时返回-1。

注意：调用任何重新布局evbuffer的函数，或者向evbuffer添加数据，会使得从evbuffer_reserve_space返回的指针变得无效。

在当前的实现中，evbuffer_reserve_space不会使用多余两个的vector，而不管用户提供了多少，或许会在未来版本中有所改变。

调用多次evbuffer_reserve_space是安全的。

如果evbuffer在多线程中使用，则在调用evbuffer_reserve_space函数之前应该使用evbuffer_lock函数进行加锁，并且一旦commit会后就解锁。

/*Suppose  we  want to fill a buffer with 2048 bytes ofoutput from a

generate_data() function, without copying.*/

struct  evbuffer_iovec  v[2];

int  n, i;

size_t  n_to_add = 2048;

/* Reserve 2048 bytes.*/

n = evbuffer_reserve_space(buf, n_to_add,  v,  2);

if (n<=0)

return; /* Unable to reserve the space forsome reason. */

for (i=0;  i<n && n_to_add > 0;  ++i) {

size_t  len = v[i].iov_len;

if (len > n_to_add) /* Don't write morethan n_to_add bytes. */

len = n_to_add;

if (generate_data(v[i].iov_base,  len) < 0) {

/* If there was a problem during datageneration, we can just stop

here; no data will be committed to thebuffer. */

return;

}

/* Set iov_len to the number of bytes weactually wrote, so we

don't commit too much. */

v[i].iov_len = len;

}

/* We commit the spacehere.  Note that we give it 'i' (thenumber of

vectors we actually used) rather than 'n'(the number of vectors we

had available. */

if(evbuffer_commit_space(buf,  v,  i)< 0)

return; /* Error committing */

Bad Examples

/* Here are some mistakes youcan make with evbuffer_reserve().

DO NOT IMITATE THIS CODE. */

struct evbuffer_iovec v[2];

{

/*Do not use thepointers from evbuffer_reserve_space() after

calling any functions that modify thebuffer.*/

evbuffer_reserve_space(buf,  1024,  v, 2);

evbuffer_add(buf, "X", 1);

/* WRONG: This next line won't work ifevbuffer_add needed to rearrange

the buffer's contents.  It might even crash your program.Instead,

you add the data before callingevbuffer_reserve_space. */

memset(v[0].iov_base, 'Y', v[0].iov_len-1);

evbuffer_commit_space(buf, v, 1);

}

{

/*Do not modify theiov_base pointers. */

const char *data = "Here is somedata";

evbuffer_reserve_space(buf, strlen(data), v,1);

/* WRONG: The next line will not do what youwant.  Instead, you

should _copy_ thecontents of data into v[0].iov_base. */

v[0].iov_base = (char*) data;

v[0].iov_len = strlen(data);

/* In this case, evbuffer_commit_space mightgive an error if you're

lucky */

evbuffer_commit_space(buf, v, 1);

}

十四：用evbuffer进行网络IO

Libevent中evbuffer最常见的用途是用来进行网络IO。evbuffer上执行网络IO的接口是：

int  evbuffer_write(struct  evbuffer  *buffer,  evutil_socket_t  fd);

int  evbuffer_write_atmost(struct  evbuffer  *buffer,  evutil_socket_t  fd,

ev_ssize_t  howmuch);

int  evbuffer_read(struct  evbuffer  *buffer,  evutil_socket_t  fd,  int howmuch);

evbuffer_read函数从fd中读取howmuch个字节到buffer的尾端。他返回成功读取的字节数，遇到EOF时返回0，发生错误返回-1。注意发生错误有可能表明一个非阻塞的操作失败了；可以通过检查错误码是否为EAGAIN(在Windows上为WSAEWOULDBLOCK )来确定。如果howmuch参数为负数，则evbuffer_read自己决定读取多少字节。

evbuffer_write_atmost函数尝试从buffer的前端发送howmuch字节到fd上。该函数返回成功写入的字节数，失败时返回-1。与evbuffer_read类似，需要检查错误码确定是否确实发生了错误，还是仅表明非阻塞IO不能立即执行。如果howmuch为负数，则会尝试发送整个buffer的内容。

调用evbuffer_write，等同于以负数howmuch调用函数evbuffer_write_atmost：它会尽可能的刷新buffer。

在Unix上，这些函数可以工作在任何支持读写的文件描述符上，但是在Windows上，仅能用在socket上。

注意，当使用bufferevent时，不需要调用这些IO函数，bufferevent会替你调用他们。

十五：evbuffer和回调函数

使用evbuffer时，经常会想知道数据何时添加到或者移除出evbuffer。Libevent提供了一般性的evbuffer回调机制支持这种需求。

struct  evbuffer_cb_info {

size_t  orig_size;

size_t  n_added;

size_t  n_deleted;

};

typedef  void ( *evbuffer_cb_func)(struct  evbuffer  *buffer,

const  struct  evbuffer_cb_info *info,  void  *arg);

当数据添加到或者移除出evbuffer的时候，就会调用evbuffer 的回调函数。该函数的参数是buffer，指向evbuffer_cb_info结构体的指针，以及一个用户提供的参数。evbuffer_cb_info结构的orig_size成员记录了buffer大小改变之前，buffer中的字节数；n_added成员记录了添加到buffer的字节数；n_deleted记录了移除的字节数。

struct  evbuffer_cb_entry;

struct  evbuffer_cb_entry  *evbuffer_add_cb(struct  evbuffer  *buffer,

evbuffer_cb_func  cb,  void *cbarg);

evbuffer_add_cb函数向evbuffer中添加回调函数，并且返回一个非透明的指针，该指针后续可以用来引用该特定的回调实例。cb参数就是会调用的回调函数，cbarg是用来传递给该函数的用户提供的参数。

在单个evbuffer上可以有多个回调函数，添加新的回调不会删除旧的回调函数。

#include  <event2/buffer.h>

#include  <stdio.h>

#include  <stdlib.h>

/*Here's a callback that remembers how many bytes we have drained in

total from the buffer, and prints a dotevery time we hit a

megabyte. */

struct  total_processed {

size_t  n;

};

void  count_megabytes_cb(struct  evbuffer  *buffer,

const  struct  evbuffer_cb_info  *info,  void *arg)

{

struct  total_processed  *tp = arg;

size_t  old_n = tp->n;

int  megabytes, i;

tp->n += info->n_deleted;

megabytes = ((tp->n) >> 20) -(old_n >> 20);

for (i=0; i<megabytes; ++i)

putc('.', stdout);

}

void  operation_with_counted_bytes(void)

{

struct  total_processed  *tp = malloc(sizeof(*tp));

struct  evbuffer  *buf = evbuffer_new();

tp->n = 0;

evbuffer_add_cb(buf, count_megabytes_cb,  tp);

/* Use the evbuffer for a while.  When we're done: */

evbuffer_free(buf);

free(tp);

}

注意，释放一个非空evbuffer并不算作从中抽取数据，而且释放evbuffer也不会释放其回调函数的用户提供的数据指针。

如果不希望一个回调函数永久的作用在buffer上，可以将其移除（永久移除），或者禁止（暂时关闭）

int  evbuffer_remove_cb_entry(struct  evbuffer  *buffer,

struct  evbuffer_cb_entry  *ent);

int  evbuffer_remove_cb(struct  evbuffer  *buffer,  evbuffer_cb_func  cb,

void  *cbarg);

#define  EVBUFFER_CB_ENABLED  1

int  evbuffer_cb_set_flags(struct  evbuffer  *buffer,

struct  evbuffer_cb_entry  *cb,

ev_uint32_t  flags);

int  evbuffer_cb_clear_flags(struct  evbuffer  *buffer,

struct  evbuffer_cb_entry  *cb,

ev_uint32_t  flags);

可以通过添加时得到的evbuffer_cb_entry来删除回调，或者使用回调函数本身以及用户提供的参数指针来删除回调。evbuffer_remove_cb函数成功时返回0，失败时返回-1。

evbuffer_cb_set_flags和evbuffer_cb_clear_flags函数可以在相应的回调函数上，设置或者移除给定的标志位。当前只支持一个用户可见的标志：EVBUFFER_CB_ENABLED。默认设置该标志，当清除该标志时，evbuffer上的修改不会再调用回调函数了。

 

int  evbuffer_defer_callbacks(struct  evbuffer  *buffer,  struct  event_base *base);

类似于bufferevent的回调函数，可以当evbuffer改变时不立即运行evbuffer的回调，而是使其延迟并作为event_base的event loop的一部分进行调用。如果有多个evbuffer，它们的回调函数会将数据从一个添加（或移除）到另外一个的时候，这种延迟机制是有帮助的，可以避免栈崩溃。

如果evbuffer的回调函数被延迟了，在在其最终调用时，他们会对多个操作的结果进行聚合。

类似于bufferevent，evbuffer有内部引用计数，所以即使evbuffer尚有未执行的延迟回调，释放它也是安全的。

十六：避免在基于evbuffer的IO上复制数据

真正快速的网络程序会尽可能少的复制数据。Libevent提供了一些机制来满足这种需求。

typedef  void (*evbuffer_ref_cleanup_cb)(const  void  *data,

size_t  datalen,  void  *extra);

int  evbuffer_add_reference(struct  evbuffer  *outbuf,

const  void  *data, size_t  datlen,

evbuffer_ref_cleanup_cb  cleanupfn,  void  *extra);

该函数通过引用向evbuffer的尾端添加数据：没有进行复制，相反的，evbuffer仅仅保存指向包含datlen个字节的data的指针。因此，在evbuffer使用它期间，该指针应该保持是有效的。当evbuffer不再需要该数据的时候，它会以data，datlen和extra为参数，调用用户提供的cleanupfn函数。该函数成功时返回0，失败时返回-1。

#include  <event2/buffer.h>

#include  <stdlib.h>

#include  <string.h>

/* In this example, we have a bunch of evbuffers that we want to use to

spool a one-megabyte resource out to thenetwork.  We do this

without keeping any more copies of theresource in memory than

necessary. */

#define  HUGE_RESOURCE_SIZE  (1024*1024)

struct huge_resource {

/* We keep a count of the references thatexist to this structure,

so that we know when we can free it. */

int  reference_count;

char  data[HUGE_RESOURCE_SIZE];

};

struct  huge_resource * new_resource(void) {

struct  huge_resource  *hr = malloc(sizeof(struct  huge_resource));

hr->reference_count= 1;

/* Here we should fill hr->data with something.  In real life,

we'd probably load something or do acomplex calculation.

Here, we'll just fill it with EEs. */

memset(hr->data,  0xEE,  sizeof(hr->data));

return  hr;

}

void  free_resource(struct  huge_resource  *hr) {

--hr->reference_count;

if (hr->reference_count == 0)

free(hr);

}

static  void  cleanup(const void  *data,  size_t len,  void  *arg){

free_resource(arg);

}

/* This is the function thatactually adds the resource to the

buffer. */

voidspool_resource_to_evbuffer(struct  evbuffer *buf,  struct  huge_resource *hr)

{

++hr->reference_count;

evbuffer_add_reference(buf,  hr->data,  HUGE_RESOURCE_SIZE,  cleanup,  hr);

}

十七：向evbuffer中添加文件

一些操作系统提供了将文件写入到网络中，而不需要复制数据到用户空间中的方法。可以通过简单的接口访问这些机制：

int  evbuffer_add_file(struct  evbuffer  *output,  int fd,  ev_off_t  offset,

size_t  length);

evbuffer_add_file函数假设已经有一个用来读的打开的文件描述符fd。该函数从该文件的offset位置开始，读取length个字节，写入到output的尾端。该函数成功时返回0，失败是返回-1。

警告：在Libevent2.0.x中，通过这种方式添加的数据，仅有下面几种操作数据的方式是可靠的：通过evbuffer_write*函数将数据发送到网络中；通过evbuffer_drain函数进行抽取数据，通过evbuffer_*_buffer函数将数据移动到其他evbuffer中。下列操作是不可靠的：通过evbuffer_remove函数从buffer中抽取数据；通过evbuffer_pullup线性化数据等等。Libevent2.1.x会修复这些限制。

如果操作系统支持splice和sendfile函数，则在调用evbuffer_write时，Libevent直接使用这些函数发送fd中的数据到网络中，而不需要将数据复制到用户内存中。如果不存在splice或sendfile函数，但是有mmap函数，则Libevent会对文件做mmap，并且内核会知道不需要将数据复制到用户空间。如果上述函数都不存在的话，则Libevent会将数据从磁盘读取到内存中。

当文件中的数据刷新到evbuffer之后，或者当释放evbuffer时，就会关闭文件描述符。如果不希望关闭文件，或者希望对文件有更细粒度的控制，则可以参考下面的文件段（file_segment）功能。

十八：对文件段（file_segment）进行更细粒度的控制

如果需要多次添加同一个文件，则evbuffer_add_file是低效的，因为它会占有文件的所有权。

struct  evbuffer_file_segment;

struct  evbuffer_file_segment  *evbuffer_file_segment_new(

int fd,  ev_off_t  offset,  ev_off_t  length,  unsigned  flags);

void  evbuffer_file_segment_free(struct  evbuffer_file_segment  *seg);

int  evbuffer_add_file_segment(struct  evbuffer  *buf,

struct  evbuffer_file_segment  *seg,  ev_off_t offset,  ev_off_t  length);

evbuffer_file_segment_new函数创建并返回一个evbuffer_file_segment对象，该对象代表了存储在文件fd中的，以offset为起点，共有length个字节的文件段。该函数如果发生错误时返回NULL。

文件段通过sendfile、splice、mmap、CreateFileMapping或malloc()-and_read()中合适的函数进行实现。它们使用系统支持的最轻量级的机制进行创建，并且在需要的时候会过渡到重量级的机制上。（比如，如果系统支持sendfile和mmap，则会仅使用sendfile实现文件段，直到真正需要检查文件段内容时，在这一刻，会使用mmap），可以通过下列标志更加细粒度的控制文件段的行为：

EVBUF_FS_CLOSE_ON_FREE：如果设置了该标志，则通过函数evbuffer_file_segment_free释放文件段将会关闭底层文件。

EVBUF_FS_DISABLE_MMAP：如果设置了该标志，则文件段将永远不会使用mmap类型的后端（CreateFileMapping，mmap），即使它们非常合适。

EVBUF_FS_DISABLE_SENDFILE：如果设置了该标志，则文件段将永远不会使用sendfile类型的后端（sendfile，splice），即使它们非常合适。

EVBUF_FS_DISABLE_LOCKING：如果设置了该标志，则不会在文件段上分配锁：在多线程环境中使用文件段将是不安全的。

一旦得到一个evbuffer_file_segment结构，则可以使用evbuffer_add_file_segment函数将其中的一部分或者所有内容添加到evbuffer中。这里的offset参数是指文件段内的偏移，而不是文件内的偏移。

当不再使用文件段时，可以通过evbuffer_file_segment_free函数进行释放。但是其实际的存储空间不会释放，直到再也没有任何evbuffer持有文件段部分数据的引用为止。

typedef  void (*evbuffer_file_segment_cleanup_cb)(

struct  evbuffer_file_segment  const  *seg, int  flags,  void *arg);

void  evbuffer_file_segment_add_cleanup_cb(struct  evbuffer_file_segment  *seg,

evbuffer_file_segment_cleanup_cb  cb,  void *arg);

可以在文件段上添加一个回调函数，当文件段的最后一个引用被释放，并且文件段被释放时，该回调函数被调用。该回调函数决不能在试图重新将该文件段添加到任何buffer上。

十九：通过引用将evbuffer添加到另一个evbuffer中

可以通过引用将evbuffer添加到另一个evbuffer中：而不是移动一个evbuffer中内容到另一个evbuffer中，当将evbuffer的引用添加到另一个evbuffer中时，它的行为类似于复制了所有字节。

int  evbuffer_add_buffer_reference(struct  evbuffer  *outbuf,

struct  evbuffer  *inbuf);

evbuffer_add_buffer_reference函数的行为类似于复制outbuf中的所有数据到inbuf中，但是它却不会执行任何不必要的复制。该函数成功时返回0，失败是返回-1。

注意，inbuf内容后续的变化将不会反馈到outbuf中：该函数是通过引用添加evbuffer当前的内容，而不是evbuffer本身。

注意，不能嵌套buffer的引用：如果一个evbuffer是evbuffer_add_buffer_reference函数中的outbuf，则其不能作为另一个的inbuf。

二十：使一个evbuffer仅能添加或者仅能移除

int  evbuffer_freeze(struct  evbuffer  *buf,  int at_front);

int  evbuffer_unfreeze(struct  evbuffer  *buf,  int at_front);

可以使用这些函数暂时性的禁止evbuffer前端或后端的改变。bufferevent会在内部使用这些函数，用来防止输出缓冲区前端，或者输入缓冲区后端的意外改变。

二十一：过时的evbuffer函数

在Libevent2.0中，evbuffer的接口发生了很多变化。在此之前，每一个evbuffer都是通过一连续的内存块实现的，这使得访问非常低效。

event.h头文件以前会暴露evbuffer结构的内部，但是现在不会了；在1.4到2.0之前，任何依赖于它们进行工作的代码都被改变了。

为了访问evbuffer中的字节数，使用EVBUFFER_LENGTH宏，使用EVBUFFER_DATA()宏得到实际的数据。这些宏都定义在event2/buffer_compat.h中。小心，EVBUFFER_DATA(b)是evbuffer_pullup(b,-1)的别名，它是非常昂贵的。

下面的接口已经不推荐使用了：

char  *evbuffer_readline(struct  evbuffer *buffer);

unsigned  char  *evbuffer_find(struct  evbuffer  *buffer,

const  unsigned  char  *what,  size_t len);

evbuffer_readline函数类似于当前的evbuffer_readln(buffer,NULL, EVBUFFER_EOL_ANY)。

evbuffer_find()函数会寻找buffer中what字符串的第一次出现，并且返回指向它的指针。不像evbuffer_search，它只会寻找第一个匹配的字符串。为了兼容仍使用该函数的老代码，它现在会将直到本地字符串的结尾的整个buffer进行线性化。

回调的接口也不再相同（废弃的接口）：

typedef  void  (*evbuffer_cb)(struct evbuffer  *buffer,

size_t  old_len,  size_t  new_len, void  *arg);

void  evbuffer_setcb(struct  evbuffer  *buffer,  evbuffer_cb  cb,  void *cbarg);

同一时刻一个evbuffer只能有一个回调函数，所以设置新的回调函数会移除前一个回调，并且设置回调为NULL，则是移除回调函数的首选方法。

不再是取得evbuffer_cb_info_structure结构，该函数以evbuffer的旧长度和新长度来调用。因此，如果old_len大于new_len，则数据被抽取，如果new_len大于old_len，则数据被添加。不能将回调延迟，所以，在一次回调中不能将添加和删除进行批量化。

这些过时的函数仍然定义在event2/buffer_compat.h中。

http://www.wangafu.net/~nickm/libevent-book/Ref7_evbuffer.html