Libevent library notes (four) commonly used function interface

1. Libevent related function description

1.1.evconnlistener_new_bind

函数功能：分配一个监听器对象，监听给定地址上的TCP连接 
	函数原型：
	EVENT2_EXPORT_SYMBOL
	struct evconnlistener *evconnlistener_new_bind(struct event_base *base,
	    evconnlistener_cb cb, void *ptr, unsigned flags, int backlog,
	    const struct sockaddr *sa, int socklen);
	参数说明：
	   @param base 关联的libevent框架上下文.
	   @param cb 当新连接到来时，进行回调的函数.如果函数为NULL,监听器按被禁用运行，知道函数被设置为非NULL值.
	   @param ptr 提供给回调函数的参数指针，（一般传递base，以便监听回调中使用）
	   @param flags 任意LEV_OPT_*的标识，一般服务器设置
LEV_OPT_REUSEABLE：端口复用
LEV_OPT_CLOSE_ON_FREE：释放资源的时候自动关闭
	   @param backlog 类似于listen函数的backlog参数，设置为-1则使用默认设置.
	   @param addr 监听器监听地址.
	   @param socklen 监听器监听地址的字节长度.
备注：这个函数相当于完成系统调用socket()、bind()、listen()，并设置accept回调函数

1.2.evconnlistener_cb monitor callback function prototype

函数功能：当监听器监听到一个新连接的时候进行回调（应该是socket的accept成功返回有效的socket描述符后，进行回调，其中fd对应accept返回的文件描述符值）.
函数原型：
typedef void (*evconnlistener_cb)(struct evconnlistener *listener, evutil_socket_t fd,
    struct sockaddr *sa, int socklen, void *user_data);
参数说明：
   @param listener 事件监听器
   @param fd 新的文件描述符，相当于服务器创建的与客户端通信的socket描述符
   @param addr 客户端地址
   @param socklen 客户端地址字节数
   @param user_arg  evconnlistener_new()中传入的自定义参数

1.3.event_new

函数功能：在被添加到上下文对象前.创建指定一个事件
函数原型：struct event *
event_new(struct event_base *base, evutil_socket_t fd, short events, void (*cb)(evutil_socket_t, short, void *), void *arg)
返回：
	返回一个事件，其能后续被event_add() and event_del()添加和删除操作. 如果发生错误，返回NULL。
描述：
	如果事件包含 EV_READ, EV_WRITE, or EV_READ|EV_WRITE其中的一种,那么fd是文件描述符或socket描述符 如果事件包含EV_SIGNAL,那么fd是一个信号数值 如果事件不包含以上任意一种标识，那么事件只能被超时或则手动调用event_active()进行触发，这种情况下fd需设置为-1.

  EV_PERSIST标识使event_add() 持续的，直到 event_del()被调用。否则只触发一次结束。通常EV_READ | EV_PERSIST, EV_WRITE | EV_PERSIST,
  EV_ET标识兼容EV_READ和EV_WRITE, 它告诉libevent框架使用边沿触发事件
  EV_TIMEOUT标识在此没有效果

  相同的fds可以进行多种事件的监听，但是需要相同的触发模式。

 当事件被激活时, 事件循环会调用回调函数,回调函数会传入3个参数. 
	第一个为fd.  
	第二个参数为触发事件的位域  EV_READ, EV_WRITE, or EV_SIGNAL.  EV_TIMEOUT 标识指示超时事件
    EV_ET指示边沿事件触发.
	第三个参数自定义的回调函数参数指针 
参数描述：
  @param base 事件附加到的libevent框架上下文
  @param fd 被监控的文件描述符或则信号 
  @param events 需要被监控的事件，通过位定义:  EV_READ, EV_WRITE,EV_SIGNAL, EV_PERSIST, EV_ET.
  @param callback 事件发生时，需要调用的函数，即回调函数
  @param callback_arg 调用回调函数时，传入的自定义参数
 
  相关联的其他函数为：event_free(), event_add(), event_del(), event_assign()

1.4.event_add

函数功能：在需等待事件集中添加一个事件.
函数原型：
EVENT2_EXPORT_SYMBOL
int event_add(struct event *ev, const struct timeval *timeout);
函数描述：
	当event_assign()或event_new()中指定的事件发生时，或则指定的超时时间到时，调度ev事件的执行。如果timeout设置为NULL, 则一直等待指定的匹配事件。
