译自http://www.wangafu.net/~nickm/libevent-book/Ref8_listener.html
evconnlistener机制提供了监听和接受TCP连接的方法。
本章的所有函数和类型都在event2/listener.h中声明,除非特别说明,它们都在2.0.2-alpha版本中首次出现。
1 创建和释放evconnlistener
接口
struct
evconnlistener
*
evconnlistener_new(struct
event_base
*base
,
evconnlistener_cb cb, void
*
ptr, unsigned flags, int
backlog,
evutil_socket_t fd);
struct
evconnlistener
*
evconnlistener_new_bind(struct
event_base
*base
,
evconnlistener_cb cb, void
*
ptr, unsigned flags, int
backlog,
const
struct
sockaddr
*
sa, int
socklen);
void
evconnlistener_free(struct
evconnlistener
*
lev);
两个evconnlistener_new*()函数都分配和返回一个新的连接监听器对象。连接监听器使用event_base来得知什么时候在给定的监听套接字上有新的TCP连接。新连接到达时,监听器调用你给出的回调函数。
两个函数中,base参数都是监听器用于监听连接的event_base。cb是收到新连接时要调用的回调函数;如果cb为NULL,则监听器是禁用的,直到设置了回调函数为止。ptr指针将传递给回调函数。flags参数控制回调函数的行为,下面会更详细论述。backlog是任何时刻网络栈允许处于还未接受状态的最大未决连接数。更多细节请查看系统的listen()函数文档。如果backlog是负的,libevent会试图挑选一个较好的值;如果为0,libevent认为已经对提供的套接字调用了listen()。
两个函数的不同在于如何建立监听套接字。evconnlistener_new()函数假定已经将套接字绑定到要监听的端口,然后通过fd传入这个套接字。如果要libevent分配和绑定套接字,可以调用evconnlistener_new_bind(),传输要绑定到的地址和地址长度。
要释放连接监听器,调用evconnlistener_free()。
evconnlistener_cb cb, void * ptr, unsigned flags, int backlog,
evutil_socket_t fd);
struct evconnlistener * evconnlistener_new_bind(struct event_base *base ,
evconnlistener_cb cb, void * ptr, unsigned flags, int backlog,
const struct sockaddr * sa, int socklen);
void evconnlistener_free(struct evconnlistener * lev);
两个evconnlistener_new*()函数都分配和返回一个新的连接监听器对象。连接监听器使用event_base来得知什么时候在给定的监听套接字上有新的TCP连接。新连接到达时,监听器调用你给出的回调函数。
两个函数中,base参数都是监听器用于监听连接的event_base。cb是收到新连接时要调用的回调函数;如果cb为NULL,则监听器是禁用的,直到设置了回调函数为止。ptr指针将传递给回调函数。flags参数控制回调函数的行为,下面会更详细论述。backlog是任何时刻网络栈允许处于还未接受状态的最大未决连接数。更多细节请查看系统的listen()函数文档。如果backlog是负的,libevent会试图挑选一个较好的值;如果为0,libevent认为已经对提供的套接字调用了listen()。
两个函数的不同在于如何建立监听套接字。evconnlistener_new()函数假定已经将套接字绑定到要监听的端口,然后通过fd传入这个套接字。如果要libevent分配和绑定套接字,可以调用evconnlistener_new_bind(),传输要绑定到的地址和地址长度。
要释放连接监听器,调用evconnlistener_free()。
可识别的标志
可以给evconnlistener_new()函数的flags参数传入一些标志。可以用或(OR)运算任意连接下述标志:
l LEV_OPT_LEAVE_SOCKETS_BLOCKING
默认情况下,连接监听器接收新套接字后,会将其设置为非阻塞的,以便将其用于libevent。如果不想要这种行为,可以设置这个标志。
l LEV_OPT_CLOSE_ON_FREE
如果设置了这个选项,释放连接监听器会关闭底层套接字。
l LEV_OPT_CLOSE_ON_EXEC
如果设置了这个选项,连接监听器会为底层套接字设置close-on-exec标志。更多信息请查看fcntl和FD_CLOEXEC的平台文档。
l LEV_OPT_REUSEABLE
某些平台在默认情况下,关闭某监听套接字后,要过一会儿其他套接字才可以绑定到同一个端口。设置这个标志会让libevent标记套接字是可重用的,这样一旦关闭,可以立即打开其他套接字,在相同端口进行监听。
l LEV_OPT_THREADSAFE
为监听器分配锁,这样就可以在多个线程中安全地使用了。这是2.0.8-rc的新功能。
可以给evconnlistener_new()函数的flags参数传入一些标志。可以用或(OR)运算任意连接下述标志:
l
默认情况下,连接监听器接收新套接字后,会将其设置为非阻塞的,以便将其用于libevent。如果不想要这种行为,可以设置这个标志。
l
如果设置了这个选项,释放连接监听器会关闭底层套接字。
l
如果设置了这个选项,连接监听器会为底层套接字设置close-on-exec标志。更多信息请查看fcntl和FD_CLOEXEC的平台文档。
l
某些平台在默认情况下,关闭某监听套接字后,要过一会儿其他套接字才可以绑定到同一个端口。设置这个标志会让libevent标记套接字是可重用的,这样一旦关闭,可以立即打开其他套接字,在相同端口进行监听。
l
为监听器分配锁,这样就可以在多个线程中安全地使用了。这是2.0.8-rc的新功能。
连接监听器回调
接口
typedef void
(
*
evconnlistener_cb)(struct
evconnlistener
*
listener,
evutil_socket_t sock, struct
sockaddr
*
addr, int
len, void
*
ptr);
接收到新连接会调用提供的回调函数。listener参数是接收连接的连接监听器。sock参数是新接收的套接字。addr和len参数是接收连接的地址和地址长度。ptr是调用evconnlistener_new()时用户提供的指针。
evutil_socket_t sock, struct sockaddr * addr, int len, void * ptr);
接收到新连接会调用提供的回调函数。listener参数是接收连接的连接监听器。sock参数是新接收的套接字。addr和len参数是接收连接的地址和地址长度。ptr是调用evconnlistener_new()时用户提供的指针。
2 启用和禁用evconnlistener
接口
int
evconnlistener_disable(struct
evconnlistener
*
lev);
int
evconnlistener_enable(struct
evconnlistener
*
lev);
这两个函数暂时禁止或者重新允许监听新连接。
int evconnlistener_enable(struct evconnlistener * lev);
这两个函数暂时禁止或者重新允许监听新连接。
3 调整evconnlistener的回调函数
接口
void
evconnlistener_set_cb(struct
evconnlistener
*
lev,
evconnlistener_cb cb, void
*
arg);
函数调整evconnlistener的回调函数和其参数。它是2.0.9-rc版本引入的。
evconnlistener_cb cb, void * arg);
函数调整evconnlistener的回调函数和其参数。它是2.0.9-rc版本引入的。
4 检测evconnlistener
接口
evutil_socket_t evconnlistener_get_fd(struct
evconnlistener
*
lev);
struct
event_base
*
evconnlistener_get_base(struct
evconnlistener
*
lev);
这些函数分别返回监听器关联的套接字和event_base。
evconnlistener_get_fd()函数首次出现在2.0.3-alpha版本。
struct event_base * evconnlistener_get_base(struct evconnlistener * lev);
这些函数分别返回监听器关联的套接字和event_base。
evconnlistener_get_fd()函数首次出现在2.0.3-alpha版本。
5 侦测错误
可以设置一个一旦监听器上的accept()调用失败就被调用的错误回调函数。对于一个不解决就会锁定进程的错误条件,这很重要。
接口
typedef void
(
*
evconnlistener_errorcb)(struct
evconnlistener
*
lis, void
*
ptr);
void
evconnlistener_set_error_cb(struct
evconnlistener
*
lev,
evconnlistener_errorcb errorcb);
如果使用evconnlistener_set_error_cb()为监听器设置了错误回调函数,则监听器发生错误时回调函数就会被调用。第一个参数是监听器,第二个参数是调用evconnlistener_new()时传入的ptr。
这个函数在2.0.8-rc版本引入。
void evconnlistener_set_error_cb(struct evconnlistener * lev,
evconnlistener_errorcb errorcb);
如果使用evconnlistener_set_error_cb()为监听器设置了错误回调函数,则监听器发生错误时回调函数就会被调用。第一个参数是监听器,第二个参数是调用evconnlistener_new()时传入的ptr。
这个函数在2.0.8-rc版本引入。
6 示例代码:回显服务器
示例
#include
<
event2
/
listener.h
>
#include
<
event2
/
bufferevent.h
>
#include
<
event2
/
buffer.h
>
#include
<
arpa
/
inet.h
>
#include
<string
.h
>
#include
<
stdlib.h
>
#include
<
stdio.h
>
#include
<
errno.h
>
static
void
echo_read_cb(struct
bufferevent
*
bev, void
*
ctx)
{
/*
This callback is invoked when there is data to read on bev.
*/
struct
evbuffer
*
input
=
bufferevent_get_input(bev);
struct
evbuffer
*
output
=
bufferevent_get_output(bev);
/*
Copy all the data from the input buffer to the output buffer.
*/
evbuffer_add_buffer(output, input);
}
static
void
echo_event_cb(struct
bufferevent
*
bev, short
events, void
*
ctx)
{
if
(events
&
BEV_EVENT_ERROR)
perror(
"
Error from bufferevent
"
);
if
(events
&
(BEV_EVENT_EOF
|
BEV_EVENT_ERROR)) {
bufferevent_free(bev);
}
}
static
void
accept_conn_cb(struct
evconnlistener
*
listener,
evutil_socket_t fd, struct
sockaddr
*
address, int
socklen,
void
*
ctx)
{
/*
We got a new connection! Set up a bufferevent for it.
*/
struct
event_base
*base
=
evconnlistener_get_base(listener);
struct
bufferevent
*
bev
=
bufferevent_socket_new(
base
, fd, BEV_OPT_CLOSE_ON_FREE);
bufferevent_setcb(bev, echo_read_cb, NULL, echo_event_cb, NULL);
bufferevent_enable(bev, EV_READ
|
EV_WRITE);
}
static
void
accept_error_cb(struct
evconnlistener
*
listener, void
*
ctx)
{
struct
event_base
*base
=
evconnlistener_get_base(listener);
int
err
=
EVUTIL_SOCKET_ERROR();
fprintf(stderr,
"
Got an error %d (%s) on the listener.
"
"
Shutting down.\n
"
, err, evutil_socket_error_to_string(err));
event_base_loopexit(base
, NULL);
}
int
main(int
argc, char
**
argv)
{
struct
event_base
*base
;
struct
evconnlistener
*
listener;
struct
sockaddr_in sin;
int
port
=
9876
;
if
(argc
>
1
) {
port
=
atoi(argv[
1
]);
}
if
(port
<=
0
||
port
>
65535
) {
puts(
"
Invalid port
"
);
return
1
;
}
base
=
event_base_new();
if
(
!base
) {
puts(
"
Couldn't open event base
"
);
return
1
;
}
/*
Clear the sockaddr before using it, in case there are extra
* platform-specific fields that can mess us up.
*/
memset(
&
sin,
0
, sizeof
(sin));
/*
This is an INET address
*/
sin.sin_family
=
AF_INET;
/*
Listen on 0.0.0.0
*/
sin.sin_addr.s_addr
=
htonl(
0
);
/*
Listen on the given port.
*/
sin.sin_port
=
htons(port);
listener
=
evconnlistener_new_bind(base
, accept_conn_cb, NULL,
LEV_OPT_CLOSE_ON_FREE
|
LEV_OPT_REUSEABLE,
-
1
,
(struct
sockaddr
*
)
&
sin, sizeof
(sin));
if
(
!
listener) {
perror(
"
Couldn't create listener
"
);
return
1
;
}
evconnlistener_set_error_cb(listener, accept_error_cb);
event_base_dispatch(base
);
return
0
;
}
#include < event2 / bufferevent.h >
#include < event2 / buffer.h >
#include < arpa / inet.h >
#include <string .h >
#include < stdlib.h >
#include < stdio.h >
#include < errno.h >
static void
echo_read_cb(struct bufferevent * bev, void * ctx)
{
/* This callback is invoked when there is data to read on bev. */
struct evbuffer * input = bufferevent_get_input(bev);
struct evbuffer * output = bufferevent_get_output(bev);
/* Copy all the data from the input buffer to the output buffer. */
evbuffer_add_buffer(output, input);
}
static void
echo_event_cb(struct bufferevent * bev, short events, void * ctx)
{
if (events & BEV_EVENT_ERROR)
perror( " Error from bufferevent " );
if (events & (BEV_EVENT_EOF | BEV_EVENT_ERROR)) {
bufferevent_free(bev);
}
}
static void
accept_conn_cb(struct evconnlistener * listener,
evutil_socket_t fd, struct sockaddr * address, int socklen,
void * ctx)
{
/* We got a new connection! Set up a bufferevent for it. */
struct event_base *base = evconnlistener_get_base(listener);
struct bufferevent * bev = bufferevent_socket_new(
base , fd, BEV_OPT_CLOSE_ON_FREE);
bufferevent_setcb(bev, echo_read_cb, NULL, echo_event_cb, NULL);
bufferevent_enable(bev, EV_READ | EV_WRITE);
}
static void
accept_error_cb(struct evconnlistener * listener, void * ctx)
{
struct event_base *base = evconnlistener_get_base(listener);
int err = EVUTIL_SOCKET_ERROR();
fprintf(stderr, " Got an error %d (%s) on the listener. "
" Shutting down.\n " , err, evutil_socket_error_to_string(err));
event_base_loopexit(base , NULL);
}
int
main(int argc, char ** argv)
{
struct event_base *base ;
struct evconnlistener * listener;
struct sockaddr_in sin;
int port = 9876 ;
if (argc > 1 ) {
port = atoi(argv[ 1 ]);
}
if (port <= 0 || port > 65535 ) {
puts( " Invalid port " );
return 1 ;
}
base = event_base_new();
if ( !base ) {
puts( " Couldn't open event base " );
return 1 ;
}
/* Clear the sockaddr before using it, in case there are extra
* platform-specific fields that can mess us up. */
memset( & sin, 0 , sizeof (sin));
/* This is an INET address */
sin.sin_family = AF_INET;
/* Listen on 0.0.0.0 */
sin.sin_addr.s_addr = htonl( 0 );
/* Listen on the given port. */
sin.sin_port = htons(port);
listener = evconnlistener_new_bind(base , accept_conn_cb, NULL,
LEV_OPT_CLOSE_ON_FREE | LEV_OPT_REUSEABLE, - 1 ,
(struct sockaddr * ) & sin, sizeof (sin));
if ( ! listener) {
perror( " Couldn't create listener " );
return 1 ;
}
evconnlistener_set_error_cb(listener, accept_error_cb);
event_base_dispatch(base );
return 0 ;
}