1 运行循环

一旦有了一个已经注册了某些事件的event_base（关于如何创建和注册事件请看下一节），就需要让libevent等待事件并且通知事件的发生。

接口

#define EVLOOP_ONCE             0x01
#define EVLOOP_NONBLOCK         0x02
#define EVLOOP_NO_EXIT_ON_EMPTY 0x04

int event_base_loop(struct event_base *base, int flags);

默认情况下，event_base_loop（）函数运行event_base直到其中没有已经注册的事件为止。执行循环的时候，函数重复地检查是否有任何已经注册的事件被触发（比如说，读事件的文件描述符已经就绪，可以读取了；或者超时事件的超时时间即将到达）。如果有事件被触发，函数标记被触发的事件为“激活的”，并且执行这些事件。

在flags参数中设置一个或者多个标志就可以改变event_base_loop（）的行为。如果设置了EVLOOP_ONCE，循环将等待某些事件成为激活的，执行激活的事件直到没有更多的事件可以执行，然会返回。如果设置了EVLOOP_NONBLOCK，循环不会等待事件被触发：循环将仅仅检测是否有事件已经就绪，可以立即触发，如果有，则执行事件的回调。

完成工作后，如果正常退出，event_base_loop（）返回0；如果因为后端中的某些未处理错误而退出，则返回-1。

为帮助理解，这里给出event_base_loop（）的算法概要：

伪代码

