libevent简介[翻译]11 Evbuffers：缓冲IO的功能函数

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

Libevent的evbuffer函数实现了一个字节队列，用来优化从尾部增加数据从头部删除数据的性能。

Evbuffers经常用作网络IO缓冲。你不用提供函数管理IO或是在IO准备好的时候触发，这就是bufferevents所做的事。

创建和释放evbuffer

接口

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

这个函数非常简单清晰了，evbuffer_new()申请创建并返回一个空的evbuffer，evbuffer_free()删除里面所有的内容。

Evbuffers和线程安全

接口

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

默认情况下，多线程同时访问evbuffer是不安全的，可以在evbuffer上调用evbuffer_enable_locking()。如果lock参数是NULL，libevent会申请一个新的lock，并且用这个lock创建一个函数，提供给evthread_set_lock_creation_callback。如果lock不是NULL，那就是用传递的lock。

evbuffer_lock()和evbuffer_unlock()用来请求和释放evbuffer上的锁。你可以使用它们保证操作的原子性。如果没有lock，函数不会有任何作用。

注意，你不需要在每个操作都调用evbuffer_lock()和evbuffer_unlock()，因为如果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增加数据

接口

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

这个函数消耗datlen的长度在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的后面附加格式化的数据。

接口

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

这个函数修改最后一个块的内存，或是增加一个新的块，这样buffer就有足够大的空间而不用重新申请了。

示例

/* 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已经又花了移动数据的函数

接口

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

evbuffer_remove_buffer()移动最多datlen的数据从dst到src。

在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前面。

重新排列evbuffer内部的层

有时候你想看evbuffer前面的N个字节的数据，把它看做一个连续的整体。如果你要这么做，你必须保证前N个字节的数据是连续的。

接口

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

evbuffer_pullup()函数线性化buf第一个空间的字节，拷贝或是移动他们，确保他们都是在同一个块的连续内存。如果空间大于buffer，就返回NULL，否则返回第一个字节的地址。

如果数据很多，调用evbuffer_pullup()会非常慢，因为需要拷贝数据

示例

#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 SOCKS4 request!  The format is easy:
     * 1 byte of version, 1 byte of command, 2 bytes 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 the buffer now that we know we
           like it. */
        evbuffer_drain(buf, 8);
        return 1;
    }
}

注意

调用evbuffer_pullup()如果size的大小等于evbuffer_get_contiguous_space()的返回值将不会拷贝或移动任何数据。

从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的字节并且拷贝到内存。如果比datlen的长度小，那就全部拷贝。出错返回-1，正常返回拷贝的字节数。

evbuffer_drain()和evbuffer_remove()行为一样，但是，它不拷贝数据：仅仅是从buffer前面删除数据。

从evbuffer拷贝数据出来

有时候你想从buffer前面拷贝数据出来并且不想删除它。比如，你想看看某些数据是否达到，而不想删除数据，或者内部重新排列数据。

接口

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删除数据。也就是把钱datlen的数据从buf前面拷贝到内存。如果数据比datlen少，就拷贝全部的，出错返回-1，成功返回拷贝的字节数。

evbuffer_copyout_from()的行为和evbuffer_copyout()类似，但是不是从buffer的前面拷贝字节，二是从pos指定的位置拷贝字节。