参数中的event必须已被event_assign()或则event_new()初始化， 如果事件已经有了一个预定的超时，调用将替换旧的timeout数值.
参数说明：
  @param ev 通过event_assign() 或event_new()初始化过的事件对象
  @param timeout 最大等待事件的时间,  NULL则一直等待
返回值：
	 0：成功,   -1 ：发生错误
  相关函数参见event_del(), event_assign(), event_new()

1.5.event_del

函数功能：从监测事件集合中删除事件.
函数原型：int event_del(struct event *ev)
函数描述：
   如果事件已经执行或则从未被添加，则没有效果 
参数说明：
  @param ev 需要从监测事件集合中删除的事件
返回值：
  @return 0：成功,   -1 ：发生错误
  @相关参见event_add()

1.6.event_free

函数功能：Deallocate a struct event * returned by event_new().
函数原型：void event_free(struct event *ev)
函数描述：
   如果事件处于待监测或则激活状态，则此函数将会先将事件设置为非监测和非激活。 在调用时会先调用event_del

1.7.bufferevent_socket_new

函数功能：通过一个已存在的socket描述符创建socket bufferevent
函数原型：struct bufferevent *bufferevent_socket_new(struct event_base *base, evutil_socket_t fd, int options);

参数说明：
  @param base 关联的框架上下文
  @param fd 关联的文件描述符.类似event_new 
  @param options 0或则BEV_OPT_*标识，一般只使用BEV_OPT_CLOSE_ON_FREE

返回值：
  @return  bufferevent结构体指针, 当出错时返回NULL
  @相关参见 bufferevent_free()
备注：在实现内部，会添加几个事件及回调，相关代码：
event_assign(&bufev->ev_read, bufev->ev_base, fd,
	    EV_READ|EV_PERSIST|EV_FINALIZE, bufferevent_readcb, bufev);
	event_assign(&bufev->ev_write, bufev->ev_base, fd,
	    EV_WRITE|EV_PERSIST|EV_FINALIZE, bufferevent_writecb, bufev);

1.8.bufferevent_setcb

函数功能：设置bufferevent事件的回调函数
函数原型：void bufferevent_setcb(struct bufferevent *bufev,
    bufferevent_data_cb readcb, bufferevent_data_cb writecb,
    bufferevent_event_cb eventcb, void *cbarg);
参数说明：
  @param bufev  需要设置回调函数的bufferevent事件
  @param readcb 数据可读时的回调，可设置为NULL不进行监测
  @param writecb 数据写入成功后进行回调通知，可设置为NULL不进行监测
  @param eventcb 当文件描述符有事件发生时的回调
  @param cbarg 回调调用时传入的自定义参数(readcb, writecb, and errorcb)
  @相关参见  bufferevent_new()

1.9.bufferevent_data_cb callback function type

原型：typedef void (*bufferevent_data_cb)(struct bufferevent *bev, void *ctx);
描述：读事件回调将被触发，当新数据到来时，可读数据大于设置的low watermark阈值（默认为0）；
    可写事件回调将被触发，当写缓存已经被耗尽或则低于low watermark阈值
参数说明： 
   @param bev 触发回调的bufferevent 
   @param ctx bufferevent_setcb方法中用户指定的参数	

1.10.bufferevent_read

函数功能：从bufferevent的读缓存区读取数据.
函数原型：size_t bufferevent_read(struct bufferevent *bufev, void *data, size_t size); 
参数说明：
  @param bufev  关联的bufferevent
  @param data  数据指针，用来存储从bufferevent读缓存区读到的数据 
  @param size 数据字节数

返回值：
  @return 读取的数据字节数

1.11.bufferevent_write

函数功能：写数据到bufferevent的写缓存区.
函数原型：int bufferevent_write(struct bufferevent *bufev,const void *data, size_t size);
函数描述：
  The bufferevent_write() function can be used to write data to the file
  descriptor.  The data is appended to the output buffer and written to the
  descriptor automatically as it becomes available for writing.
