Libevent源码剖析（一）之接口详解

Libevent V2.1版本源码剖析，准备先将提供接口进行分类，根据接口逐步深入源码。

事件集合处理接口（struct event_base）

事件集合处理接口存在两种初始化的方式，一种是直接创建默认的接口，另外一种是根据配置对象创建相应的集合，需要用户额外的维护一个配置对象。

Libevent提供的默认初始化版本：

struct event_base *event_base_new(void)

Functionality：创建一个新的event_base，为Libevent维护一个事件集合。
Parameters：None
Reterned Value：一个初始化的event_base

void event_base_free(struct event_base *)

Functionality：释放与event_base相关联的所有内存，并释放event_base结构。注意：这个函数不会关闭任何fds或者释放由event_new()传递的内存。
Parameters：提供想要销毁的struct event_base对象
Returned Value：None

int event_reinit(struct event_base *base)

Functionality：在调用fork()之后重新初始化，一些事件在fork()之后不能继续存在，需要调用该函数重新进行初始化
Parameters：需要重新初始化的struct event_base对象
Returned Value：成功返回0，否则返回-1

int event_base_dispatch(struct event_base *)

Functionality：事件循环调度，将程序的控制权交给事件处理机制。该循环将运行事件库，直到没有待处理事件，或者直到调用event_base_loopbreak()或者event_base_loopexit()暂时的停止事件循环
Parameters：struct event_base对象
Returned Value：成功返回0，错误返回-1，用户退出返回1。

const char *event_base_get_method(const struct event_base *)

Functionality：返回当前正在使用的事件分发机制
Parameters：提供的struct event_base对象
Returned Value：epoll，poll，select等

const char **event_get_supported_methods(void)

Functionality：返回系统支持的所有的事件分发机制
Parameters：None
Returned Value：epoll，poll，select等

int event_gettime_monotonic(struct event_base *base, struct timeval *tp)

Functionality：从struct event_base对象中查询当前的时间
Parameters：struct event_base对象以及即将被填充的timeval参数
Returned Value：成功返回0，失败返回-1

int event_base_get_num_events(struct event_base *, unsigned int)

Functionality：获取标志中指定的事件的数量
Parameters：传入event_base结构

• EVENT_BASE_COUNT_ACTIVE：返回活动的事件数量
• EVENT_BASE_COUNT_VIRTUAL：返回内部的虚拟事件数量
• EVENT_BASE_COUNT_ADDED：返回使用event_add()添加的事件数量
  Returned Value：根据标志位，返回事件的数量

int event_base_get_max_events(struct event_base *, unsigned int, int)

Functionality：根据上述的三个标志，返回允许的最大事件数量
Parameters：
1）：event_base结构
2）：上述标志的按位与
3）：清除选项，用于重置最大计数
Returned Value：返回事件的最大数量

为事件集合对象维护一个可配置对象：

struct event_config *event_config_new(void)和void event_config_free(struct event_config *cfg)

Functionality：分配与删除一个事件配置对象，事件配置对象可以用户修改Libevent的行为，在随后的一些设置中可以对这个config对象进行设置。
Parameters：None
Returned Value：返回一个新分配的对象。

int event_config_avoid_method(struct event_config *cfg, const char *method)

Functionality：输入一个避免进入配置的事件方法。可以用来避免某些不支持的事件。
Parameters：event_config结构和避免进入事件的名称
Returned Value：成功返回0，失败返回-1

int event_base_get_features(const struct event_base *base)

Functionality：返回事件库支持的功能的位掩码
Parameters：提供想要观察的struct event_base对象
Returned Value：返回以下功能位的组合：

• EV_FEATURE_ET：是否支持ET模式
• EV_FEATURE_O1：触发一个事件的效率O（1）或者O（N）
• EV_FEATURE_FDS：需要一个事件描述符或者socket
• EV_FEATURE_EARLY_CLOSE：在关闭时丢弃所有的数据

int event_config_require_features(struct event_config *cfg, int feature)

Functionality：输入应用程序需要的必须的事件方法，根据上述提供的标志进行组合
Parameters：event_config事件配置对象和事件需要的标志位的组合
Returned Value：成功返回0，失败返回-1

int event_config_set_flag(struct event_config *cfg, int flag)

Functionality：设置一个或多个标志决定event_base如何初始化以及如何工作
Parameters：设置的标志是以下位的组合

