LibEvent中文帮助文档--第12章【Evbuffer IO实用功能】
2016-12-02 17:19
519 查看
[align=center]LibEvent中文帮助文档--第12章【Evbuffer IO实用功能】[/align]
返回主目录
Libevent
快速可移植非阻塞式网络编程
文档是2009-2012年由Nick-Mathewson基于Attribution-Noncommercial-Share
Alike许可协议3.0创建,未来版本将会使用约束性更低的许可来创建.
此外,本文档的源代码示例也是基于BSD的"3条款"或"修改"条款.详情请参考BSD文件全部条款.本文档最新下载地址:
英文:http://libevent.org/
中文:http://blog.csdn.net/zhouyongku/article/details/53431750
请下载并运行"gitclonegit://github.com/nmathewson/libevent-
book.git"获取本文档描述的最新版本源码.
<<上一章>>
除了特定说明外,本章的函数定义在<event2/buffer.h>中.
接口
struct evbuffer* evbuffer_new(void);
void evbuffer_free(struct evbuffer* buf);
这些函数应该相当清晰:evbuffer_new()分配了一个空的evbuffer,evbuffer_free()删除一个或全部的内容.
这些函数自从LibEvent0.8就存在.
接口
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()默认情况下,在多个线程中同时访问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)
这些函数都在2.0.1-alpha版本中引入.
接口
size_t evbuffer_get_length(const struct evbuffer* buf);
这个函数返回 evbuffer存储的字节数,它在2.0.1-alpha版本中引入.
接口
size_t evbuffer_get_contiguous_space(const struct evbuffer* buf);
这个函数返回连续地存储在 evbuffer前面的字节数. evbuffer中的数据可能存储在多个分隔开的内存块中,这个函数返回当前第一个块中的字节数.
这个函数在2.0.1-alpha版本引入.
接口
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
字节,而不需要更多的内存分配.
示例
/* 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_add()和evbuffer_add_printf()函数在libevent
0.8版本引入;evbuffer_expand()首次出现在0.9版本,而evbuffer_add_printf()首次出现在1.1版本.
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_add_buffer()在0.8版本引入;evbuffer_remove_buffer()是2.0.1-alpha版本新增加的.
接口
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()相同.
使用这些函数时要当心,永远不要对与bufferevent
共享的evbuffer
使用.这些函数是2.0.1-alpha版本新添加的.
N 字节,将其看作连续的字节数组.要做到这一点,首先必须确保缓冲区的前面确实是连续的.
接口
unsigned char* evbuffer_pullup(struct evbuffer * buf, ev_ssize_t size);
evbuffer_pullup()函数"线性化"buf前面的
size字节,必要时将进行复制或者移动,以保证这些字节是连续的,占据相同的内存块.如果size
是负的,函数会线性化整个缓冲区.如果size
大于缓冲区中的字节数,函数返回NULL.否则,evbuffer_pullup()返回指向buf
中首字节的指针.
调用 evbuffer_pullup()时使用较大的size
参数可能会非常慢,因为这可能需要复制整个缓冲区的内容.
示例
#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_get_contiguous_space()返回的值作为尺寸值调用evbuffer_pullup()不会导致任何数据复制或者移动.
evbuffer_pullup()函数由2.0.1-alpha版本新增加:先前版本的
libevent总是保证
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
处的内存中.如果可用字节少于datlen,函数复制所有字节.失败时返回-1,否则返回复制了的字节数.
evbuffer_drain()函数的行为与evbuffer_remove()相同,只是它不进行数据复制:而只是将数据从缓冲区前面移除.成功时返回0,失败时返回-1.
evbuffer_drain()由0.8版引入,evbuffer_remove()首次出现在0.9版.
那样) ,或者在内部重新排列缓冲区(像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()相同,但是它不从缓冲区移除任何数据.也就是说,它从
buf前面复制datlen
字节到data
处的内存中.如果可用字节少于
datlen ,函数会复制所有字节.失败时返回-1,否则返回复制的字节数.如果从缓冲区复制数据太慢,可以使用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
前面取出一行,用一个新分配的空字符结束的字符串返回这一行.如果n_read_out
不是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:行尾是任意数量、任意次序的回车和换行符.这种格式不是特别有用.它的存在主要是为了向后兼容.
注意如果使用 event_se_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_readln()接口在1.4.14-stable及以后版本中可用.
evbuffer中的一个位置,包含可用于在evbuffer
中迭代的数据.
接口
struct evbuffer_ptr
{
ev_ssize_t pos;
struct
{
/* internal fields*/
} _internal;
};
接口
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()函数在缓冲区中查找含有len
个字符的字符串what.
函数返回包含字符串位置,或者在没有找到字符串时包含-1的evbuffer_ptr
结构体.如果提供了start
参数,则从指定的位置开始搜索;否则,从开始处进行搜索.
evbuffer_search_range()函数和evbuffer_search
行为相同,只是它只考虑在end
之前出现的what.
evbuffer_search_eol()函数像evbuffer_readln()一样检测行结束,但是不复制行,而是返回指向行结束符的evbuffer_ptr.如果eol_len_out
非空,则它被设置为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函数操作
buffer中的位置
pos.如果how
等于EVBUFFER_PTR_SET,指针被移动到缓冲区中的绝对位置position;如果等于EVBUFFER_PTR_ADD,则向前移动position字节.成功时函数返回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 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或者其布局的调用都会使得
evbuffer_ptr失效,不能再安全地使用.这些接口是2.0.1-alpha版本新增加的.
,也不重新排列内部内存布局(像evbuffer_pullup()那样)
.有时候可能需要查看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.函数会让每个结构体包含指向evbuffer
内部内存块的指针(iov_base)和块中数据长度.
如果 len小于0,evbuffer_peek()会试图填充所有evbuffer_iovec
结构体.否则,函数会进行填充,直到使用了所有结构体,或者见到len
字节为止.如果函数可以给出所有请求的数据,则返回实际使用的结构体个数;否则,函数返回给出所有请求数据所需的结构体个数.
如果 ptr为
NULL,函数从缓冲区开始处进行搜索.否则,从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\n", and pass it to 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-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_peek()给出的内容之后进行解锁.
这个函数是2.0.2-alpha版本新增加的.
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()函数给出evbuffer
内部空间的指针.函数会扩展缓冲区以至少提供size
字节的空间.到扩展空间的指针,以及其长度,会存储在通过vec
传递的向量数组中,n_vec是数组的长度.
n_vec的值必须至少是1.如果只提供一个向量,libevent会确保请求的所有连续空间都在单个扩展区中,但是这可能要求重新排列缓冲区,或者浪费内存.为取得更好的性能,应该至少提供2个向量.函数返回提供请求的空间所需的向量数.
写入到向量中的数据不会是缓冲区的一部分,直到调用evbuffer_commit_space(),使得写入的数据进入缓冲区.如果需要提交少于请求的空间,可以减小任何
evbuffer_iovec结构体的
iov_len字段,也可以提供较少的向量.函数成功时返回0,失败时返回-1.
提示和警告:
调用
任 何
重 新排
列 evbuffer或 者 向 其 添 加 数 据 的 函 数 都 将 使 从evbuffer_reserve_space()获取的指针失效.
当前实现中,不论用户提供多少个向量,evbuffer_reserve_space()从不使用多于两个.未来版本可能会改变这一点.
如果在多个线程中使用 evbuffer,确保在调用evbuffer_reserve_space()之前使用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’relucky*/
evbuffer_commit_space(buf, v, 1);
}
这个函数及其提出的接口从2.0.2-alpha版本就存在了.
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
末尾.成功时函数返回读取的字节数,0表示EOF,失败时返回-1.注意,错误码可能指示非阻塞操作不能立即成功,应该检查错误码EAGAIN(或者Windows
中的WSAWOULDBLOCK) .如果howmuch
为负,evbuffer_read()试图猜测要读取多少数据.
evbuffer_write_atmost()函数试图将buffer
前面至多howmuch
字节写入到套接字fd
中.成功时函数返回写入的字节数,失败时返回-1.跟evbuffer_read()一样,应该检查错误码,看是真的错误,还是仅仅指示非阻塞IO
不能立即完成.如果为howmuch
给出负值,函数会试图写入buffer
的所有内容.
调用 evbuffer_write()与使用负的howmuch
参数调用evbuffer_write_atmost()一样:函数会试图尽量清空buffer
的内容.
在 Unix中,这些函数应该可以在任何支持read
和write
的文件描述符上正确工作.在Windows中,仅仅支持套接字.注意,如果使用bufferevent,则不需要调用这些函数,bufferevent的代码已经为你调用了.
evbuffer_write_atmost()函数在2.0.1-alpha版本中引入.
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_cb_info
结构体指针,和用户提供的参数.evbuffer_cb_info结构体的orig_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
也不会为回调释放用户提供的数据指针.如果不想让缓冲区上的回调永远激活,可以移除或者禁用回调:
接口
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来移除回调,也可以通过回调函数和参数指针来移除.成功时函数返回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
的事件循环中执行.如果有多个evbuffer,它们的回调潜在地让数据添加到evbuffer
中,或者从中移除,又要避免栈崩溃,延迟回调是很有用的.
如果回调被延迟,则最终执行时,它可能是多个操作结果的总和.
与 bufferevent一样,evbuffer具有内部引用计数的,所以即使还有未执行的延迟回调,释放evbuffer
也是安全的.
整个
回 调
系 统是 2.0.1-alpha
版 本 新 引 入 的. evbuffer_cb_(set|clear)_flags()
函 数 从
2.0.2-alpha版本开始存在.
接口
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只会存储一个到data处的
datlen字节的指针.因此,在evbuffer
使用这个指针期间,必须保持指针是有效的.evbuffer会在不再需要这部分数据的时候调用用户提供的
cleanupfn函数,带有提供的data指针、datlen值和
extra指针参数.函数成功时返回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 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_add_reference()函数在LibEvent2.0.2-alpha版本中开始出现.
接口
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.x版本中,唯一可靠的处理数据的补充方式是用evbuffer_write*()发送到网络,用evbuffer_drain()排掉或者用evbuffer_*_buffer*()来移动到另外一个evbuffer上.不能使用evbuffer_remove()可靠地提取数据或使用evbuffer_pullup()来线性化数据等等.LibEvent2.1x试图修复这个限制.
如果你的操作系统支持splice()或者sendfile()函数,LibEvent将会使用这些函数从fd套接字上直接发送数据到网络而不用经过RAM.如果你的操作系统不支持splice()或者sendfile()函数但是支持mmap()函数,LibEvent将会对文件进行内存映射,那么你的内核将会有希望判定其不需要拷贝数据到用户内存空间,否则LibEvent将会从磁盘读取数据到RAM中.
在数据刷新到evbuffer()中之后或者evbuffer释放的时候文件描述符将会关闭,如果你不想这样而想要更细粒度地控制文件,请查看下面的函数.
本函数定义在LibEvent2.0.1-alpha版本中.
接口
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:如果设置了这个标志,file_segment将不会对文件使用内存映射的后台模式,即使内存映射更合适.
EVBUF_FS_DISABLE_SENDFILE:如果设置了这个标志,file_segment将不会对文件使用使用sendfile后台模式,即使sendfile更合适.
EVBUF_FS_DISABLE_LOCKING:如果设置了这个标志,file_segment将不会再分配锁:多线程中以任何方式使用它将会使得它不再安全.
一旦有了evbuffer_file_segment,可以用evbuffer_add_file_segment()来添加一些或所有evbuffer.这里的参数offset指的是文件片段内的偏移量而不是文件的偏移量.
接口
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等.
这些文件段函数首次出现在LibEvent2.1.1-alpha,evbuffer_file_segment_add_cleanup_cb()首次出现在LibEvent2.1.2-alpha.
接口
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_add_buffer_reference的outbuf不能成为别的buffer的inbuf.
这个函数首次出现在LibEvent2.1.1-alpha中.
接口
int evbuffer_freeze(struct evbuffer* buf, int at_front);
int evbuffer_unfreeze(struct evbuffer* buf, int at_front);
你可以使用这些函数来临时禁用改变evbuffer的头或尾.bufferevent代码使用这些函数内部来阻止意外编辑输出buffer的头或者输入buffer的尾.
evbuffer_freeze()函数首次出现在LibEvent2.0.1-alpha版本.
event.h头文件常用来显示evbuffer的内部结构,然而这些都是不再可用的,在1.4和2.0版本之中依赖evbuffer工作的函数都有了很大的改变.
要访问evbuffer字节的数量,可以使用EVBUFFER_LENGTHH()宏,实际数据可以使用EVBUFFER_DATA()宏,这两个宏都在event2/bufer_compat.h头文件中.不过,小心EVBUFFER_DATA(b)是evbuvfer_pullup()别名,用它的代价比较昂贵.
别的一些弃用的接口:
接口
char* evbuffer_readline(struct evbuffer * buffer);
unsigned char* evbuffer_find(struct evbuffer * buffer,
const unsigned char* what,
size_t len);
evbuffer_find()函数工作原理与当前的evbuffer_readln(buffer,NULL,EVBUFFER_EOL_ANY)类似.
evbuffer_find()函数会搜索在buffer中出现的字符串并返回指向该字符串的指针.与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只能一次设置一个回调函数,所以设置一个新的回调函数将会使之前的回调函数失效,设置回调函数为空则将使回调函数禁用.
函数调用的时候使用新老版本的evbuffer的长度而不是获取evbuffer_cb_info_structure,因此如果old_len比new_len大那么数据将会流失,如果new_len比old_len大数据将被添加.由于不可能推迟一个回调调用,因此增加或删除操作将
不会被批处理成一个单个回调函数调用.
这些废弃的函数仍然在event2/buffer_compatch.h中有效.
<<下一章>>
[align=center]LibEvent中文帮助文档--第12章【Evbuffer IO实用功能】[/align]
返回主目录
Libevent
快速可移植非阻塞式网络编程
| 修订历史 | |||
| 版本 | 日期 | 作者 | 备注 |
| V1.0 | 2016-11-15 | 周勇 | Libevent编程中文帮助文档 |
文档是2009-2012年由Nick-Mathewson基于Attribution-Noncommercial-Share
Alike许可协议3.0创建,未来版本将会使用约束性更低的许可来创建.
此外,本文档的源代码示例也是基于BSD的"3条款"或"修改"条款.详情请参考BSD文件全部条款.本文档最新下载地址:
英文:http://libevent.org/
中文:http://blog.csdn.net/zhouyongku/article/details/53431750
请下载并运行"gitclonegit://github.com/nmathewson/libevent-
book.git"获取本文档描述的最新版本源码.
<<上一章>>
12.Evbuffer IO实用功能
LibEvent的bufferevent实现了向后添加数据和前面移除数据的优化字节序列.evbuffer用于处理完了IO的缓冲部分.它不提供调度IO或当IO就绪时触发IO的功能:这就是bufferevent所做的事.除了特定说明外,本章的函数定义在<event2/buffer.h>中.
12.1创建或释放一个Bvbuffer
接口
struct evbuffer* evbuffer_new(void);
void evbuffer_free(struct evbuffer* buf);
这些函数应该相当清晰:evbuffer_new()分配了一个空的evbuffer,evbuffer_free()删除一个或全部的内容.
这些函数自从LibEvent0.8就存在.
12.2Evbuffer和线程安全
接口
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()默认情况下,在多个线程中同时访问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)
这些函数都在2.0.1-alpha版本中引入.
12.3检查Evbuffer
接口
size_t evbuffer_get_length(const struct evbuffer* buf);
这个函数返回 evbuffer存储的字节数,它在2.0.1-alpha版本中引入.
接口
size_t evbuffer_get_contiguous_space(const struct evbuffer* buf);
这个函数返回连续地存储在 evbuffer前面的字节数. evbuffer中的数据可能存储在多个分隔开的内存块中,这个函数返回当前第一个块中的字节数.
这个函数在2.0.1-alpha版本引入.
12.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
字节,而不需要更多的内存分配.
示例
/* 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_add()和evbuffer_add_printf()函数在libevent
0.8版本引入;evbuffer_expand()首次出现在0.9版本,而evbuffer_add_printf()首次出现在1.1版本.
12.5将数据从一个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_add_buffer()在0.8版本引入;evbuffer_remove_buffer()是2.0.1-alpha版本新增加的.
12.6添加数据到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()相同.
使用这些函数时要当心,永远不要对与bufferevent
共享的evbuffer
使用.这些函数是2.0.1-alpha版本新添加的.
12.7重新排列Evbuffer的内部布局
有时候需要取出 evbuffer前面的N 字节,将其看作连续的字节数组.要做到这一点,首先必须确保缓冲区的前面确实是连续的.
接口
unsigned char* evbuffer_pullup(struct evbuffer * buf, ev_ssize_t size);
evbuffer_pullup()函数"线性化"buf前面的
size字节,必要时将进行复制或者移动,以保证这些字节是连续的,占据相同的内存块.如果size
是负的,函数会线性化整个缓冲区.如果size
大于缓冲区中的字节数,函数返回NULL.否则,evbuffer_pullup()返回指向buf
中首字节的指针.
调用 evbuffer_pullup()时使用较大的size
参数可能会非常慢,因为这可能需要复制整个缓冲区的内容.
示例
#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_get_contiguous_space()返回的值作为尺寸值调用evbuffer_pullup()不会导致任何数据复制或者移动.
evbuffer_pullup()函数由2.0.1-alpha版本新增加:先前版本的
libevent总是保证
evbuffer中的数据是连续的,而不计开销.
12.8从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
处的内存中.如果可用字节少于datlen,函数复制所有字节.失败时返回-1,否则返回复制了的字节数.
evbuffer_drain()函数的行为与evbuffer_remove()相同,只是它不进行数据复制:而只是将数据从缓冲区前面移除.成功时返回0,失败时返回-1.
evbuffer_drain()由0.8版引入,evbuffer_remove()首次出现在0.9版.
12.9从Evbuffer中复制出数据
有时候需要获取缓冲区前面数据的副本,而不清除数据.比如说,可能需要查看某特定类型的记录是否已经完整到达,而不清除任何数据(像evbuffer_remove那样) ,或者在内部重新排列缓冲区(像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()相同,但是它不从缓冲区移除任何数据.也就是说,它从
buf前面复制datlen
字节到data
处的内存中.如果可用字节少于
datlen ,函数会复制所有字节.失败时返回-1,否则返回复制的字节数.如果从缓冲区复制数据太慢,可以使用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;
}
12.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值是0x0D
0x0A)
EVBUFFER_EOL_CRLF:行尾是一个可选的回车,后随一个换行符(也就是说,可以是\r\n或者\n)
.这种格式对于解析基于文本的互联网协议很有用,因为标准通常要求\r\n的行结束符,而不遵循标准的客户端有时候只使用\n.
EVBUFFER_EOL_ANY:行尾是任意数量、任意次序的回车和换行符.这种格式不是特别有用.它的存在主要是为了向后兼容.
注意如果使用 event_se_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_readln()接口在1.4.14-stable及以后版本中可用.
12.11在Evbuffer中搜索
evbuffer_ptr结构体指示evbuffer中的一个位置,包含可用于在evbuffer
中迭代的数据.
接口
struct evbuffer_ptr
{
ev_ssize_t pos;
struct
{
/* internal fields*/
} _internal;
};
接口
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()函数在缓冲区中查找含有len
个字符的字符串what.
函数返回包含字符串位置,或者在没有找到字符串时包含-1的evbuffer_ptr
结构体.如果提供了start
参数,则从指定的位置开始搜索;否则,从开始处进行搜索.
evbuffer_search_range()函数和evbuffer_search
行为相同,只是它只考虑在end
之前出现的what.
evbuffer_search_eol()函数像evbuffer_readln()一样检测行结束,但是不复制行,而是返回指向行结束符的evbuffer_ptr.如果eol_len_out
非空,则它被设置为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函数操作
buffer中的位置
pos.如果how
等于EVBUFFER_PTR_SET,指针被移动到缓冲区中的绝对位置position;如果等于EVBUFFER_PTR_ADD,则向前移动position字节.成功时函数返回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 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或者其布局的调用都会使得
evbuffer_ptr失效,不能再安全地使用.这些接口是2.0.1-alpha版本新增加的.
12.12检测数据而不复制
有时候需要读取 evbuffer中的数据而不进行复制(像evbuffer_copyout()那样),也不重新排列内部内存布局(像evbuffer_pullup()那样)
.有时候可能需要查看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.函数会让每个结构体包含指向evbuffer
内部内存块的指针(iov_base)和块中数据长度.
如果 len小于0,evbuffer_peek()会试图填充所有evbuffer_iovec
结构体.否则,函数会进行填充,直到使用了所有结构体,或者见到len
字节为止.如果函数可以给出所有请求的数据,则返回实际使用的结构体个数;否则,函数返回给出所有请求数据所需的结构体个数.
如果 ptr为
NULL,函数从缓冲区开始处进行搜索.否则,从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\n", and pass it to 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-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_peek()给出的内容之后进行解锁.
这个函数是2.0.2-alpha版本新增加的.
12.13直接向Evbuffer添加数据
有时候需要能够直接向 evbuffer添加数据,而不用先将数据写入到字符数组中,然后再使用evbuffer_add()进行复制.有一对高级函数可以完成这种功能: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()函数给出evbuffer
内部空间的指针.函数会扩展缓冲区以至少提供size
字节的空间.到扩展空间的指针,以及其长度,会存储在通过vec
传递的向量数组中,n_vec是数组的长度.
n_vec的值必须至少是1.如果只提供一个向量,libevent会确保请求的所有连续空间都在单个扩展区中,但是这可能要求重新排列缓冲区,或者浪费内存.为取得更好的性能,应该至少提供2个向量.函数返回提供请求的空间所需的向量数.
写入到向量中的数据不会是缓冲区的一部分,直到调用evbuffer_commit_space(),使得写入的数据进入缓冲区.如果需要提交少于请求的空间,可以减小任何
evbuffer_iovec结构体的
iov_len字段,也可以提供较少的向量.函数成功时返回0,失败时返回-1.
提示和警告:
调用
任 何
重 新排
列 evbuffer或 者 向 其 添 加 数 据 的 函 数 都 将 使 从evbuffer_reserve_space()获取的指针失效.
当前实现中,不论用户提供多少个向量,evbuffer_reserve_space()从不使用多于两个.未来版本可能会改变这一点.
如果在多个线程中使用 evbuffer,确保在调用evbuffer_reserve_space()之前使用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’relucky*/
evbuffer_commit_space(buf, v, 1);
}
这个函数及其提出的接口从2.0.2-alpha版本就存在了.
12.14使用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
末尾.成功时函数返回读取的字节数,0表示EOF,失败时返回-1.注意,错误码可能指示非阻塞操作不能立即成功,应该检查错误码EAGAIN(或者Windows
中的WSAWOULDBLOCK) .如果howmuch
为负,evbuffer_read()试图猜测要读取多少数据.
evbuffer_write_atmost()函数试图将buffer
前面至多howmuch
字节写入到套接字fd
中.成功时函数返回写入的字节数,失败时返回-1.跟evbuffer_read()一样,应该检查错误码,看是真的错误,还是仅仅指示非阻塞IO
不能立即完成.如果为howmuch
给出负值,函数会试图写入buffer
的所有内容.
调用 evbuffer_write()与使用负的howmuch
参数调用evbuffer_write_atmost()一样:函数会试图尽量清空buffer
的内容.
在 Unix中,这些函数应该可以在任何支持read
和write
的文件描述符上正确工作.在Windows中,仅仅支持套接字.注意,如果使用bufferevent,则不需要调用这些函数,bufferevent的代码已经为你调用了.
evbuffer_write_atmost()函数在2.0.1-alpha版本中引入.
12.15Evbuffer和回调
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_cb_info
结构体指针,和用户提供的参数.evbuffer_cb_info结构体的orig_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
也不会为回调释放用户提供的数据指针.如果不想让缓冲区上的回调永远激活,可以移除或者禁用回调:
接口
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来移除回调,也可以通过回调函数和参数指针来移除.成功时函数返回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
的事件循环中执行.如果有多个evbuffer,它们的回调潜在地让数据添加到evbuffer
中,或者从中移除,又要避免栈崩溃,延迟回调是很有用的.
如果回调被延迟,则最终执行时,它可能是多个操作结果的总和.
与 bufferevent一样,evbuffer具有内部引用计数的,所以即使还有未执行的延迟回调,释放evbuffer
也是安全的.
整个
回 调
系 统是 2.0.1-alpha
版 本 新 引 入 的. evbuffer_cb_(set|clear)_flags()
函 数 从
2.0.2-alpha版本开始存在.
12.16为基于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只会存储一个到data处的
datlen字节的指针.因此,在evbuffer
使用这个指针期间,必须保持指针是有效的.evbuffer会在不再需要这部分数据的时候调用用户提供的
cleanupfn函数,带有提供的data指针、datlen值和
extra指针参数.函数成功时返回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 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_add_reference()函数在LibEvent2.0.2-alpha版本中开始出现.
12.17增加一个文件到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.x版本中,唯一可靠的处理数据的补充方式是用evbuffer_write*()发送到网络,用evbuffer_drain()排掉或者用evbuffer_*_buffer*()来移动到另外一个evbuffer上.不能使用evbuffer_remove()可靠地提取数据或使用evbuffer_pullup()来线性化数据等等.LibEvent2.1x试图修复这个限制.
如果你的操作系统支持splice()或者sendfile()函数,LibEvent将会使用这些函数从fd套接字上直接发送数据到网络而不用经过RAM.如果你的操作系统不支持splice()或者sendfile()函数但是支持mmap()函数,LibEvent将会对文件进行内存映射,那么你的内核将会有希望判定其不需要拷贝数据到用户内存空间,否则LibEvent将会从磁盘读取数据到RAM中.
在数据刷新到evbuffer()中之后或者evbuffer释放的时候文件描述符将会关闭,如果你不想这样而想要更细粒度地控制文件,请查看下面的函数.
本函数定义在LibEvent2.0.1-alpha版本中.
12.18细粒度控制文件段
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:如果设置了这个标志,file_segment将不会对文件使用内存映射的后台模式,即使内存映射更合适.
EVBUF_FS_DISABLE_SENDFILE:如果设置了这个标志,file_segment将不会对文件使用使用sendfile后台模式,即使sendfile更合适.
EVBUF_FS_DISABLE_LOCKING:如果设置了这个标志,file_segment将不会再分配锁:多线程中以任何方式使用它将会使得它不再安全.
一旦有了evbuffer_file_segment,可以用evbuffer_add_file_segment()来添加一些或所有evbuffer.这里的参数offset指的是文件片段内的偏移量而不是文件的偏移量.
接口
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等.
这些文件段函数首次出现在LibEvent2.1.1-alpha,evbuffer_file_segment_add_cleanup_cb()首次出现在LibEvent2.1.2-alpha.
12.19添加一个Evbuffer引用到另一个Evbuffer
可以添加一个引用到另一个Evbuffer:比起移动buffer的内容并且将它们添加到另一个,你可以为另一个添加一个引用,就好像你拷贝了所有的内部字节.接口
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_add_buffer_reference的outbuf不能成为别的buffer的inbuf.
这个函数首次出现在LibEvent2.1.1-alpha中.
12.20让Evbuffer只能添加和删除
接口
int evbuffer_freeze(struct evbuffer* buf, int at_front);
int evbuffer_unfreeze(struct evbuffer* buf, int at_front);
你可以使用这些函数来临时禁用改变evbuffer的头或尾.bufferevent代码使用这些函数内部来阻止意外编辑输出buffer的头或者输入buffer的尾.
evbuffer_freeze()函数首次出现在LibEvent2.0.1-alpha版本.
12.21废弃的Evbuffer函数
evbuffer的接口在LibEvent2.0已经有了较大改变.在此之前每个evbuffer被实现为一个连续的块内存,访问效率很低.event.h头文件常用来显示evbuffer的内部结构,然而这些都是不再可用的,在1.4和2.0版本之中依赖evbuffer工作的函数都有了很大的改变.
要访问evbuffer字节的数量,可以使用EVBUFFER_LENGTHH()宏,实际数据可以使用EVBUFFER_DATA()宏,这两个宏都在event2/bufer_compat.h头文件中.不过,小心EVBUFFER_DATA(b)是evbuvfer_pullup()别名,用它的代价比较昂贵.
别的一些弃用的接口:
接口
char* evbuffer_readline(struct evbuffer * buffer);
unsigned char* evbuffer_find(struct evbuffer * buffer,
const unsigned char* what,
size_t len);
evbuffer_find()函数工作原理与当前的evbuffer_readln(buffer,NULL,EVBUFFER_EOL_ANY)类似.
evbuffer_find()函数会搜索在buffer中出现的字符串并返回指向该字符串的指针.与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只能一次设置一个回调函数,所以设置一个新的回调函数将会使之前的回调函数失效,设置回调函数为空则将使回调函数禁用.
函数调用的时候使用新老版本的evbuffer的长度而不是获取evbuffer_cb_info_structure,因此如果old_len比new_len大那么数据将会流失,如果new_len比old_len大数据将被添加.由于不可能推迟一个回调调用,因此增加或删除操作将
不会被批处理成一个单个回调函数调用.
这些废弃的函数仍然在event2/buffer_compatch.h中有效.
<<下一章>>
内容来自用户分享和网络整理，不保证内容的准确性，如有侵权内容，可联系管理员处理 
相关文章推荐
- Libevent参考手册：evbuffer：缓冲IO实用功能
- Libevent参考手册：evbuffer：缓冲IO实用功能 (2011-07-31 16:41:46)
- libevent参考手册第八章：evbuffer：缓冲IO实用功能 (十)
- libevent参考手册第八章：evbuffer：缓冲IO实用功能 (十)
- Libevent参考手册：evbuffer：缓冲IO实用功能
- Libevent参考手册：evbuffer：缓冲IO实用功能
- Libevent参考手册：evbuffer：缓冲IO实用功能
- LibEvent中文帮助文档--第14章【使用LibEvent的DNS:高和低层功能】
- LibEvent中文帮助文档
- LibEvent中文帮助文档--第16章【DNS服务器接口】
- LibEvent中文帮助文档--第9章【辅助类型和函数】
- LibEvent中文帮助文档--第15章【底层DNS接口】
- LibEvent中文帮助文档
- LibEvent中文帮助文档--第11章【高级话题】
- evbuffer：缓冲IO实用功能 (十) （转）
- LibEvent中文帮助文档-第7章【事件循环】
- libevent学习笔记【使用篇】——7. evbuffer：缓冲IO的实用功能
- 翻译：libevent参考手册第八章：evbuffer：缓冲IO实用功能 (十) （转）
- LibEvent中文帮助文档--第17章【废弃的DNS接口】
- LibEvent中文帮助文档--第1、2、3、4章