• 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

  • 相关阅读:
    P2764 最小路径覆盖问题
    P1402 酒店之王 网络流
    P2597 [ZJOI2012]灾难 拓扑排序
    FJOI2017 矩阵填数
    2019.2.27模拟
    2019.2.26模拟
    SDOI2013 方程
    [AH2017/HNOI2017]抛硬币
    Lucas定理和扩展Lucas定理
    LuoguP4861 按钮
  • 原文地址:https://www.cnblogs.com/ukernel/p/9191074.html
Copyright © 2020-2023  润新知