• EVENT_BASE_FLAG_NOLOCK：不为event_base分配锁，这样是用于单线程环境，在多线程下不安全
• EVENT_BASE_FLAG_IGNORE_ENV：配置时不检查EVENT_*环境变量
• EVENT_BASE_FLAG_STARTUP_IOCP：仅限Windows
• EVENT_BASE_FLAG_NO_CACHE_TIME：在每次超时后进行回调检查
• EVENT_BASE_FLAG_EPOLL_USE_CHANGELIST：如果使用epoll作为事件分发器，可以对事件进行批量处理，而更少的进行系统调用。如果使用了dup()之类的复制操作，会使产生难以检查的错误。
• EVENT_BASE_FLAG_PRECISE_TIMER：是否使用慢的但是精度更高的定时器配置。

Returned Value：成功返回0，失败返回-1

struct event_base *event_base_new_with_config(const struct event_config *)

Functionality：根据event_config初始化一个event_base对象
Parameters：event_config对象
Returned Value：成功返回event_base对象，失败返回NULL

int event_base_set(struct event_base *, struct event *)

Functionality：将事件与事件库关联起来，事件不能处于活动/挂起状态
Parameters：struct event对象与struct event_base对象
Returned Value：成功返回0，失败返回-1

int event_base_loop(struct event_base *, int)

Functionality：等待事件激活并运行回调函数，这是一个更灵活的event_base_dispatch()版本。默认情况下，此循环将运行事件库，直到没有更多待处理或活动事件，或直到调用event_base_loopbreak（）或event_base_loopexit（）。
Parameters：event_base结构和以下参数的任意组合：

• EVLOOP_ONCE：阻塞，直到有活动的事件，然后退出，执行所有的活动事件
• EVLOOP_NONBLOCK：非阻塞模式，知道有活动事件发生，执行完回调函数，退出
• EVLOOP_NO_EXIT_ON_EMPTY：不要退出循环，知道我们调用event_base_loopbreak()和event_base_loopexit()

Returned Value：成功返回0，失败返回-1

int event_base_loopexit(struct event_base *, const struct timeval *)

Functionality：在指定时间后退出循环。给定定时器到期后，下一个event_base_loop将会处理已经就绪的事件，然后退出，再次阻塞事件
Parameters：event_base结构和定时器时间
Returned Value：成功返回0，失败返回-1

int event_base_loopbreak(struct event_base *)

Functionality：立即终止一个活动的event_base_loop()。在手头的事件处理完成后终止循环。通常在回调函数调用这个函数
Parameters：struct event_base对象
Returned Value：成功返回0，失败返回-1

int event_base_loopcontinue(struct event_base *)

Functionality：与上述break作用相反，意味着loop继续开始工作。如果事件循环没有启动，这个函数调用无效
Parameters：struct event_base对象
Returned Value：成功返回0，失败返回-1

int event_base_got_exit(struct event_base *)

Functionality：检查事件循环是否被event_base_loopexit()退出。一般在调用event_base_loopexit()之后立刻调用
Parameters：struct event_base对象
Returned Value：loopexit()已经被调用返回True，否则返回false

int event_base_got_break(struct event_base *)

Functionality：检查事件循环是否被break，一般在event_base_loopbreak()之后调用
Parameters：struct event_base对象
Returned Value：如果被调用返回True，否则返回False

struct event *event_base_get_running_event(struct event_base *base)

Functionality：获取目前正在被处理的事件
Parameters：struct event_base对象
Returned Value：成功返回struct event对象，失败返回NULL

struct event_base *event_get_base(const struct event *ev)

Functionality：返回事件事件集
Parameters：提供查询的struct event对象
Returned Value：返回事件集对象

int event_base_priority_init(struct event_base *, int)

Functionality：设置不同事件优先级的数量。默认情况下，Libevent以相同的优先级安排所有活动的事件。这个函数在event_base_dispatch()之前调用。
Parameters：已经初始化的struct event_base结构和不同的优先级事件的数量
Returned Value：成功返回0，失败返回-1

const struct timeval *event_base_init_common_timeout(struct event_base *base, const struct timeval *duration)

Functionality：准备为一个struct event_base对象使用相同的大量的超时时间。不建议使用，更好的方式是使用event_add()添加事件时，顺便添加超时时间
Parameters：struct event_base对象以及超时时间
Returned Value：返回添加的超时时间对象

void event_base_active_by_fd(struct event_base *base, evutil_socket_t fd, short events)

