初入libevent的人，很可能是第一次接触异步编程。Libevent的编程思想，建议还是多看前人的程序，或者是看libevent本身的文档学习。
或者是介绍另外一个库，那就是libuv，它是libev某种意义上的的替代品（而libev又可以算是libevent的某种替代品笑）。libuv的文档我记得也有对异步编程的介绍。好了，这不是本文的内容。
本文地址：https://segmentfault.com/a/1190000005359466
Reference
Programming with Libevent
翻译：Libevent参考手册第一章：设置libevent
序章和知识准备
在文档序章中举了一个例子，介绍了异步编程。这里面列举了几个典型的函数，如下：
头文件#include <event2/event.h>
结构体struct event
函数event_new(), event_free(), event_base_new(), event_add(), event_base_dispatch()
Libevent的基本思路是使用select()。但是使用select很多的话，往往系统开销很大，所以各个UNIX和类UNIX系统是使用了select的替代。但是不同的系统使用的替代各不相同，这导致程序移植起来很麻烦。
Linux：epoll()
BSD：kqueue()
Solaris：/dev/poll, evports
Libevent使用BSD License而不是GPL，这使得它可以很方便地用在一个闭源的项目里面
Libevent的特性
-
evutil：不同平台的抽象层，主要是网络接口部分 -
event,event_base：libevent的核心API -
bufferevent：缓存化的read/write接口，并且可以与SSL互相封装。
另外还有几个我就不列出了，个人很少用
Libevent的库
-
libevent_core：Libevent的核心API和功能，包含了上述主要模块 -
libevent_extra：Libevent提供的额外功能包，这些目前还用不上 -
libevent：包含上述两个，但是建议以后不要使用
之所以还有event2文件夹，是因为这个文件夹下是新的（也就是目前使用的）libevent库
创建一个event_base
每一个event_base持有和管理多个event，并且判断哪些event是被激活了的。但是这发生在一个单一的线程内。如果你想哟啊在多个线程内并行处理event，则需要在每个线程中各创建一个event_base。
获得一个默认的event_base
struct event_base *event_base_new(void);这个函数alloc并返回一个带默认配置的event base。
获得一个复杂的event_base
struct event_config *event_config_new(void);
struct event_base *event_base_new_with_config(const struct event_config *cfg);
void event_config_free(struct event_config *cfg);这几个函数的基本功能就是：获得一个config，配置好后作为event_base创建的参数。用完后记得将config给free掉。
而配置config则需要用到要以下两个函数：
int event_config_require_features(struct event_config *cfg, enum event_method_feature feature);这里的枚举值有以下几个：EV_FEATURE_ET：需要边沿触发的I/OEV_FEATURE_OI：在add和delete event的时候，需要后端（backend）方法EV_FEATURE_FDS：需要能够支持任意文件描述符的后端方法
上述的值都是mask，可以位与（|）。
int event_config_set_flag(struct event_config *cfg, enum event_base_config_flag flag);这里的枚举值有以下几个：EVENT_BASE_FLAG_NOLOCK：event_base不使用lock初始化EVENT_BASE_FLAG_IGNORE_ENV：挑选backend方法时，不检查EVENT_xxx标志。这个功能慎用EVENT_BASE_FLAG_STARTUP_IOCP：仅用于Windows。起码我不关心EVENT_BASE_FLAG_NO_CACHE_TIME：不检查timeout，代之以为每个event loop都准备调用timeout方法。这会导致CPU使用率偏高EVENT_BASE_FLAG_EPOLL_USE_CHANGELIST：告诉libevent如果使用epoll的话，可以使用基于“changlist”的backend。EVENT_BASE_FLAG_PRECISE_TIMER：使用更加精确的定时机制
以上两个函数成功时返回0，失败时返回-1；
设置event_base的分离时间
int event_config_set_max_dispatch_interval (
struct event_config *cfg,
const struct timerval *mac_interval,
int max_callbacks,
int min_priority);在检查高优先级的event之前，通过限制低优先级调用来防止优先级反转（priority inversion）。而另一个限制条件是max_interval参数，这是表示高优先级事件被调用的最大延时。
成功时返回0，失败时返回-1。默认情况下，`event_base`被设置成默认优先级
检查event_base的backend方法
const char **event_get_supported_methods(void);返回一个char*数组，说明了libevent支持的所有backend方法。数组以NULL结尾。
读取指定event_base的配置
const char *event_base_get_method (const struct event_base *base);
enum event_method_feature event_base_get_features (const struct event_base *base);释放一个event_base资源
int event_base_priority_init (structr event_base *base, int n_priorities);第二个参数表示可支持的优先级，至少为1。0是最优先。这样，event_base中的优先级即为0 ~ nPriorities-1。
最大支持的优先级数为EVENT_MAX_PRIORITIES。
int event_base_get_npriorities(struct event_base *base);上一个函数的读版本
使用事件循环event loop
当event_base和其中的event都配置好了之后，就可以启用libevent了。Event的配置在后文说，这里先讲event loop的运行。
运行loop
int event_base_loop (struct event_base *base, int flags);
int event_base_dispatch (struct event_base *base);函数的行为是：运行event_base，直到没有event被注册在event_base中位置。这是默认的行为，也就是说，当没有pending或active事件时，函数返回。
参数flags可以用来修改默认行为，有以下掩码值：
-
EVLOOP_ONCE：等待并执行active事件，循环执行到没有事件可执行 -
EVLOOP_NONBLOCK：循环不等待事件触发，而是即检查即回调 -
EVLOOP_NO_EXIT：没有事件仍不退出，而是由其他函数触发退出
第二个函数的作用是相同的，等效于使用默认的flags。
停止loop
int event_base_loopexit (struct event_base *base, const struct timeval *tv);
int event_base_loopbreak (struct event_base *base);第一个函数要求event_base在指定时间后立即停止，如果tv为NULL，则立即停止。但这个函数实际上会使得event_base在执行完全部的callback之后才返回。
第二个函数的不同之处是使event_base在执行完当前的callback之后，无视其他active事件而立即停止。但需要注意的是，如果当前没有callback，这会导致event_base等到执行完下一个callback之后才退出。
int event_base_got_exit (struct event_base *base);
int event_base_got_break (struct event_base *base);用来判断是否获得了exit或者是break请求。注意返回值实际上应该是BOOL而不是int
检查event_loop内部的时间
int event_base_gettimeofday_cached (struct event_base *base, struct timeval *tv);
int event_base_update_cache_time (struct event_base *base);获得event_loop时间。第一个函数获得event_loop最近的时间，比较快，但是不精确。第二个函数可以强制event_loop立即同步更新时间。
将event_base的状态存入文件
void event_base_dump_events (struct event_base *base, FILE *f);实际上我觉得这个函数能够保存的信息还是不够多。另外，你可以将/dev/stdout句柄打开之后传入也是可以的
在event_base中运行每一个event
typedef int (*event_base_foreach_Event_cb) (const struct event_base *,
const struct event *,
void *);
int event_base_foreach_event (struct event_base *base,
event_base_foreach_Event_cb fn,
void *arg);这个函数比较谜。按照资料，这个函数会检查event_base中所有的active或pending的Event，然后调用传入的一个回调，逐个调用。
注意这里的callback只允许用来检查event的状态，不允许修改。此外，callback的执行时间不应太长，因为会有锁保护。
为什么说这个函数谜呢？因为我实际上在libevent的头文件中找-不-到这个函数啊！资料里面是有的，但是.h文件中不存在，强行调用，也是找不到函数。从描述来看这个函数其实很好用，也非常适合初学者们跟踪学习event_base及其event的状态。但是……用不了。
使用事件“event”
Libevent的基本处理单元是event，每个event代表一组条件：
- 做好read或write准备的文件描述符
- 正在准备好read或write准备的文件描述符（边沿触发I/O，没用过，不懂）
- 超时
- 信号被触发
- 用户触发的事件
当一个event被设置好，并且关联到一个event_base里面时，它被称为“initialized”。此时你可以执行add，这使得它进入pending状态。当event被触发或超时时，它的状态称为active，这个情况下对应的callback会被调用。如果event被配置为persist，那么它在callback执行前后都会保持pending的状态。可以通过delete来使得一个event从pending状态重新变成nonpending。
创建一个event对象
typedef void (*event_callback_fn) (evutil_socket_t, short, void *);
struct event *event_new (struct event_base *base,
evutil_socket_t fd,
short what,
event_callback_fn cb,
void *arg);
void event_free (struct event *event);创建一个新的event。其中fd是文件描述符，需要自行初始化之后再作为参数传入。event_free()释放event的资源。如果event是active或者是pending状态，则函数会将event先变成非active且非pending的状态，然后再释放它。
参数what表示这个event的需要关注绑定在该fd上的哪些事件。有以下几个掩码值：
- EV_TIMEOUT：超时
- EV_READ：有数据可读
- EV_WRITE：数据可写
- EV_SIGNAL：系统发出的信号（
signal） - EV_PERSIST：持续事件
- EV_ET：边沿触发
关于EV_PERSIST
int event_del (struct event *event);
前文所说的add动作的反动作。EV_PERSIST使得一个event不会自动被event_base给delete掉，除非显式地调用这个函数。
使用event自己的ID作为回调参数
回调的时候会传入自定义的arg。但是如果想要让回调能够接受自己的struct event指针作为参数，那么应该使用以下函数：void *event_self_cbarg();
比如：
struct event *aEvent = event_new (pBase, aFd,
EV_READ | EV_TIMEOUT,
aCallback,
event_self_cbarg());Note on 2016-11-21: 在最新版本的 libevent 中，这个函数已经被停用了。并且目前并没有这个函数的合适替代。
超时事件
纯超时事件不需要fd（传入-1即可）。Libevent定义了一些方便的用于创建超时事件的宏：
evtimer_new (base, callback, arg)
evtimer_add (ev, tv)
evtimer_del (ev)
evtimer_pending (ev, tv_out)从测试结果来看，这里的timer event都是一次性执行的，所以请自行在callback中重新add
信号事件
信号时间也不需要fd，但不是传入-1，而是对应的signum。
evsignal_new (base, signum, callback, arg) // 自带EV_PERSIST
evsignal_add (ev, tv)
evsignal_del (ev)
evsignal_pending (ev, what, tv_out)signal事件的callback是异步的，所以很安全，不像signal()中的回调那样有诸多限制。
注意：不要给signal事件设置timeout
使事件进入pending和non-pending
int event_add (struct event *ev, const struct timeval *tv);
int event_del (struct event *ev);
int event_remove_timer (struct event *ev);使用优先级的事件
int event_priority_set (struct event *event, int priority);将事件优先级设置在event base的优先级和0之间。
观察event状态
int event_pending (const struct event *ev, short what, struct timeval *tv_out);注意这个函数的返回值实际上是BOOL。函数判断event是否为给定的flag（what）而被pending或active。如果tv_out非空，并且EV_TIMEOUT被设置了，那么判断完状态后，event得timeout也会被通过这个参数返回回来。
以下是其他一目了然的get函数：
evutil_short_t event_get_fd (const struct event *ev);
struct event_base *event_get_base (const struct event *ev); // 注意这个很常用
short event_get_events (const struct event *ev);
event_callback_fn event_get_callback (const struct event *ev);
void *event_get_callback_arg (const struct event *ev);
int event_get_priority (const struct event *ev);
void event_get_assigement (const struct event *event,
struct event_base **base_out,
evutil_short_t *fd_out,
short *events_out,
event_callback_fn *callback_out,
void *arg_out);寻找当前运行中event
struct event *event_base_get_running_event (struct event_base *base);注意这个函数只支持在event的loop中调用，在其它线程调用的话是不支持的
快速配置一个一次性的事件
int event_base_once (struct event_base *base,
evutil_socket_t fd,
short what,
event_callback_fn cb,
void *arg,
const struct timeval *tv);这个函数完成前面的event_new和event_add动作，并且不返回event对象。调用这个函数创建的对象直接加入到event_base中，并且执行了一次callback之后，自动delete和free掉。
Event的优先级默认，what不支持EV_SIGNAL和EV_PERSIST。
从libevent 2.1.2之后，即便一个event还没有被activate过，在event_base被释放时，也会一并被释放掉。在这之前这算是一个bug。不过也请注意其他所有不由libevent管理的资源（比如arg），要防止内存泄漏。
手动激活一个event
void event_active (struct event *ev, int what, short ncalls);用指定的标志来激活一个event，慎用该功能，特别是不要再callback中使用。但这是另一个比较谜的函数，因为我在我自己设计的字符设备驱动中使用这个函数，但是实际上我监听着这个设备的event却根本没有被激活。我的调用方式应该是没问题的，难道是还需要内核驱动做什么支持吗？（2016-7-5 笔记：这里说的可能只是不能在目标event的callback中使用，但是可以在其它无关事件的callback中调用。还没有确认，但是猜测的可能性是：这个函数只有在libevent的loop中调用才能生效，不能异步地在loop外部activate。已经确认了在loop内部是生效的，至于在外部无法生效的原因，是不是我所猜测的那样，目前我还找不到确认的答案）
优化了的公共超时事件
Libevent对add/del超时事件具有 O(logN)的性能，使用与多个不同超时时间的队列。但是如果有多个使用同一个超时值的事件，这样做就显得很低效了。此时libevent使用二进制堆算法（binary heep algorrithm）来完成这种任务。
此时libevent要涉及一个“common timeout”了：
const struct timeval *event_base_init_common_timeout (
struct event_base *base,
const struct timeval *duration);这个函数返回一个持续的timeval指针，指向common timeout。使用这个timeout的事件会被加入到binary heep中，并且只有你指定的特定event_base中有效。返回的timeval指针，可以把timeval值复制出来使用。
系列篇
Libevent官方文档学习笔记（1. libevent_core部分）（本文）
Libevent官方文档学习笔记（2. bufferevent部分）
Libevent官方文档学习笔记（3. evbuffer部分）
**粗体** _斜体_ [链接](http://example.com) `代码` - 列表 > 引用。你还可以使用@来通知其他用户。