eloop.h File Reference

Event loop. More...

Go to the source code of this file.

Macros
#define	ELOOP_ALL_CTX   (void *) -1
	eloop_cancel_timeout() magic number to match all timeouts

Typedefs
typedef void(*	eloop_sock_handler )(int sock, void *eloop_ctx, void *sock_ctx)
	eloop socket event callback type More...
typedef void(*	eloop_event_handler )(void *eloop_data, void *user_ctx)
	eloop generic event callback type More...
typedef void(*	eloop_timeout_handler )(void *eloop_data, void *user_ctx)
	eloop timeout event callback type More...
typedef void(*	eloop_signal_handler )(int sig, void *signal_ctx)
	eloop signal event callback type More...

Enumerations
enum	eloop_event_type { EVENT_TYPE_READ = 0, EVENT_TYPE_WRITE, EVENT_TYPE_EXCEPTION }
	eloop socket event type for eloop_register_sock() More...

Functions
int	eloop_init (void)
	Initialize global event loop data. More...
int	eloop_register_read_sock (int sock, eloop_sock_handler handler, void *eloop_data, void *user_data)
	Register handler for read events. More...
void	eloop_unregister_read_sock (int sock)
	Unregister handler for read events. More...
int	eloop_register_sock (int sock, eloop_event_type type, eloop_sock_handler handler, void *eloop_data, void *user_data)
	Register handler for socket events. More...
void	eloop_unregister_sock (int sock, eloop_event_type type)
	Unregister handler for socket events. More...
int	eloop_register_event (void *event, size_t event_size, eloop_event_handler handler, void *eloop_data, void *user_data)
	Register handler for generic events. More...
void	eloop_unregister_event (void *event, size_t event_size)
	Unregister handler for a generic event. More...
int	eloop_register_timeout (unsigned int secs, unsigned int usecs, eloop_timeout_handler handler, void *eloop_data, void *user_data)
	Register timeout. More...
int	eloop_cancel_timeout (eloop_timeout_handler handler, void *eloop_data, void *user_data)
	Cancel timeouts. More...
int	eloop_cancel_timeout_one (eloop_timeout_handler handler, void *eloop_data, void *user_data, struct os_reltime *remaining)
	Cancel a single timeout. More...
int	eloop_is_timeout_registered (eloop_timeout_handler handler, void *eloop_data, void *user_data)
	Check if a timeout is already registered. More...
int	eloop_deplete_timeout (unsigned int req_secs, unsigned int req_usecs, eloop_timeout_handler handler, void *eloop_data, void *user_data)
	Deplete a timeout that is already registered. More...
int	eloop_replenish_timeout (unsigned int req_secs, unsigned int req_usecs, eloop_timeout_handler handler, void *eloop_data, void *user_data)
	Replenish a timeout that is already registered. More...
int	eloop_register_signal (int sig, eloop_signal_handler handler, void *user_data)
	Register handler for signals. More...
int	eloop_register_signal_terminate (eloop_signal_handler handler, void *user_data)
	Register handler for terminate signals. More...
int	eloop_register_signal_reconfig (eloop_signal_handler handler, void *user_data)
	Register handler for reconfig signals. More...
void	eloop_run (void)
	Start the event loop. More...
void	eloop_terminate (void)
	Terminate event loop. More...
void	eloop_destroy (void)
	Free any resources allocated for the event loop. More...
int	eloop_terminated (void)
	Check whether event loop has been terminated. More...
void	eloop_wait_for_read_sock (int sock)
	Wait for a single reader. More...

Detailed Description

Event loop.

This file defines an event loop interface that supports processing events from registered timeouts (i.e., do something after N seconds), sockets (e.g., a new packet available for reading), and signals. eloop.c is an implementation of this interface using select() and sockets. This is suitable for most UNIX/POSIX systems. When porting to other operating systems, it may be necessary to replace that implementation with OS specific mechanisms.

Typedef Documentation

typedef void(* eloop_event_handler)(void *eloop_data, void *user_ctx)

eloop generic event callback type

Parameters

eloop_ctx	Registered callback context data (eloop_data)
sock_ctx	Registered callback context data (user_data)

typedef void(* eloop_signal_handler)(int sig, void *signal_ctx)

eloop signal event callback type

Parameters

sig	Signal number
signal_ctx	Registered callback context data (user_data from eloop_register_signal(), eloop_register_signal_terminate(), or eloop_register_signal_reconfig() call)

typedef void(* eloop_sock_handler)(int sock, void *eloop_ctx, void *sock_ctx)

eloop socket event callback type

Parameters

sock	File descriptor number for the socket
eloop_ctx	Registered callback context data (eloop_data)
sock_ctx	Registered callback context data (user_data)

typedef void(* eloop_timeout_handler)(void *eloop_data, void *user_ctx)

eloop timeout event callback type

Parameters

