1189251Ssam/* 2189251Ssam * Event loop 3189251Ssam * Copyright (c) 2002-2006, Jouni Malinen <j@w1.fi> 4189251Ssam * 5252726Srpaulo * This software may be distributed under the terms of the BSD license. 6252726Srpaulo * See README for more details. 7189251Ssam * 8189251Ssam * This file defines an event loop interface that supports processing events 9189251Ssam * from registered timeouts (i.e., do something after N seconds), sockets 10189251Ssam * (e.g., a new packet available for reading), and signals. eloop.c is an 11189251Ssam * implementation of this interface using select() and sockets. This is 12189251Ssam * suitable for most UNIX/POSIX systems. When porting to other operating 13189251Ssam * systems, it may be necessary to replace that implementation with OS specific 14189251Ssam * mechanisms. 15189251Ssam */ 16189251Ssam 17189251Ssam#ifndef ELOOP_H 18189251Ssam#define ELOOP_H 19189251Ssam 20189251Ssam/** 21189251Ssam * ELOOP_ALL_CTX - eloop_cancel_timeout() magic number to match all timeouts 22189251Ssam */ 23189251Ssam#define ELOOP_ALL_CTX (void *) -1 24189251Ssam 25189251Ssam/** 26189251Ssam * eloop_event_type - eloop socket event type for eloop_register_sock() 27189251Ssam * @EVENT_TYPE_READ: Socket has data available for reading 28189251Ssam * @EVENT_TYPE_WRITE: Socket has room for new data to be written 29189251Ssam * @EVENT_TYPE_EXCEPTION: An exception has been reported 30189251Ssam */ 31189251Ssamtypedef enum { 32189251Ssam EVENT_TYPE_READ = 0, 33189251Ssam EVENT_TYPE_WRITE, 34189251Ssam EVENT_TYPE_EXCEPTION 35189251Ssam} eloop_event_type; 36189251Ssam 37189251Ssam/** 38189251Ssam * eloop_sock_handler - eloop socket event callback type 39189251Ssam * @sock: File descriptor number for the socket 40189251Ssam * @eloop_ctx: Registered callback context data (eloop_data) 41189251Ssam * @sock_ctx: Registered callback context data (user_data) 42189251Ssam */ 43189251Ssamtypedef void (*eloop_sock_handler)(int sock, void *eloop_ctx, void *sock_ctx); 44189251Ssam 45189251Ssam/** 46189251Ssam * eloop_event_handler - eloop generic event callback type 47189251Ssam * @eloop_ctx: Registered callback context data (eloop_data) 48346981Scy * @user_ctx: Registered callback context data (user_data) 49189251Ssam */ 50346981Scytypedef void (*eloop_event_handler)(void *eloop_ctx, void *user_ctx); 51189251Ssam 52189251Ssam/** 53189251Ssam * eloop_timeout_handler - eloop timeout event callback type 54189251Ssam * @eloop_ctx: Registered callback context data (eloop_data) 55346981Scy * @user_ctx: Registered callback context data (user_data) 56189251Ssam */ 57346981Scytypedef void (*eloop_timeout_handler)(void *eloop_ctx, void *user_ctx); 58189251Ssam 59189251Ssam/** 60189251Ssam * eloop_signal_handler - eloop signal event callback type 61189251Ssam * @sig: Signal number 62189251Ssam * @signal_ctx: Registered callback context data (user_data from 63189251Ssam * eloop_register_signal(), eloop_register_signal_terminate(), or 64189251Ssam * eloop_register_signal_reconfig() call) 65189251Ssam */ 66214734Srpaulotypedef void (*eloop_signal_handler)(int sig, void *signal_ctx); 67189251Ssam 68189251Ssam/** 69189251Ssam * eloop_init() - Initialize global event loop data 70189251Ssam * Returns: 0 on success, -1 on failure 71189251Ssam * 72214734Srpaulo * This function must be called before any other eloop_* function. 73189251Ssam */ 74214734Srpauloint eloop_init(void); 75189251Ssam 76189251Ssam/** 77189251Ssam * eloop_register_read_sock - Register handler for read events 78189251Ssam * @sock: File descriptor number for the socket 79189251Ssam * @handler: Callback function to be called when data is available for reading 80189251Ssam * @eloop_data: Callback context data (eloop_ctx) 81189251Ssam * @user_data: Callback context data (sock_ctx) 82189251Ssam * Returns: 0 on success, -1 on failure 83189251Ssam * 84189251Ssam * Register a read socket notifier for the given file descriptor. The handler 85189251Ssam * function will be called whenever data is available for reading from the 86189251Ssam * socket. The handler function is responsible for clearing the event after 87189251Ssam * having processed it in order to avoid eloop from calling the handler again 88189251Ssam * for the same event. 89189251Ssam */ 90189251Ssamint eloop_register_read_sock(int sock, eloop_sock_handler handler, 91189251Ssam void *eloop_data, void *user_data); 92189251Ssam 93189251Ssam/** 94189251Ssam * eloop_unregister_read_sock - Unregister handler for read events 95189251Ssam * @sock: File descriptor number for the socket 96189251Ssam * 97189251Ssam * Unregister a read socket notifier that was previously registered with 98189251Ssam * eloop_register_read_sock(). 99189251Ssam */ 100189251Ssamvoid eloop_unregister_read_sock(int sock); 101189251Ssam 102189251Ssam/** 103189251Ssam * eloop_register_sock - Register handler for socket events 104189251Ssam * @sock: File descriptor number for the socket 105189251Ssam * @type: Type of event to wait for 106189251Ssam * @handler: Callback function to be called when the event is triggered 107189251Ssam * @eloop_data: Callback context data (eloop_ctx) 108189251Ssam * @user_data: Callback context data (sock_ctx) 109189251Ssam * Returns: 0 on success, -1 on failure 110189251Ssam * 111189251Ssam * Register an event notifier for the given socket's file descriptor. The 112189251Ssam * handler function will be called whenever the that event is triggered for the 113189251Ssam * socket. The handler function is responsible for clearing the event after 114189251Ssam * having processed it in order to avoid eloop from calling the handler again 115189251Ssam * for the same event. 116189251Ssam */ 117189251Ssamint eloop_register_sock(int sock, eloop_event_type type, 118189251Ssam eloop_sock_handler handler, 119189251Ssam void *eloop_data, void *user_data); 120189251Ssam 121189251Ssam/** 122189251Ssam * eloop_unregister_sock - Unregister handler for socket events 123189251Ssam * @sock: File descriptor number for the socket 124189251Ssam * @type: Type of event for which sock was registered 125189251Ssam * 126189251Ssam * Unregister a socket event notifier that was previously registered with 127189251Ssam * eloop_register_sock(). 128189251Ssam */ 129189251Ssamvoid eloop_unregister_sock(int sock, eloop_event_type type); 130189251Ssam 131189251Ssam/** 132189251Ssam * eloop_register_event - Register handler for generic events 133189251Ssam * @event: Event to wait (eloop implementation specific) 134189251Ssam * @event_size: Size of event data 135189251Ssam * @handler: Callback function to be called when event is triggered 136189251Ssam * @eloop_data: Callback context data (eloop_data) 137189251Ssam * @user_data: Callback context data (user_data) 138189251Ssam * Returns: 0 on success, -1 on failure 139189251Ssam * 140189251Ssam * Register an event handler for the given event. This function is used to 141252726Srpaulo * register eloop implementation specific events which are mainly targeted for 142189251Ssam * operating system specific code (driver interface and l2_packet) since the 143189251Ssam * portable code will not be able to use such an OS-specific call. The handler 144189251Ssam * function will be called whenever the event is triggered. The handler 145189251Ssam * function is responsible for clearing the event after having processed it in 146189251Ssam * order to avoid eloop from calling the handler again for the same event. 147189251Ssam * 148189251Ssam * In case of Windows implementation (eloop_win.c), event pointer is of HANDLE 149189251Ssam * type, i.e., void*. The callers are likely to have 'HANDLE h' type variable, 150189251Ssam * and they would call this function with eloop_register_event(h, sizeof(h), 151189251Ssam * ...). 152189251Ssam */ 153189251Ssamint eloop_register_event(void *event, size_t event_size, 154189251Ssam eloop_event_handler handler, 155189251Ssam void *eloop_data, void *user_data); 156189251Ssam 157189251Ssam/** 158189251Ssam * eloop_unregister_event - Unregister handler for a generic event 159189251Ssam * @event: Event to cancel (eloop implementation specific) 160189251Ssam * @event_size: Size of event data 161189251Ssam * 162189251Ssam * Unregister a generic event notifier that was previously registered with 163189251Ssam * eloop_register_event(). 164189251Ssam */ 165189251Ssamvoid eloop_unregister_event(void *event, size_t event_size); 166189251Ssam 167189251Ssam/** 168189251Ssam * eloop_register_timeout - Register timeout 169189251Ssam * @secs: Number of seconds to the timeout 170189251Ssam * @usecs: Number of microseconds to the timeout 171189251Ssam * @handler: Callback function to be called when timeout occurs 172189251Ssam * @eloop_data: Callback context data (eloop_ctx) 173189251Ssam * @user_data: Callback context data (sock_ctx) 174189251Ssam * Returns: 0 on success, -1 on failure 175189251Ssam * 176189251Ssam * Register a timeout that will cause the handler function to be called after 177189251Ssam * given time. 178189251Ssam */ 179189251Ssamint eloop_register_timeout(unsigned int secs, unsigned int usecs, 180189251Ssam eloop_timeout_handler handler, 181189251Ssam void *eloop_data, void *user_data); 182189251Ssam 183189251Ssam/** 184189251Ssam * eloop_cancel_timeout - Cancel timeouts 185189251Ssam * @handler: Matching callback function 186189251Ssam * @eloop_data: Matching eloop_data or %ELOOP_ALL_CTX to match all 187189251Ssam * @user_data: Matching user_data or %ELOOP_ALL_CTX to match all 188189251Ssam * Returns: Number of cancelled timeouts 189189251Ssam * 190189251Ssam * Cancel matching <handler,eloop_data,user_data> timeouts registered with 191189251Ssam * eloop_register_timeout(). ELOOP_ALL_CTX can be used as a wildcard for 192189251Ssam * cancelling all timeouts regardless of eloop_data/user_data. 193189251Ssam */ 194189251Ssamint eloop_cancel_timeout(eloop_timeout_handler handler, 195189251Ssam void *eloop_data, void *user_data); 196189251Ssam 197189251Ssam/** 198281806Srpaulo * eloop_cancel_timeout_one - Cancel a single timeout 199281806Srpaulo * @handler: Matching callback function 200281806Srpaulo * @eloop_data: Matching eloop_data 201281806Srpaulo * @user_data: Matching user_data 202281806Srpaulo * @remaining: Time left on the cancelled timer 203281806Srpaulo * Returns: Number of cancelled timeouts 204281806Srpaulo * 205281806Srpaulo * Cancel matching <handler,eloop_data,user_data> timeout registered with 206281806Srpaulo * eloop_register_timeout() and return the remaining time left. 207281806Srpaulo */ 208281806Srpauloint eloop_cancel_timeout_one(eloop_timeout_handler handler, 209281806Srpaulo void *eloop_data, void *user_data, 210281806Srpaulo struct os_reltime *remaining); 211281806Srpaulo 212281806Srpaulo/** 213189251Ssam * eloop_is_timeout_registered - Check if a timeout is already registered 214189251Ssam * @handler: Matching callback function 215189251Ssam * @eloop_data: Matching eloop_data 216189251Ssam * @user_data: Matching user_data 217189251Ssam * Returns: 1 if the timeout is registered, 0 if the timeout is not registered 218189251Ssam * 219189251Ssam * Determine if a matching <handler,eloop_data,user_data> timeout is registered 220189251Ssam * with eloop_register_timeout(). 221189251Ssam */ 222189251Ssamint eloop_is_timeout_registered(eloop_timeout_handler handler, 223189251Ssam void *eloop_data, void *user_data); 224189251Ssam 225189251Ssam/** 226281806Srpaulo * eloop_deplete_timeout - Deplete a timeout that is already registered 227281806Srpaulo * @req_secs: Requested number of seconds to the timeout 228281806Srpaulo * @req_usecs: Requested number of microseconds to the timeout 229281806Srpaulo * @handler: Matching callback function 230281806Srpaulo * @eloop_data: Matching eloop_data 231281806Srpaulo * @user_data: Matching user_data 232281806Srpaulo * Returns: 1 if the timeout is depleted, 0 if no change is made, -1 if no 233281806Srpaulo * timeout matched 234281806Srpaulo * 235281806Srpaulo * Find a registered matching <handler,eloop_data,user_data> timeout. If found, 236281806Srpaulo * deplete the timeout if remaining time is more than the requested time. 237281806Srpaulo */ 238281806Srpauloint eloop_deplete_timeout(unsigned int req_secs, unsigned int req_usecs, 239281806Srpaulo eloop_timeout_handler handler, void *eloop_data, 240281806Srpaulo void *user_data); 241281806Srpaulo 242281806Srpaulo/** 243281806Srpaulo * eloop_replenish_timeout - Replenish a timeout that is already registered 244281806Srpaulo * @req_secs: Requested number of seconds to the timeout 245281806Srpaulo * @req_usecs: Requested number of microseconds to the timeout 246281806Srpaulo * @handler: Matching callback function 247281806Srpaulo * @eloop_data: Matching eloop_data 248281806Srpaulo * @user_data: Matching user_data 249281806Srpaulo * Returns: 1 if the timeout is replenished, 0 if no change is made, -1 if no 250281806Srpaulo * timeout matched 251281806Srpaulo * 252281806Srpaulo * Find a registered matching <handler,eloop_data,user_data> timeout. If found, 253281806Srpaulo * replenish the timeout if remaining time is less than the requested time. 254281806Srpaulo */ 255281806Srpauloint eloop_replenish_timeout(unsigned int req_secs, unsigned int req_usecs, 256281806Srpaulo eloop_timeout_handler handler, void *eloop_data, 257281806Srpaulo void *user_data); 258281806Srpaulo 259281806Srpaulo/** 260189251Ssam * eloop_register_signal - Register handler for signals 261189251Ssam * @sig: Signal number (e.g., SIGHUP) 262189251Ssam * @handler: Callback function to be called when the signal is received 263189251Ssam * @user_data: Callback context data (signal_ctx) 264189251Ssam * Returns: 0 on success, -1 on failure 265189251Ssam * 266189251Ssam * Register a callback function that will be called when a signal is received. 267189251Ssam * The callback function is actually called only after the system signal 268189251Ssam * handler has returned. This means that the normal limits for sighandlers 269189251Ssam * (i.e., only "safe functions" allowed) do not apply for the registered 270189251Ssam * callback. 271189251Ssam */ 272189251Ssamint eloop_register_signal(int sig, eloop_signal_handler handler, 273189251Ssam void *user_data); 274189251Ssam 275189251Ssam/** 276189251Ssam * eloop_register_signal_terminate - Register handler for terminate signals 277189251Ssam * @handler: Callback function to be called when the signal is received 278189251Ssam * @user_data: Callback context data (signal_ctx) 279189251Ssam * Returns: 0 on success, -1 on failure 280189251Ssam * 281189251Ssam * Register a callback function that will be called when a process termination 282189251Ssam * signal is received. The callback function is actually called only after the 283189251Ssam * system signal handler has returned. This means that the normal limits for 284189251Ssam * sighandlers (i.e., only "safe functions" allowed) do not apply for the 285189251Ssam * registered callback. 286189251Ssam * 287189251Ssam * This function is a more portable version of eloop_register_signal() since 288189251Ssam * the knowledge of exact details of the signals is hidden in eloop 289189251Ssam * implementation. In case of operating systems using signal(), this function 290189251Ssam * registers handlers for SIGINT and SIGTERM. 291189251Ssam */ 292189251Ssamint eloop_register_signal_terminate(eloop_signal_handler handler, 293189251Ssam void *user_data); 294189251Ssam 295189251Ssam/** 296189251Ssam * eloop_register_signal_reconfig - Register handler for reconfig signals 297189251Ssam * @handler: Callback function to be called when the signal is received 298189251Ssam * @user_data: Callback context data (signal_ctx) 299189251Ssam * Returns: 0 on success, -1 on failure 300189251Ssam * 301189251Ssam * Register a callback function that will be called when a reconfiguration / 302189251Ssam * hangup signal is received. The callback function is actually called only 303189251Ssam * after the system signal handler has returned. This means that the normal 304189251Ssam * limits for sighandlers (i.e., only "safe functions" allowed) do not apply 305189251Ssam * for the registered callback. 306189251Ssam * 307189251Ssam * This function is a more portable version of eloop_register_signal() since 308189251Ssam * the knowledge of exact details of the signals is hidden in eloop 309189251Ssam * implementation. In case of operating systems using signal(), this function 310189251Ssam * registers a handler for SIGHUP. 311189251Ssam */ 312189251Ssamint eloop_register_signal_reconfig(eloop_signal_handler handler, 313189251Ssam void *user_data); 314189251Ssam 315189251Ssam/** 316337817Scy * eloop_sock_requeue - Requeue sockets 317337817Scy * 318337817Scy * Requeue sockets after forking because some implementations require this, 319337817Scy * such as epoll and kqueue. 320337817Scy */ 321337817Scyint eloop_sock_requeue(void); 322337817Scy 323337817Scy/** 324189251Ssam * eloop_run - Start the event loop 325189251Ssam * 326189251Ssam * Start the event loop and continue running as long as there are any 327189251Ssam * registered event handlers. This function is run after event loop has been 328189251Ssam * initialized with event_init() and one or more events have been registered. 329189251Ssam */ 330189251Ssamvoid eloop_run(void); 331189251Ssam 332189251Ssam/** 333189251Ssam * eloop_terminate - Terminate event loop 334189251Ssam * 335189251Ssam * Terminate event loop even if there are registered events. This can be used 336189251Ssam * to request the program to be terminated cleanly. 337189251Ssam */ 338189251Ssamvoid eloop_terminate(void); 339189251Ssam 340189251Ssam/** 341189251Ssam * eloop_destroy - Free any resources allocated for the event loop 342189251Ssam * 343189251Ssam * After calling eloop_destroy(), other eloop_* functions must not be called 344189251Ssam * before re-running eloop_init(). 345189251Ssam */ 346189251Ssamvoid eloop_destroy(void); 347189251Ssam 348189251Ssam/** 349189251Ssam * eloop_terminated - Check whether event loop has been terminated 350189251Ssam * Returns: 1 = event loop terminate, 0 = event loop still running 351189251Ssam * 352189251Ssam * This function can be used to check whether eloop_terminate() has been called 353189251Ssam * to request termination of the event loop. This is normally used to abort 354189251Ssam * operations that may still be queued to be run when eloop_terminate() was 355189251Ssam * called. 356189251Ssam */ 357189251Ssamint eloop_terminated(void); 358189251Ssam 359189251Ssam/** 360189251Ssam * eloop_wait_for_read_sock - Wait for a single reader 361189251Ssam * @sock: File descriptor number for the socket 362189251Ssam * 363189251Ssam * Do a blocking wait for a single read socket. 364189251Ssam */ 365189251Ssamvoid eloop_wait_for_read_sock(int sock); 366189251Ssam 367189251Ssam#endif /* ELOOP_H */ 368