Functionality：将struct event_base中由fd描述的事件手动设置为激活状态
Parameters：struct event_base对象，由eventfd描述的事件以及想要激活的事件掩码
Returned Value：None

void event_base_active_by_signal(struct event_base *base, int sig)

Functionality：激活给定信号描述的事件
Parameters：传入管理事件的集合以及想要激活的信号
Returned Value：None

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)

Functionality：对struct event_base中所有的事件执行一个回调函数，这个函数不能修改已存在事件的状态
Parameters：struct event_base对象，需要执行的回调函数以及回调函数需要的参数
Returned Value：成功返回0，失败返回-1

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

Functionality：填充设置时间的缓存
Parameters：struct event_base对象以及将要被填充的struct timeval对象
Returned Value：成功返回0，失败返回-1

int event_base_update_cache_time(struct event_base *base)

Functionality：更新struct event_base中的时间
Parameters：传入的struct event_base对象
Returned Value：成功返回0，失败返回-1

日志接口

#define EVENT_LOG_DEBUG 0
#define EVENT_LOG_MSG   1
#define EVENT_LOG_WARN  2
#define EVENT_LOG_ERR   3

typedef void (*event_log_cb)(int severity, const char *msg)        //事件的回调函数
typedef void (*event_fatal_cb)(int err)        //如果遇到致命错误，调用这个函数

void event_set_log_callback(event_log_cb cb)

Functionality：重定向日志消息
Parameters：如果cb为空，使用Libevent提供的日志消息。
Returned Value：None

void event_set_fatal_callback(event_fatal_cb cb)

Functionality：在出现致命错误时，调用用户提供的函数。默认情况下，调用exit(1)
Parameters：用于提供的处理致命错误的cb
Returned Value：None

void event_enable_debug_logging(ev_uint32_t which)

Functionality：打开调试日志，并将它发送到默认的日志处理程序
Parameters：

• EVENT_DBG_ALL：打开调试日志
• EVENT_DBG_NONE：关闭调试日志

Returned Value：None

事件处理接口（struct event）

Libevent支持的事件：

#define EV_TIMEOUT	0x01        //发生超时事件
#define EV_READ		0x02        //读事件
#define EV_WRITE	        0x04        //写事件
#define EV_SIGNAL	0x08        //信号事件
#define EV_PERSIST	0x10        //持续性事件，在激活后不会自动移除
#define EV_ET		0x20        //支持ET类型
#define EV_CLOSED	0x80        //关闭事件

void *event_self_cbarg(void)

Functionality：返回一个用于指定事件本身必须用作回调参数的值,就是返回回调函数的参数。struct event * ev = event_new（base，sock，events，callback，event_self_cbarg（））
Parameters：None
Returned Value：返回event回调函数的参数

struct event *event_new(struct event_base *, evutil_socket_t, short, event_callback_fn, void *)

Functionality：分配新的事件结构
Parameters：
1）：此事件依赖于event_base
2）：事件的socket fd
3）：关注的事件类型
4）：事件将要调用的回调函数
5）：回调函数的参数
Returned Value：成功返回新的event，错误返回NULL

int event_assign(struct event *, struct event_base *, evutil_socket_t, short, event_callback_fn, void *)

Functionality：同上述函数作用一样，不过需要用户提供内存（一般在堆上）
Parameters：同上述
Returned Value：成功返回0，失败返回-1

void event_free(struct event* )

Functionality：释放由event_new()产生的event对象
Parameters：event结构体
Returned Value：None

int event_base_once(struct event_base *, evutil_socket_t, short, event_callback_fn, void *, const struct timeval *)

Functionality：一个事件只需要被处理一次，不需要用户提供event对象
Parameters：timeval表示等待的最长的时间
Returned Value：成功返回0，失败返回-1

int event_add(struct event *ev, const struct timeval *timeout)

Functionality：将一个事件添加到一组待定的事件中，timeout指定超时时间。如果timeout为空，则不会发生超时事件。
Parameters：表示事件的struct event对象以及超时时间
Returned Value：成功返回0，失败返回-1。

int event_remove_timer(struct event *ev)

Functionality：从挂起的事件中删除定时器，但是并不删除事件本身。如果事件具有预定的超时时间，则取消超时事件，但是依旧等待事件
Parameters：struct event对象
Returned Value：成功返回0，失败返回-1

int event_del(struct event *)

Functionality：从事件集中删除已经添加的事件，如果事件正在被执行或者已经被移除，没有效果
Parameters：struct event对象
Returned Value：成功返回0，失败返回-1