如果拷贝数据太慢，可以使用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 some protocol where records
       contain a 4-byte size field in network order, followed by that
       number of bytes.  We will return 1 and set the 'out' fields if we
       have a whole record, return 0 if the record isn'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't arrived. */

   /* We use evbuffer_copyout here so that the size 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的前面提取一行数据，然后返回一个新创建的NUL结尾的字符串。如果n_read_out不是NULL，*n_read_out就指向了字符串返回的长度。如果不是整行被读取，那么就返回NULL，行结束符并不在拷贝的字符串内。

evbuffer_readln()有4中结束格式：

• EVBUFFER_EOL_LF

结束是一个换行符，也就是" "。ASCII是0x0A

• EVBUFFER_EOL_CRLF_STRICT

结束是一个回车符，也就是" "，ASCII是0x0D 0x0A

• EVBUFFER_EOL_CRLF

结束是一个可选的回车符，跟在换行符后面，也就是可以是" "或" "。这个格式在解析基于文本的Internet协议时非常有用。因为有的是标准的" "结束，而有的是" "

• EVBUFFER_EOL_ANY

结束是任何组合的换行符和回车符，这个格式不太有用，仅仅是为了兼容性。

• EVBUFFER_EOL_NUL

结束是一个数据0，也就是ASCII的NUL

注意，如果使用event_set_mem_functions()代替默认的malloc，字符串通过evbuffer_readln返回，将会通过你自己定义的申请函数替换

示例

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是唯一公共的字段。另一个不能在你代码中使用。它指向一个evbuffer从开始到offset的位置

接口

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中的内容，查找到匹配what中字符串的位置。返回evbuffer_ptr指向字符串的位置，如果没找到，返回-1.如果start参数提供了，就指定了在查找开始的位置，否则，从字符串开始查找。

evbuffer_search_range()和evbuffer_search行为类似，只是值查找end之前的数据。

evbuffer_search_eol()函数发现行结束的数据，与evbuffer_readln()类似，只不过不拷贝数据，而是返回这一行数据的开头位置。如果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操作pos位置的数据。如果how是EVBUFFER_PTR_SET，指针就指向buffer中一个绝对的位置；如果是EVBUFFER_PTR_ADD，就向前移动position字节。

示例

#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 occurrences of 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或是layout的调用都会是evbuffer_ptr无效，并且不能安全使用。

不拷贝数据来检查数据

有时候你想读取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()的时候，你需要给一个evbuffer_iovec的结构体，用vec_out传递进来。这个数组的长度是n_vec。它设置这些结构体，每一个都包指向evbuffer在内存中（iov_base）的块，并且长度也设置在哪个块中。

如果len比0小，evbuffer_peek()就会试着填满所有的evbuffer_iovec结构体。否则，它会不断的填满它们，知道所有的都被使用了，或者len的字节是可见的。如果函数可以给你所有的你请求的数据，它会返回使用的evbuffer_iovec结构体的数量。否则，返回可能需要的数量。

如果ptr是NULL，evbuffer_peek()从buffer第一个位置开始，否则，从ptr指定的位置开始

示例

{
    /* Let's look at the first two chunks of buf, and write them 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 chunks available. */
        fwrite(v[i].iov_base, 1, v[i].iov_len, stderr);
    }
}

{
    /* Let's send the first 4906 bytes to stdout 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 written separately; if we don't,
           we may write more than 4096 bytes if the 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
", and pass it to a consume() function. */
    struct evbuffer_ptr ptr;
    struct evbuffer_iovec v[1];
    const char s[] = "start
";
    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-defined consume function */
        consume(v[0].iov_base, v[0].iov_len);
        n_written += v[0].iov_len;

        /* Advance the pointer so we see the next 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添加数据

有时候你想直接想evbuffer添加数据，而不是先写入到一个字符串数组，然后再通过evbuffer_add()添加到里面。有一对函数可以做到这个：`evbuffer_reserve_space()`和`evbuffer_commit_space()`。和`evbuffer_peek()`一样，这两个函数使用evbuffer_iovec结构体来直接访问内存中的evbuffer。

**接口**

```cpp
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()提供了指向evbuffer内部空间的指针。它把buffer扩充到至少能满足你提供的size大小。这个指针指向扩充的位置，并且他的长度，会被保存到你传入的vec vectores数组中。n_vec是数组的长度

n_vec至少是1.如果只提供了一个vector，libevent将会保证你有一个连续的空间，但是可能会重新分配buffer或是浪费内存。为了性能，最好提供2个vecotre。函数返回你请求的vector使用的个数。

你写入到vector中的数据并不会称为buffer的一元，需要调用evbuffer_commit_space()，使得数据写入到buffer。如果你想提交比你少的数据，你可以减少iov_len。你可以同样传入比你提供少的vector。

注意和说明

• 调用函数重新排列evbufer或是添加数据会是通过evbuffer_reserve_space()获取的指针失效

• 当前的实现，evbuffer_reserve_space()不会使用超过两个vector，不管你提供了多少，这个会在未来解决

• 任何时候调用evbuffer_reserve_space()都是安全的

• 如果你的evbuffer在多线程中使用，确保调用evbuffer_lock()来加锁，并且在提交后释放锁。

示例

/* Suppose we want to fill a buffer with 2048 bytes of output 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 for some 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 more than n_to_add bytes. */
      len = n_to_add;
   if (generate_data(v[i].iov_base, len) < 0) {
      /* If there was a problem during data generation, we can just stop
         here; no data will be committed to the buffer. */
      return;
   }
   /* Set iov_len to the number of bytes we actually wrote, so we
      don't commit too much. */
   v[i].iov_len = len;
}

/* We commit the space here.  Note that we give it 'i' (the number 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 */

错误的示例

/* Here are some mistakes you can make with evbuffer_reserve().
   DO NOT IMITATE THIS CODE. */
struct evbuffer_iovec v[2];

{
  /* Do not use the pointers from evbuffer_reserve_space() after
     calling any functions that modify the buffer. */
  evbuffer_reserve_space(buf, 1024, v, 2);
  evbuffer_add(buf, "X", 1);
  /* WRONG: This next line won't work if evbuffer_add needed to rearrange
     the buffer's contents.  It might even crash your program. Instead,
     you add the data before calling evbuffer_reserve_space. */
  memset(v[0].iov_base, 'Y', v[0].iov_len-1);
  evbuffer_commit_space(buf, v, 1);
}

