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置为内存块的长度。

        如果len小于0，则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