void event_active(struct event *ev, int res, short ncalls)

Functionality：使挂起的事件生效
Parameters：
1）：struct event对象
2）：一组传递给事件的标志
3）：这个参数已经被忽略
Returned Value：None

int event_pending(const struct event *ev, short events, struct timeval *tv)

Functionality：检查特定的事件的状态，是否被添加
Parameters：
1）：struct event对象
2）：请求查询的事件类型
3）：如果该字段不为NULL。并且事件上有超时事件发生，被填充为超时时间
Returned Value：如果事件已经被添加，返回true，否则返回false

int event_initialized(const struct event *ev)

Functionality：测试一个事件是否被初始化
Parameters：即将被测试的struct event对象
Returned Value：已经被初始化返回1，没有被初始化返回-1

evutil_socket_t event_get_fd(const struct event *ev)

Functionality：返回事件描述的eventfd
Parameters：即将提取fd的struct event对象
Returned Value：返回事件描述符

int event_base_get_npriorities(struct event_base *eb)

Functionality：获取不同的优先级事件的数量
Parameters：struct event_base对象
Returned Value：返回优先级等级的数量

int event_priority_set(struct event *, int)

Functionality：为事件分配优先级
Parameters：struct event对象以及优先级
Returned Value：成功返回0，失败返回-1

short event_get_events(const struct event *ev)

Functionality：返回struct event关注的事件
Parameters：提供查询的struct event对象
Returned Value：返回事件集

event_callback_fn event_get_callback(const struct event *ev)

Functionality：获取用于处理事件的回调函数对象
Parameters：提供查询的struct event对象
Returned Value：返回回调事件集合

void *event_get_callback_arg(const struct event *ev)

Functionality：返回回调函数使用的参数
Parameters：提供查询的struct event对象
Returned Value：None

int event_get_priority(const struct event *ev)

Functionality：获取事件的优先级
Parameters：提供查询的struct event对象
Returned Value：返回事件的优先级

void event_get_assignment(const struct event *event, struct event_base **base_out, evutil_socket_t *fd_out, short *events_out, event_callback_fn *callback_out, void **arg_out);

Functionality：将事件相关信息复制到传入的参数上面，带有out的都是传出的参数
Parameters：传入一个需要观察的struct event对象，其余的都是根据这个struct event指针返回填充的信息
Returned Value：None

将信号事件与定时器事件宏化：

#define evtimer_assign(ev, b, cb, arg)  event_assign((ev), (b), -1, 0, (cb), (arg))       
#define evtimer_new(b, cb, arg)	       event_new((b), -1, 0, (cb), (arg))
#define evtimer_add(ev, tv)		event_add((ev), (tv))
#define evtimer_del(ev)			event_del(ev)
#define evtimer_pending(ev, tv)		event_pending((ev), EV_TIMEOUT, (tv))
#define evtimer_initialized(ev)		event_initialized(ev)

#define evsignal_add(ev, tv)		event_add((ev), (tv))
#define evsignal_assign(ev, b, x, cb, arg)		event_assign((ev), (b), (x), EV_SIGNAL|EV_PERSIST, cb, (arg))
#define evsignal_new(b, x, cb, arg)		event_new((b), (x), EV_SIGNAL|EV_PERSIST, (cb), (arg))
#define evsignal_del(ev)		event_del(ev)
#define evsignal_pending(ev, tv)	event_pending((ev), EV_SIGNAL, (tv))
#define evsignal_initialized(ev)	event_initialized(ev)

typedef void (*event_callback_fn)(evutil_socket_t, short, void *)        //处理事件的回调函数

全局查询接口

size_t event_get_struct_event_size(void)

Functionality：获取struct event的大小
Parameters：None
Returned Value：返回struct event对象的大小

const char *event_get_version(void)和ev_uint32_t event_get_version_number(void)

Functionality：获取Libevent的版本
Parameters：None
Returned Value：分别返回当前版本的不同的表达形式

void event_set_mem_functions(void *(*malloc_fn)(size_t sz), void *(*realloc_fn)(void *ptr, size_t sz), void (*free_fn)(void *ptr))

Functionality：提供自己的内存管理函数，以覆盖Libevent默认使用的malloc，realloc和free
Parameters：传入的三个内存分配函数
Returned Value：None

void libevent_global_shutdown(void)

Functionality：彻底的销毁掉由Libevent管理的资源，用户管理的一些缓冲区除外
Parameters：None
Returned Value：None