libevent的事件分发相关接口

5.1 event_base_dispatch

功能

执行事件分发循环。

备注

本函数是event_base_loop的一个简单封装。代码如下：

int
event_base_dispatch(struct event_base *event_base)
{
	return (event_base_loop(event_base, 0));
}

本函数执行事件循环，直到没有更多的pending的或者active的事件，或者event_base_loopbreak和event_base_loopexit被调用了，才会退出循环。

原型

int event_base_dispatch(struct event_base *base);

5.2 event_base_loop

功能

执行事件分发循环。等待事件就绪，并且回调设置在事件上面的回调函数。

备注

事件分发循环默认将一直运行，直到没有更多的pending或者active的事件，或者event_base_loopbreak和event_base_loopexit被调用。

原型

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

参数说明：
flags:

• EVLOOP_ONCE
  事件循环将一直阻塞，直到我们有active事件，一旦所有的active事件已经回调完毕，事件循环将立即退出。

• EVLOOP_NONBLOCK
  不在事件循环中阻塞，查看是否有事件active，如果有，则回调优先级最高的事件，然后退出。

• EVLOOP_NO_EXIT_ON_EMPTY
  即使没有pending事件，事件循环也不退出，直到event_base_loopbreak和event_base_loopexit被调用。

5.3 event_base_loopbreak

功能

立即停止 event_base_loop事件循环

备注

如果event_base_loopbreak被调用，那么event_base_loop在完成当前event的回调后退出时间循环。通常event_base_loopbreak是在事件的回调函数中被调用的，这种行为好比是循环代码中的break指令。

后续再调用event_base_loop将正常进行，不受此影响。

原型

int event_base_loopbreak(struct event_base *eb);

5.4 event_base_loopexit

功能

通知event_base在指定的超时时间后退出事件循环。

备注

在给定的tv超时之后，event_base会在event_base_loop事件循环中完成active事件的回调然后退出。
后续再调用event_base_loop将正常进行，不受此影响。

原型

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

5.5 event_base_get_running_event

功能

获取当前正在被回调的事件。

备注

本函数要求必须在事件回调函数中执行来获取当前的事件。

原型

struct event *event_base_get_running_event(struct event_base *base);

5.6 event_base_dump_events

功能

将所有event_base中pending的或者active的事件输出到指定的标准文件中。

备注

本函数用在调试的时候。而且libevent不保证不同的libevent版本输出的格式是相同的。

原型

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

5.7 event_base_active_by_fd

功能

根据文件句柄fd来激活与该句柄关联的所有的事件event。

备注

本函数仅激活pending状态的事件。那些还没有被添加进来进入pending状态的将不会被激活。

原型

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

5.8 event_base_active_by_signal

功能

根据signal好来激活与该signal关联的所有的事件event。

备注

本函数仅激活pending状态的事件。那些还没有被添加进来进入pending状态的将不会被激活。

原型

void event_base_active_by_signal(struct event_base *base, int sig);

5.9 event_base_foreach_event

功能

遍历所有pending和active状态的事件，对于每个事件调用输入参数fn指定的回调函数。

备注

回调函数禁止调用任何可能修改event_base的函数，任何修改event的函数，或者添加、删除event到event_base中的函数。

event_base_foreach_event会在整个循环过程中都加锁运行，因此对于慢回调则需要注意。

libevent本身自己也会在event_base中添加少量的一些event，因此在遍历的过程中你不应该假设只会碰到你自己添加的event。

如果希望本函数的遍历过程一直持续下去，那么回调函数必须返回0，返回其它值将导致循环立即结束。

原型

int event_base_foreach_event(struct event_base *base, 
							 event_base_foreach_event_cb fn, void *arg);

5.10 event_base_gettimeofday_cached

功能

获取当前时间。

备注

通常，这个值只有在实际处理事件回调时才会被cache，如果回调函数需要执行很长时间，那么可能会变得非常不准确。

原型

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

5.11 event_base_update_cache_time

功能

更新缓存中的当前时间。

备注

可以通过这个函数强制更新缓存中的当前时间。避免获得的当前时间因为回调时间过长而变得不准确。

原型

int event_base_update_cache_time(struct event_base *base);

5.12 event_base_get_num_events

功能

获取event_base中指定flag类型的事件event的数量。

备注

原型

int event_base_get_num_events(struct event_base *eb, unsigned int flags);

参数说明：
flags:

• EVENT_BASE_COUNT_ACTIVE: 获取active状态的event。
• EVENT_BASE_COUNT_ADDED: 获取pending状态的event。

5.13 event_base_get_max_events

功能

获取指定flag的最大事件数量。

备注

原型

int event_base_get_max_events(struct event_base *eb, unsigned int flags, int 
							  clear);

参数说明：
clear 参数可以在获取到最大值后重置最大值计数器。