eloop_ctx	Registered callback context data (eloop_data)
sock_ctx	Registered callback context data (user_data)

Enumeration Type Documentation

enum eloop_event_type

eloop socket event type for eloop_register_sock()

Parameters

EVENT_TYPE_READ	Socket has data available for reading
EVENT_TYPE_WRITE	Socket has room for new data to be written
EVENT_TYPE_EXCEPTION	An exception has been reported

Function Documentation

int eloop_cancel_timeout	(	eloop_timeout_handler	handler,
		void *	eloop_data,
		void *	user_data
	)

Cancel timeouts.

Parameters

handler	Matching callback function
eloop_data	Matching eloop_data or ELOOP_ALL_CTX to match all
user_data	Matching user_data or ELOOP_ALL_CTX to match all

Returns

Number of cancelled timeouts

Cancel matching <handler,eloop_data,user_data> timeouts registered with eloop_register_timeout(). ELOOP_ALL_CTX can be used as a wildcard for cancelling all timeouts regardless of eloop_data/user_data.

int eloop_cancel_timeout_one	(	eloop_timeout_handler	handler,
		void *	eloop_data,
		void *	user_data,
		struct os_reltime *	remaining
	)

Cancel a single timeout.

Parameters

handler	Matching callback function
eloop_data	Matching eloop_data
user_data	Matching user_data
remaining	Time left on the cancelled timer

Returns

Number of cancelled timeouts

Cancel matching <handler,eloop_data,user_data> timeout registered with eloop_register_timeout() and return the remaining time left.

int eloop_deplete_timeout	(	unsigned int	req_secs,
		unsigned int	req_usecs,
		eloop_timeout_handler	handler,
		void *	eloop_data,
		void *	user_data
	)

Deplete a timeout that is already registered.

Parameters

req_secs	Requested number of seconds to the timeout
req_usecs	Requested number of microseconds to the timeout
handler	Matching callback function
eloop_data	Matching eloop_data
user_data	Matching user_data

Returns

1 if the timeout is depleted, 0 if no change is made, -1 if no timeout matched

Find a registered matching <handler,eloop_data,user_data> timeout. If found, deplete the timeout if remaining time is more than the requested time.

void eloop_destroy

(

void

)

Free any resources allocated for the event loop.

After calling eloop_destroy(), other eloop_* functions must not be called before re-running eloop_init().

int eloop_init

(

void

)

Initialize global event loop data.

Returns

0 on success, -1 on failure

This function must be called before any other eloop_* function.

int eloop_is_timeout_registered	(	eloop_timeout_handler	handler,
		void *	eloop_data,
		void *	user_data
	)

Check if a timeout is already registered.

Parameters

handler	Matching callback function
eloop_data	Matching eloop_data
user_data	Matching user_data

Returns

1 if the timeout is registered, 0 if the timeout is not registered

Determine if a matching <handler,eloop_data,user_data> timeout is registered with eloop_register_timeout().

int eloop_register_event	(	void *	event,
		size_t	event_size,
		eloop_event_handler	handler,
		void *	eloop_data,
		void *	user_data
	)

Register handler for generic events.

Parameters

event	Event to wait (eloop implementation specific)
event_size	Size of event data
handler	Callback function to be called when event is triggered
eloop_data	Callback context data (eloop_data)
user_data	Callback context data (user_data)

Returns

0 on success, -1 on failure

Register an event handler for the given event. This function is used to register eloop implementation specific events which are mainly targeted for operating system specific code (driver interface and l2_packet) since the portable code will not be able to use such an OS-specific call. The handler function will be called whenever the event is triggered. The handler function is responsible for clearing the event after having processed it in order to avoid eloop from calling the handler again for the same event.

In case of Windows implementation (eloop_win.c), event pointer is of HANDLE type, i.e., void*. The callers are likely to have 'HANDLE h' type variable, and they would call this function with eloop_register_event(h, sizeof(h), ...).

int eloop_register_read_sock	(	int	sock,
		eloop_sock_handler	handler,
		void *	eloop_data,
		void *	user_data
	)

Register handler for read events.

Parameters

sock	File descriptor number for the socket
handler	Callback function to be called when data is available for reading
eloop_data	Callback context data (eloop_ctx)
user_data	Callback context data (sock_ctx)

Returns

0 on success, -1 on failure

Register a read socket notifier for the given file descriptor. The handler function will be called whenever data is available for reading from the socket. The handler function is responsible for clearing the event after having processed it in order to avoid eloop from calling the handler again for the same event.

int eloop_register_signal	(	int	sig,
		eloop_signal_handler	handler,
		void *	user_data
	)

Register handler for signals.

Parameters

sig	Signal number (e.g., SIGHUP)
handler	Callback function to be called when the signal is received
user_data	Callback context data (signal_ctx)

Returns

0 on success, -1 on failure

