listener.h File Reference

A callback that we invoke when a listener has a new connection. More...

#include <event2/visibility.h>
#include <event2/event.h>

Go to the source code of this file.

Macros
#define	LEV_OPT_BIND_IPV4_AND_IPV6   (1u<<9)
	Flag: Indicates that the listener wants to work only in both IPv4 and IPv6 socket. More...
#define	LEV_OPT_BIND_IPV6ONLY   (1u<<8)
	Flag: Indicates that the listener wants to work only in IPv6 socket. More...
#define	LEV_OPT_CLOSE_ON_EXEC   (1u<<2)
	Flag: Indicates that we should set the close-on-exec flag, if possible.
#define	LEV_OPT_CLOSE_ON_FREE   (1u<<1)
	Flag: Indicates that freeing the listener should close the underlying socket.
#define	LEV_OPT_DEFERRED_ACCEPT   (1u<<6)
	Flag: Indicates that the listener should defer accept() until data is available, if possible. More...
#define	LEV_OPT_DISABLED   (1u<<5)
	Flag: Indicates that the listener should be created in disabled state. More...
#define	LEV_OPT_LEAVE_SOCKETS_BLOCKING   (1u<<0)
	Flag: Indicates that we should not make incoming sockets nonblocking before passing them to the callback.
#define	LEV_OPT_REUSEABLE   (1u<<3)
	Flag: Indicates that we should disable the timeout (if any) between when this socket is closed and when we can listen again on the same port.
#define	LEV_OPT_REUSEABLE_PORT   (1u<<7)
	Flag: Indicates that we ask to allow multiple servers (processes or threads) to bind to the same port if they each set the option for incoming connections/datagrams to be distributed evenly across all of the threads (or processes). More...
#define	LEV_OPT_THREADSAFE   (1u<<4)
	Flag: Indicates that the listener should be locked so it's safe to use from multiple threadcs at once.

Typedefs
typedef void(*	evconnlistener_cb) (struct evconnlistener *, evutil_socket_t, struct sockaddr *, int socklen, void *)
typedef void(*	evconnlistener_errorcb) (struct evconnlistener *, void *)
	A callback that we invoke when a listener encounters a non-retriable error. More...

Functions
EVENT2_EXPORT_SYMBOL int	evconnlistener_disable (struct evconnlistener *lev)
	Stop listening for connections on an evconnlistener.
EVENT2_EXPORT_SYMBOL int	evconnlistener_enable (struct evconnlistener *lev)
	Re-enable an evconnlistener that has been disabled.
EVENT2_EXPORT_SYMBOL void	evconnlistener_free (struct evconnlistener *lev)
	Disable and deallocate an evconnlistener.
EVENT2_EXPORT_SYMBOL struct event_base *	evconnlistener_get_base (struct evconnlistener *lev)
	Return an evconnlistener's associated event_base.
EVENT2_EXPORT_SYMBOL evutil_socket_t	evconnlistener_get_fd (struct evconnlistener *lev)
	Return the socket that an evconnlistner is listening on.
EVENT2_EXPORT_SYMBOL struct evconnlistener *	evconnlistener_new (struct event_base *base, evconnlistener_cb cb, void *ptr, unsigned flags, int backlog, evutil_socket_t fd)
	Allocate a new evconnlistener object to listen for incoming TCP connections on a given file descriptor. More...
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)
	Allocate a new evconnlistener object to listen for incoming TCP connections on a given address. More...
EVENT2_EXPORT_SYMBOL void	evconnlistener_set_cb (struct evconnlistener *lev, evconnlistener_cb cb, void *arg)
	Change the callback on the listener to cb and its user_data to arg.
EVENT2_EXPORT_SYMBOL void	evconnlistener_set_error_cb (struct evconnlistener *lev, evconnlistener_errorcb errorcb)
	Set an evconnlistener's error callback.

Detailed Description

A callback that we invoke when a listener has a new connection.

Parameters

listener	The evconnlistener
fd	The new file descriptor
addr	The source address of the connection
socklen	The length of addr
user_arg	the pointer passed to evconnlistener_new()

Macro Definition Documentation