while (any events are registered with the loop,
        or EVLOOP_NO_EXIT_ON_EMPTY was set) {

    if (EVLOOP_NONBLOCK was set, or any events are already active)
        If any registered events have triggered, mark them active.
    else
        Wait until at least one event has triggered, and mark it active.

    for (p = 0; p < n_priorities; ++p {
       if (any event with priority of p is active) {
          Run all active events with priority of p.
          break; /* Do not run any events of a less important priority */
       }
    }

    if (EVLOOP_ONCE was set or EVLOOP_NONBLOCK was set)
       break;
}

为方便起见，也可以调用

接口

int event_base_dispatch(struct event_base *base);

event_base_dispatch（）等同于没有设置标志的event_base_loop（）。所以，event_base_dispatch（）将一直运行，直到没有已经注册的事件了，或者调用了event_base_loopbreak（）或者event_base_loopexit（）为止。

这些函数定义在<event2/event.h>中，从libevent 1.0版就存在了。

2 停止循环

如果想在移除所有已注册的事件之前停止活动的事件循环，可以调用两个稍有不同的函数。

接口

int event_base_loopexit(struct event_base *base,
                        const struct timeval *tv);
int event_base_loopbreak(struct event_base *base);

event_base_loopexit（）让event_base在给定时间之后停止循环。如果tv参数为NULL，event_base会立即停止循环，没有延时。如果event_base当前正在执行任何激活事件的回调，则回调会继续运行，直到运行完所有激活事件的回调之才退出。

event_base_loopbreak（）让event_base立即退出循环。它与event_base_loopexit（base,NULL）的不同在于，如果event_base当前正在执行激活事件的回调，它将在执行完当前正在处理的事件后立即退出。

注意event_base_loopexit(base,NULL)和event_base_loopbreak(base)在事件循环没有运行时的行为不同：前者安排下一次事件循环在下一轮回调完成后立即停止（就好像带EVLOOP_ONCE标志调用一样）；后者却仅仅停止当前正在运行的循环，如果事件循环没有运行，则没有任何效果。

这两个函数都在成功时返回0，失败时返回-1。

示例：立即关闭

#include <event2/event.h>

/* Here's a callback function that calls loopbreak */
void cb(int sock, short what, void *arg)
{
    struct event_base *base = arg;
    event_base_loopbreak(base);
}

void main_loop(struct event_base *base, evutil_socket_t watchdog_fd)
{
    struct event *watchdog_event;

    /* Construct a new event to trigger whenever there are any bytes to
       read from a watchdog socket.  When that happens, we'll call the
       cb function, which will make the loop exit immediately without
       running any other active events at all.
     */
    watchdog_event = event_new(base, watchdog_fd, EV_READ, cb, base);

    event_add(watchdog_event, NULL);

    event_base_dispatch(base);
}

示例：执行事件循环10秒，然后退出

#include <event2/event.h>

void run_base_with_ticks(struct event_base *base)
{
  struct timeval ten_sec;

  ten_sec.tv_sec = 10;
  ten_sec.tv_usec = 0;

  /* Now we run the event_base for a series of 10-second intervals, printing
     "Tick" after each.  For a much better way to implement a 10-second
     timer, see the section below about persistent timer events. */
  while (1) {
     /* This schedules an exit ten seconds from now. */
     event_base_loopexit(base, &ten_sec);

     event_base_dispatch(base);
     puts("Tick");
  }
}

有时候需要知道对event_base_dispatch（）或者event_base_loop（）的调用是正常退出的，还是因为调用event_base_loopexit（）或者event_base_break（）而退出的。可以调用下述函数来确定是否调用了loopexit或者break函数。

接口

int event_base_got_exit(struct event_base *base);
int event_base_got_break(struct event_base *base);

这两个函数分别会在循环是因为调用event_base_loopexit（）或者event_base_break（）而退出的时候返回true，否则返回false。下次启动事件循环的时候，这些值会被重设。

这些函数声明在<event2/event.h>中。event_break_loopexit()函数首次在libevent 1.0c版本中实现；event_break_loopbreak()首次在libevent 1.4.3版本中实现。

3 检查内部时间缓存

有时候需要在事件回调中获取当前时间的近似视图，但不想调用gettimeofday()（可能是因为OS将gettimeofday()作为系统调用实现，而你试图避免系统调用的开销）。

在回调中，可以请求libevent开始本轮回调时的当前时间视图。

接口

int event_base_gettimeofday_cached(struct event_base *base,
    struct timeval *tv_out);

如果当前正在执行回调，event_base_gettimeofday_cached()函数设置tv_out参数的值为缓存的时间。否则，函数调用evutil_gettimeofday()获取真正的当前时间。成功时函数返回0，失败时返回负数。

注意，因为libevent在开始执行回调的时候缓存时间值，所以这个值至少是有一点不精确的。如果回调执行很长时间，这个值将非常不精确。

这个函数是libevent 2.0.4-alpha新引入的。

4 转储event_base的状态

接口

void event_base_dump_events(struct event_base *base, FILE *f);

为帮助调试程序（或者调试libevent），有时候可能需要加入到event_base的事件及其状态的完整列表。调用event_base_dump_events()可以将这个列表输出到指定的文件中。

这个列表是人可读的，未来版本的libevent将会改变其格式。

这个函数在libevent 2.0.1-alpha版本中引入。

5 废弃的事件循环函数

前面已经讨论过，老版本的libevent 具有“当前”event_base的概念。

本文讨论的某些事件循环函数具有操作当前event_base的变体。除了没有base参数外，这些函数跟当前新版本函数的行为相同。

注意

2.0版本之前的event_base是不支持锁的，所以这些函数并不是完全线程安全的：不允许在执行事件循环的线程之外的其他线程中调用_loopbreak()或者_loopexit()函数。

实际运作

    这里我将结合具体的代码分析libevent是如何操作上面那个队列式的evbuffer的，先看一些辅助函数：

    该函数主要操作一些指标，当每次从evbuffer里读取数据时，libevent便会将buffer指针后移，同时增大misalign，减小off，
而该函数正是做这件事的。说白了，该函数就是用于调整缓冲队列的前向指标。

    该函数用于扩充evbuffer的容量。每次向evbuffer写数据时，都是将数据写到buffer+off后，buffer到buffer+off之间已被
使用，保存的是有效数据，而orig_buffer和buffer之间则是因为读取数据移动指标而形成的无效区域。
    evbuffer_expand的扩充策略在于，首先判断如果让出orig_buffer和buffer之间的空闲区域是否可以容纳添加的数据，如果
可以，则移动buffer和buffer+off之间的数据到orig_buffer和orig_buffer+off之间(有可能发生内存重叠，所以这里移动调用的
是memmove)，然后把新的数据拷贝到orig_buffer+off之后；如果不可以容纳，那么重新分配更大的空间(realloc)，同样会移动
数据。
    扩充内存的策略为：确保新的内存区域最小尺寸为256，且以乘以2的方式逐步扩大(256、512、1024、...)。

    了解了以上两个函数，看其他函数就比较简单了。可以看看具体的读数据和写数据：

    该函数用于添加一段用户数据到evbuffer中。很简单，就是先判断是否有足够的空闲内存，如果没有则调用evbuffer_expand
扩充之，然后直接memcpy，更新off指标。

    该函数用于将evbuffer中的数据复制给用户空间(读数据)。简单地将数据memcpy，然后调用evbuffer_drain移动相关指标。

动态分配一个struct evbuffer结构，需要调用evbuffer_free释放内存。

void evbuffer_free(struct evbuffer *buffer)

释放buffer所占用的内存。

int evbuffer_add_buffer(struct evbuffer *outbuf, struct evbuffer *inbuf)

移动数据从一个evbuffer到另一个evbuffer。

实际上还是调用了evbuffer_add添加数据到outbuf中。但会清除inbuf中的数据。

返回值：成功返回0， 失败返回-1。

int evbuffer_add_printf( struct evbuffer *, const char* fmt, )

添加一个格式化的字符串到evbuffer尾部。

u_char *evbuffer_find(struct evbuffer *buffer, const u_char *what, size_t len)

查找缓冲区中是否存在指定的字符串what。

注意这里使用的是u_char类型，说明有可能查找的数据不是以’\0’结尾

如果存在返回指向字符串what的指针，没有则返回NULL。

int evbuffer_read(struct evbuffer *buf, int fd, int howmuch)

调用read/recv函数，从文件描述符fd上读取数据到evbuffer中。如果缓冲区不够，调用evbuffer_expand扩充缓冲区。

int evbuffer_write(struct evbuffer *buffer, int fd)

把缓冲区中的数据，调用send/write函数写入文件描述符fd上， 如果send/write函数写入的字节数大于0，则调用evbuffer_drain删除已写的数据。

char *evbuffer_readline(struct evbuffer *buffer)

读取数据以"\r\n","\n\r", "\r" 或者 "\n"结尾。

返回动态分配内存，需要调用者自己使用free来释放内存。返回一个以“\0”结尾的字符串。

void evbuffer_setcb(struct evbuffer *buffer,
    void (*cb)(struct evbuffer *, size_t, size_t, void *),
    void *cbarg)

设置回调函数。当缓冲区中发生变化时， 调用设置的回调函数。

Evbuffer提供的API已经全部介绍完毕，接下来我们通过一个实例进一步学习如何使用evbuffer, 想要使用evbuffer，系统里必须已经安装了libevent。

例子代码如下：evbuffer-test.c

#include <stdio.h>
#include <string.h>
#include <assert.h>

//引入libevent头文件
#include "event.h"

int main(int argc, char** argv)
{
    struct evbuffer* buff = NULL;
    char c, c2[3] = {0};
    
    buff = evbuffer_new();
    assert(buff != NULL);
    
    evbuffer_add(buff, "1", 1);
    evbuffer_add(buff, "2", 1);
    evbuffer_add(buff, "3", 1);
    evbuffer_add_printf(buff, "%d%d", 4, 5);
    assert(buff->off == 5);

    evbuffer_remove(buff, &c, sizeof(char));
    assert(c == '1');
    evbuffer_remove(buff, &c, sizeof(char));
    assert(c == '2');
    evbuffer_remove(buff, &c, sizeof(char));
    assert(c == '3');
    evbuffer_remove(buff, c2, 2);
    assert(strcmp(c2, "45") == 0);
    
    assert(buff->off == 0);
  
    evbuffer_add(buff, "test\r\n", 6);
    assert(buff->off == 6);
    
    char* line = evbuffer_readline(buff);
    assert(strcmp(line, "test") ==0);
    assert(buff->off == 0);
    free(line);
   
    evbuffer_free(buff);
    
    printf("ok\n");
    
    return 0;
}