Register a callback function that will be called when a signal is received. The callback function is actually called only after the system signal handler has returned. This means that the normal limits for sighandlers (i.e., only "safe functions" allowed) do not apply for the registered callback.

int eloop_register_signal_reconfig	(	eloop_signal_handler	handler,
		void *	user_data
	)

Register handler for reconfig signals.

Parameters

handler	Callback function to be called when the signal is received
user_data	Callback context data (signal_ctx)

Returns

0 on success, -1 on failure

Register a callback function that will be called when a reconfiguration / hangup signal is received. The callback function is actually called only after the system signal handler has returned. This means that the normal limits for sighandlers (i.e., only "safe functions" allowed) do not apply for the registered callback.

This function is a more portable version of eloop_register_signal() since the knowledge of exact details of the signals is hidden in eloop implementation. In case of operating systems using signal(), this function registers a handler for SIGHUP.

int eloop_register_signal_terminate	(	eloop_signal_handler	handler,
		void *	user_data
	)

Register handler for terminate signals.

Parameters

handler	Callback function to be called when the signal is received
user_data	Callback context data (signal_ctx)

Returns

0 on success, -1 on failure

Register a callback function that will be called when a process termination signal is received. The callback function is actually called only after the system signal handler has returned. This means that the normal limits for sighandlers (i.e., only "safe functions" allowed) do not apply for the registered callback.

This function is a more portable version of eloop_register_signal() since the knowledge of exact details of the signals is hidden in eloop implementation. In case of operating systems using signal(), this function registers handlers for SIGINT and SIGTERM.

int eloop_register_sock	(	int	sock,
		eloop_event_type	type,
		eloop_sock_handler	handler,
		void *	eloop_data,
		void *	user_data
	)

Register handler for socket events.

Parameters

sock	File descriptor number for the socket
type	Type of event to wait for
handler	Callback function to be called when the event is triggered
eloop_data	Callback context data (eloop_ctx)
user_data	Callback context data (sock_ctx)

Returns

0 on success, -1 on failure

Register an event notifier for the given socket's file descriptor. The handler function will be called whenever the that event is triggered for the socket. The handler function is responsible for clearing the event after having processed it in order to avoid eloop from calling the handler again for the same event.

int eloop_register_timeout	(	unsigned int	secs,
		unsigned int	usecs,
		eloop_timeout_handler	handler,
		void *	eloop_data,
		void *	user_data
	)

Register timeout.

Parameters

secs	Number of seconds to the timeout
usecs	Number of microseconds to the timeout
handler	Callback function to be called when timeout occurs
eloop_data	Callback context data (eloop_ctx)
user_data	Callback context data (sock_ctx)

Returns

0 on success, -1 on failure

Register a timeout that will cause the handler function to be called after given time.

int eloop_replenish_timeout	(	unsigned int	req_secs,
		unsigned int	req_usecs,
		eloop_timeout_handler	handler,
		void *	eloop_data,
		void *	user_data
	)

Replenish a timeout that is already registered.

Parameters

req_secs	Requested number of seconds to the timeout
req_usecs	Requested number of microseconds to the timeout
handler	Matching callback function
eloop_data	Matching eloop_data
user_data	Matching user_data

Returns

1 if the timeout is replenished, 0 if no change is made, -1 if no timeout matched

Find a registered matching <handler,eloop_data,user_data> timeout. If found, replenish the timeout if remaining time is less than the requested time.

void eloop_run

(

void

)

Start the event loop.

Start the event loop and continue running as long as there are any registered event handlers. This function is run after event loop has been initialized with event_init() and one or more events have been registered.

void eloop_terminate

(

void

)

Terminate event loop.

Terminate event loop even if there are registered events. This can be used to request the program to be terminated cleanly.

int eloop_terminated

(

void

)

Check whether event loop has been terminated.

Returns

1 = event loop terminate, 0 = event loop still running

This function can be used to check whether eloop_terminate() has been called to request termination of the event loop. This is normally used to abort operations that may still be queued to be run when eloop_terminate() was called.

void eloop_unregister_event	(	void *	event,
		size_t	event_size
	)

Unregister handler for a generic event.

Parameters

event	Event to cancel (eloop implementation specific)
event_size	Size of event data

Unregister a generic event notifier that was previously registered with eloop_register_event().

void eloop_unregister_read_sock

(

int

sock

)

Unregister handler for read events.

Parameters

sock	File descriptor number for the socket

Unregister a read socket notifier that was previously registered with eloop_register_read_sock().

void eloop_unregister_sock	(	int	sock,
		eloop_event_type	type
	)

Unregister handler for socket events.

Parameters

sock	File descriptor number for the socket
type	Type of event for which sock was registered

Unregister a socket event notifier that was previously registered with eloop_register_sock().

void eloop_wait_for_read_sock

(

int

sock

)

Wait for a single reader.

Parameters

sock	File descriptor number for the socket

Do a blocking wait for a single read socket.