参数说明：
  @param bufev  关联的bufferevent
  @param data 数据指针，从此来源中获取数据，以写入到bufferevent写缓存区 
  @param size 数据字节数

返回值：
  @return 如果成功为0, 失败为-1
  @相关参见 bufferevent_write_buffer()

1.12.bufferevent_enable

启用bufferevent相关缓存区
int bufferevent_enable(struct bufferevent *bufev, short event);
备注：新建的bufferevent默认写缓存时enable，而读缓存是disable的

1.13.bufferevent_disable

禁用bufferevent相关缓存区
int bufferevent_disable(struct bufferevent *bufev, short event);
备注：新建的bufferevent默认写缓存时enable，而读缓存是disable的

1.14.bufferevent_socket_connect

函数功能：  使用基于socket的bufferevent进行connect()连接
函数原型：int bufferevent_socket_connect(struct bufferevent *bev, const struct sockaddr *sa, int socklen)
函数描述：
   当连接成功时eventcb会被回调 ，使用BEV_EVENT_CONNECTED 集合.内部使用evutil_socket_connect_
   内部使用连接函数原型为：int evutil_socket_connect_(evutil_socket_t *fd_ptr, const struct sockaddr *sa, int socklen)

   （1）如果bufferevent还没有socket set, 则分配一个socket，并且设置为非阻塞
   实现代码中：
   fd = bufferevent_getfd(bev);
	if (fd < 0) {
    
    
		if (!sa)
			goto done;
		fd = evutil_socket_(sa->sa_family,
		    SOCK_STREAM|EVUTIL_SOCK_NONBLOCK, 0);
		if (fd < 0)
			goto freesock;
		ownfd = 1;
	}
   （2）内部使用evutil_socket_connect_函数进行连接，此函数返回值：
2 ：连接被拒绝（errno值为ECONNREFUSED）
1 ：已经连接上
0 ：尚未连接上（errno值为EINTR或则EINPROGRESS）,
-1 发生错误
    （3） 根据evutil_socket_connect_返回值，进一步判断，
if (r == 0) {
    
    
		if (! be_socket_enable(bev, EV_WRITE)) {
    
    
			bufev_p->connecting = 1;
			result = 0;
			goto done;
		}
	} else if (r == 1) {
    
    
		/* The connect succeeded already. How very BSD of it. */
		result = 0;
		bufev_p->connecting = 1;
		bufferevent_trigger_nolock_(bev, EV_WRITE, BEV_OPT_DEFER_CALLBACKS);
	} else {
    
    
		/* The connect failed already.  How very BSD of it. */
		result = 0;
		bufferevent_run_eventcb_(bev, BEV_EVENT_ERROR, BEV_OPT_DEFER_CALLBACKS);
		bufferevent_disable(bev, EV_WRITE|EV_READ);
	}
     a）若尚未连接上（errno值为EINTR或则EINPROGRESS）,则设置为正在连接标识，并添加一个EV_WRITE事件（超时参数根据bufferevent当前设置的数值），并标记返回值为0（按成功返回），后续若连接上时，会调用事件回调，events值为：BEV_EVENT_CONNECTED，若发生错误，则events值为BEV_EVENT_ERROR
     b）若已经连接上，设置返回成功，同时也是标记正在连接，并直接调用可写回调函数（bufferevent_trigger_nolock_(bev, EV_WRITE, BEV_OPT_DEFER_CALLBACKS);）。调用bufferevent_socket_new方法中添加bufferevent事件内部的ev_write事件对应的回调函数bufferevent_writecb
	在bufferevent_writecb回调中，根据connecting结合查询socket当前的连接状态，若已经连接上，则清除connecting为0，并执行事件回调，events值为：BEV_EVENT_CONNECTED。
        若在bufferevent_writecb回调过程中查询到socket连接状态是出错状态，执行事件回调，events值为：BEV_EVENT_ERROR。 
     c）若连接被拒绝，设置返回成功，并调用错误事件回调函数，同时禁用读写缓存；
     d）若发生错误，设置返回失败；
    
参数说明：
   @param bufev 通过bufferevent_socket_new()创建的bufferevent  
   @param addr  服务器地址
   @param socklen 服务器地址长度
返回：
   @return 0 连接成功, -1 ：失败.

