libevent入门

Libevent API

===============================

evtimer_new

evtimer_new(base, callback, NULL)

用来做定时器，即当达到一定时间后调用回调函数callback，用evtimer_add激活定时器。例如：

my_node->ev_expect_ping = evtimer_new(my_node->base,expected_leader_ping_period,
                                              (void*)my_node);
evtimer_del(my_node->ev_expect_ping);
evtimer_add(my_node->ev_expect_ping,&my_node->config.expect_ping_timeval);

我们在my->base上创建了一个定时器my_node->ev_expect_ping，并绑定这个定时器上的定时事件expected_leader_ping_period，然后先用evtimer_del禁用这个定时器，再用evtimer_add启用定时器，设定expect_ping_timeval后触发。

===============================

bufferevent

struct bufferevent {
               struct event_base *ev_base;
        const struct bufferevent_ops *be_ops;
        struct event ev_read;
        struct event ev_write;
        struct evbuffer *input;
        struct evbuffer *output;
		……
		bufferevent_data_cb readcb;
        bufferevent_data_cb writecb;
		bufferevent_event_cb errorcb;
		……
}

bufferevent 内置了两个event（读／写）和对应的缓冲区，当有数据被读入（input）时，readcb被调用，当output被输出完成的时候，writecb被调用。

当网络I／O出现错误，如链接中断，超时或其他错误时，errorcb被调用，例如 ：BEV_EVENT_ERROR

如果bufferevent出现这个事件，表示操作时发生错误，如果你是将bufferevent用作socket通信，这个错误一般意味着socket连接断开。更多的错误信息需要调用EVUTIL_SOCKET_ERROR()。

bufferevent由一个底层的传输端口（如套接字），一个读取缓冲区和一个写入缓冲区组成。与通常的事件在底层传输端口已经就绪，可以读取或者写入的时候执行回调不同的是，bufferevent在读取或者写入了足够量的数据之后调用用户提供的回调。

bufferevent_write(struct bufferevent *bufev, const void *data, size_t size)

把数据写入一个bufferevent buffer中，它被用来将数据写入文件描述符，当数据变得能够写时，会自动写入到描述符中。

 struct bufferevent * bufferevent_socket_new (struct event_base *base,
           evutil_socket_t fd, int options)

bufferevent_socket_new在一个已经存在的socket（fd）上创建一个新的socket bufferevent，bufferevent是在event和evbuffer之上的一层封装，为输入和输出各提供了一个event（分别是ev_read和ev_write）和相应的buffer。

   void bufferevent_setcb (struct bufferevent *bufev, bufferevent_data_cb
           readcb, bufferevent_data_cb writecb, bufferevent_event_cb eventcb,
           void *cbarg)

bufferevent_setcb()函数修改bufferevent的一个或者多个回调。readcb、writecb和eventcb函数将分别在已经读取足够的数据、已经写入足够的数据，或者发生错误时被调用。每个回调函数的第一个参数都是发生了事件的bufferevent，最后一个参数都是调用bufferevent_setcb()时用户提供的cbarg参数：可以通过它向回调传递数据。

int bufferevent_enable (struct bufferevent *bufev, short event)

当bufferevent初始化后，调用bufferevent_enable来激活，参数event指定bufferevent可以进行的事件，如，如果是EV_READ，则进行读。

===============================

evconnlistener_new_bind & evconnlistener_new

用evconnlistener_new_bind即可完成一个服务端socket的创建。

struct evconnlistener *evconnlistener_new_bind(struct event_base *base,
    evconnlistener_cb cb, void *ptr, unsigned flags, int backlog,
    const struct sockaddr *sa, int socklen);

分配和返回一个新的连接监听器对象，base参数是监听器用于监听连接的event_base，即连接监听器使用event_base来得知什么时候在给定的监听套接字const struct sockaddr *sa（包含ip和端口）上有新的TCP连接，新连接到达时，监听器调用你给出的回调函数cb。

struct evconnlistener *evconnlistener_new(struct event_base *base,

    evconnlistener_cb cb, void *ptr, unsigned flags, int backlog,

    evutil_socket_t fd);

上面的两个Evconnlistener_new*() 函数都分配并返回一个新的连接监听器对象。连接侦听器使用event_base获得通知，当在一个监听套接字上有一个新的TCP连接。当一个新的连接到达时，它将调用你所提供的回调函数。

在这两个函数中，侦听器使用一个event_base类型的base参数去侦听连接。当一个新连接被接受时，回调函数Cb将被调用；若回调cb是 NULL，监听器将被视为禁用直到设置回调。Ptr指针将传递给回调。Flags参数控制侦听器的行为。backlog参数控制着挂起连接的最大的数目，即任何时间网络堆栈应该允许等待中尚未接受的状态的数目。如果backlog是负的，Libevent 将尝试为backlog设置一个适当的值；如果它是零，Libevent 将假定您已经在套接字上调用 listen()。

这两个函数设置监听套接字的方式不同。Evconnlistener_new() 函数假设您已有套接字已经与端口绑定，并且以fd参数传递。如果您希望自己让Libevent 分配和绑定到套接字上，调用 evconnlistener_new_bind()，传递sockaddr参数的和它的长度。

要释放连接的侦听器，请将它传递给 evconnlistener_free()。

===============================

evbuffer_remove

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

evbuffer_remove() 函数将复制和删除前面的buf的datlen个字节到内存中的data中。如果少于datlen个字节可用，函数将复制所有的字节。失败返回的值是-1，否则返回复制的字节数。

示例：

 struct evbuffer* evb = bufferevent_get_input(bev);
    evbuffer_remove(evb,msg_buf,SYS_MSG_HEADER_SIZE+data_size);

从一个bufferevent叫bev中读取数据到evbuffer evb中，再转到msg_buf中。