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由一个底层的传输port（如套接字）。一个读取缓冲区和一个写入缓冲区组成。与通常的事件在底层传输port已经就绪，能够读取或者写入的时候运行回调不同的是，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和port）上有新的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() 函数如果您已有套接字已经与port绑定，而且以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中。