1.15. Internal connection function evutil_socket_connect_

函数原型：
Int evutil_socket_connect_(evutil_socket_t *fd_ptr, const struct sockaddr *sa, int socklen)
函数描述：
实现中真正使用linux系统接口connect，非阻塞模式调用
2 ：连接被拒绝（errno值为ECONNREFUSED）
1 ：已经连接上
0 ：尚未连接上（errno值为EINTR或则EINPROGRESS）,
-1 发生错误
源码参考：
int evutil_socket_connect_(evutil_socket_t *fd_ptr, const struct sockaddr *sa, int socklen)
{
    
    
	int made_fd = 0;

	if (*fd_ptr < 0) {
    
    
		if ((*fd_ptr = socket(sa->sa_family, SOCK_STREAM, 0)) < 0)
			goto err;
		made_fd = 1;
		if (evutil_make_socket_nonblocking(*fd_ptr) < 0) {
    
    
			goto err;
		}
	}

	if (connect(*fd_ptr, sa, socklen) < 0) {
    
    
		int e = evutil_socket_geterror(*fd_ptr);
		if (EVUTIL_ERR_CONNECT_RETRIABLE(e))
			return 0;
		if (EVUTIL_ERR_CONNECT_REFUSED(e))
			return 2;
		goto err;
	} else {
    
    
		return 1;
	}

err:
	if (made_fd) {
    
    
		evutil_closesocket(*fd_ptr);
		*fd_ptr = -1;
	}
	return -1;
}

1.16. Get socket status evutil_socket_finished_connecting_

获取套接字的状态，
1：已经连接；
0：尚未连接；
-1：发生错误
源码参考：
int
evutil_socket_finished_connecting_(evutil_socket_t fd)
{
    
    
	int e;
	ev_socklen_t elen = sizeof(e);

	if (getsockopt(fd, SOL_SOCKET, SO_ERROR, (void*)&e, &elen) < 0)
		return -1;

	if (e) {
    
    
		if (EVUTIL_ERR_CONNECT_RETRIABLE(e))
			return 0;
		EVUTIL_SET_SOCKET_ERROR(e);
		return -1;
	}

	return 1;
}

1.17.event_base_dispatch

函数功能：事件调度循环
函数原型：
EVENT2_EXPORT_SYMBOL
int event_base_dispatch(struct event_base *);
函数描述：
  This loop will run the event base until either there are no more pending or
  active, or until something calls event_base_loopbreak() or
  event_base_loopexit().
参数说明：
  @param base  event_base_new() or event_base_new_with_config()创建的框架上下文对象
返回值：
  @return 0：成功,   -1 ：发生错误，1 已退出循环，没有待监测或则激活的事件
   相关函数参见event_base_loop()

1.18.event_base_loop

函数功能：等待事件激活，并运行回调 
函数原型：
EVENT2_EXPORT_SYMBOL
int event_base_loop(struct event_base *, int);
函数描述：
  这是event_base_dispatch()的较复杂版本.
  默认地，此循环会运行，直到没有待监测事件或则激活事件, 或则调用了calls event_base_loopbreak()，或则调用了
  event_base_loopexit().  可以使用flags参数覆盖行为。

参数说明：
  @param base  event_base_new() or event_base_new_with_config()创建的框架上下文对象
  @param flags EVLOOP_ONCE 和 EVLOOP_NONBLOCK任意组合
返回值：
  @return 0：成功,   -1 ：发生错误，1 已退出循环，没有待监测或则激活的事件
  相关参见event_base_loopexit(), event_base_dispatch(), EVLOOP_ONCE,EVLOOP_NONBLOCK

1.19.event_base_loopexit

函数功能：指定时间后，退出loop循环 
函数原型：
EVENT2_EXPORT_SYMBOL
int event_base_loopexit(struct event_base *, const struct timeval *);
函数描述： 
   event_base_loop()后调用会正常处理.
参数说明：
  @param base  event_base_new() or event_base_new_with_config()创建的框架上下文对象
  @param tv loop结束前地时间,若指定为NULL，则运行完当前已激活地事件立马结束 
返回值：
  @return 0：成功,   -1 ：发生错误
  @相关参见event_base_loopbreak()