LEV_OPT_BIND_IPV4_AND_IPV6

#define LEV_OPT_BIND_IPV4_AND_IPV6   (1u<<9)

Flag: Indicates that the listener wants to work only in both IPv4 and IPv6 socket.

This flag exists as complement to LEV_OPT_BIND_IPV6ONLY to account for the different default behaviour on Windows so that the code can explicitly request the socket to support both modes without having to rely on the default option.

LEV_OPT_BIND_IPV6ONLY

#define LEV_OPT_BIND_IPV6ONLY   (1u<<8)

Flag: Indicates that the listener wants to work only in IPv6 socket.

According to RFC3493 and most Linux distributions, default value is to work in IPv4-mapped mode. If there is a requirement to bind same port on same ip addresses but different handlers for both IPv4 and IPv6, it is required to set IPV6_V6ONLY socket option to be sure that the code works as expected without affected by bindv6only sysctl setting in system.

This socket option on Windows is instead enabled by default.

LEV_OPT_DEFERRED_ACCEPT

#define LEV_OPT_DEFERRED_ACCEPT   (1u<<6)

Flag: Indicates that the listener should defer accept() until data is available, if possible.

Ignored on platforms that do not support this.

This option can help performance for protocols where the client transmits immediately after connecting. Do not use this option if your protocol doesn't start out with the client transmitting data, since in that case this option will sometimes cause the kernel to never tell you about the connection.

This option is only supported by evconnlistener_new_bind(): it can't work with evconnlistener_new_fd(), since the listener needs to be told to use the option before it is actually bound.

LEV_OPT_DISABLED

#define LEV_OPT_DISABLED   (1u<<5)

Flag: Indicates that the listener should be created in disabled state.

Use evconnlistener_enable() to enable it later.

LEV_OPT_REUSEABLE_PORT

#define LEV_OPT_REUSEABLE_PORT   (1u<<7)

Flag: Indicates that we ask to allow multiple servers (processes or threads) to bind to the same port if they each set the option for incoming connections/datagrams to be distributed evenly across all of the threads (or processes).

SO_REUSEPORT is what most people would expect SO_REUSEADDR to be, however SO_REUSEPORT does not imply SO_REUSEADDR.

This feature is available only on Linux 3.9+, DragonFlyBSD 3.6+, FreeBSD 12.0+, Solaris 11.4, AIX 7.2.5 for now.

Typedef Documentation

evconnlistener_errorcb

typedef void(* evconnlistener_errorcb) (struct evconnlistener *, void *)

A callback that we invoke when a listener encounters a non-retriable error.

Parameters

listener	The evconnlistener
user_arg	the pointer passed to evconnlistener_new()

Function Documentation

evconnlistener_new()

EVENT2_EXPORT_SYMBOL struct evconnlistener* evconnlistener_new	(	struct event_base *	base,
		evconnlistener_cb	cb,
		void *	ptr,
		unsigned	flags,
		int	backlog,
		evutil_socket_t	fd
	)

Allocate a new evconnlistener object to listen for incoming TCP connections on a given file descriptor.

Parameters

base	The event base to associate the listener with.
cb	A callback to be invoked when a new connection arrives. If the callback is NULL, the listener will be treated as disabled until the callback is set.
ptr	A user-supplied pointer to give to the callback.
flags	Any number of LEV_OPT_* flags
backlog	Passed to the listen() call to determine the length of the acceptable connection backlog. Set to -1 for a reasonable default. Set to 0 if the socket is already listening.
fd	The file descriptor to listen on. It must be a nonblocking file descriptor, and it should already be bound to an appropriate port and address.

evconnlistener_new_bind()

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
	)

Allocate a new evconnlistener object to listen for incoming TCP connections on a given address.

Parameters

base	The event base to associate the listener with.
cb	A callback to be invoked when a new connection arrives. If the callback is NULL, the listener will be treated as disabled until the callback is set.
ptr	A user-supplied pointer to give to the callback.
flags	Any number of LEV_OPT_* flags
backlog	Passed to the listen() call to determine the length of the acceptable connection backlog. Set to -1 for a reasonable default.
sa	The address to listen for connections on.
socklen	The length of the address.