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
:需要一个事件描述符或者socketEV_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
:仅限WindowsEVENT_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