{
  /* Do not modify the iov_base pointers. */
  const char *data = "Here is some data";
  evbuffer_reserve_space(buf, strlen(data), v, 1);
  /* WRONG: The next line will not do what you want.  Instead, you
     should _copy_ the contents 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 might give an error if you're
     lucky */
  evbuffer_commit_space(buf, v, 1);
}

使用evbuffer的网络IO

最常见的使用evbuffer的场景就是网络IO。操作网络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中。如果成功，返回读了几个字节，附带0在遇到EOF的时候，-1表示失败。注意，error将会指出非阻塞操作没有正常执行；需要通过EAGAIN或是在Windows上的WSAEWOULDBLOCK来检查。如果howmuch是负数，evbuffer_read()试着读取更多的数据。

evbuffer_write_atmost()试着从buffer前面写入到fd的howmuch字节。如果成功，返回写入了多少字节，-1表示失败。和evbuffer_read()类似，需要检测error code来判断是否真的出错了，还是表明非阻塞IO仅仅没完成。如果传入负数到howmuch，将会尽量写入更多的数据。

调用evbuffer_write()和evbuffer_write_atmost()类似，传入负数到howmuch，将会试着写入更多的数据。

在Unix上，可以支持read和write调用中任意文件秒速符，在Windows上，只能支持socket。

记住，当使用bufferevent，你不需要调用它的IO函数，bufferevent会自己这样做

Evbuffers和回调函数

有时候，使用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字段记录了在它的size修改之前的字节数；他的n_added字段记录了多少字节添加了进来，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 dot every 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_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变化的时候不立马执行，但是也仅仅是在一个事件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后面添加一块数据。没有数据拷贝，转而替换为把指向的detlen长度的数据指针直接保存到evbuffer。所以指针必须包含evbuffer可以使用的足够长的数据。当evbuffer不需要数据时，调用cleanupfn函数，传入数据指针，数据长度和额外的参数惊醒释放。

示例

#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 the network.  We do this
   without keeping any more copies of the resource in memory than
   necessary. */

#define HUGE_RESOURCE_SIZE (1024*1024)
struct huge_resource {
    /* We keep a count of the references that exist 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 a complex 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 that actually adds the resource to the
   buffer. */
void spool_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，不是socket，可以读。在offset的位置增加length的字节，结束在output。

警告

在Libevent 2.0.x中，唯一一个依赖的事情，通过这种方式做数据添加，就是使用evbuffer_write*()发送到网络，通过evbuffer_drain()把数据传输完成，或者通过evbuffer_*_buffer()移动到另一个evbuffer。你不能可靠的通过evbuffer_remove()从buffer中提取出来，并且通过evbuffer_pullup()线性化，等等。Libevent 2.1.x将会试着去修复这个限制。

如果你的系统支持splice()或sendfile()，libevent会使通过evbuffer_write()用它把数据从fd发送到网络,不需要把数据先拷贝到RAM。如果splice/sendfile不存在，但是有mmap()，Libevent会mmap文件，你的内核可以希望的发现不需要把数据拷贝到用户层。否则，libevent会把数据从硬盘拷贝到RAM。

当数据从evbuffer刷新干净或者evbuffer已经被释放，文件描述符就会被关闭。如果你不想这样做，或者你想细粒度的控制你的文件，可以参考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()创建并返回一个用来替换底层在fd中的从offset开始包含length字节的文件的新的evbuffer_file_segment结构体。出错返回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

禁止使用内存拷贝机制。

• EVBUF_FS_DISABLE_SENDFILE

禁止使用sendfile机制

• EVBUF_FS_DISABLE_LOCKING

在使用文件片段的时候不会加锁

如果你有evbuffer_file_segment，你可以通过evbuffer_add_file_segment()把一个或是多个添加到evbuffer中。offset在这里指向文件片段的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);

你可以为文件片段增加回调函数，当最后的文件片段被释放的时候，会被调用。这个回调不能还原文件片段或是把它添加到任何缓冲区中。

把evbuffer添加到另一个引用

你可以把一个evbuffer添加到另一个引用，而避免把内容从一个buffer移动到另一个。

接口

int evbuffer_add_buffer_reference(struct evbuffer *outbuf,
    struct evbuffer *inbuf);

evbuffer_add_buffer_reference()行为就相当于你把数据从outbuf拷贝到inbuf，但是并没有任何底层拷贝。

注意，inbuf中内容的修改并不会反映给outbuf，因为你是把内容添加进去，而不是evbuffer自己。

注意，你不能嵌套buffer的索引。

是evbuffer只能添加或是删除

接口

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

你可以用这两个函数临时禁用evbuffer前端或是后端的修改。bufferevent底层的代码会使用它们来禁止前端output buffer或是后端input buffer的修改。