1 /* 2 * Event loop 3 * Copyright (c) 2002-2006, Jouni Malinen <j@w1.fi> 4 * 5 * This program is free software; you can redistribute it and/or modify 6 * it under the terms of the GNU General Public License version 2 as 7 * published by the Free Software Foundation. 8 * 9 * Alternatively, this software may be distributed under the terms of BSD 10 * license. 11 * 12 * See README and COPYING for more details. 13 * 14 * This file defines an event loop interface that supports processing events 15 * from registered timeouts (i.e., do something after N seconds), sockets 16 * (e.g., a new packet available for reading), and signals. eloop.c is an 17 * implementation of this interface using select() and sockets. This is 18 * suitable for most UNIX/POSIX systems. When porting to other operating 19 * systems, it may be necessary to replace that implementation with OS specific 20 * mechanisms. 21 */ 22 23 #ifndef ELOOP_H 24 #define ELOOP_H 25 26 /** 27 * ELOOP_ALL_CTX - eloop_cancel_timeout() magic number to match all timeouts 28 */ 29 #define ELOOP_ALL_CTX (void *) -1 30 31 /** 32 * eloop_event_type - eloop socket event type for eloop_register_sock() 33 * @EVENT_TYPE_READ: Socket has data available for reading 34 * @EVENT_TYPE_WRITE: Socket has room for new data to be written 35 * @EVENT_TYPE_EXCEPTION: An exception has been reported 36 */ 37 typedef enum { 38 EVENT_TYPE_READ = 0, 39 EVENT_TYPE_WRITE, 40 EVENT_TYPE_EXCEPTION 41 } eloop_event_type; 42 43 /** 44 * eloop_sock_handler - eloop socket event callback type 45 * @sock: File descriptor number for the socket 46 * @eloop_ctx: Registered callback context data (eloop_data) 47 * @sock_ctx: Registered callback context data (user_data) 48 */ 49 typedef void (*eloop_sock_handler)(int sock, void *eloop_ctx, void *sock_ctx); 50 51 /** 52 * eloop_event_handler - eloop generic event callback type 53 * @eloop_ctx: Registered callback context data (eloop_data) 54 * @sock_ctx: Registered callback context data (user_data) 55 */ 56 typedef void (*eloop_event_handler)(void *eloop_data, void *user_ctx); 57 58 /** 59 * eloop_timeout_handler - eloop timeout event callback type 60 * @eloop_ctx: Registered callback context data (eloop_data) 61 * @sock_ctx: Registered callback context data (user_data) 62 */ 63 typedef void (*eloop_timeout_handler)(void *eloop_data, void *user_ctx); 64 65 /** 66 * eloop_signal_handler - eloop signal event callback type 67 * @sig: Signal number 68 * @eloop_ctx: Registered callback context data (global user_data from 69 * eloop_init() call) 70 * @signal_ctx: Registered callback context data (user_data from 71 * eloop_register_signal(), eloop_register_signal_terminate(), or 72 * eloop_register_signal_reconfig() call) 73 */ 74 typedef void (*eloop_signal_handler)(int sig, void *eloop_ctx, 75 void *signal_ctx); 76 77 /** 78 * eloop_init() - Initialize global event loop data 79 * @user_data: Pointer to global data passed as eloop_ctx to signal handlers 80 * Returns: 0 on success, -1 on failure 81 * 82 * This function must be called before any other eloop_* function. user_data 83 * can be used to configure a global (to the process) pointer that will be 84 * passed as eloop_ctx parameter to signal handlers. 85 */ 86 int eloop_init(void *user_data); 87 88 /** 89 * eloop_register_read_sock - Register handler for read events 90 * @sock: File descriptor number for the socket 91 * @handler: Callback function to be called when data is available for reading 92 * @eloop_data: Callback context data (eloop_ctx) 93 * @user_data: Callback context data (sock_ctx) 94 * Returns: 0 on success, -1 on failure 95 * 96 * Register a read socket notifier for the given file descriptor. The handler 97 * function will be called whenever data is available for reading from the 98 * socket. The handler function is responsible for clearing the event after 99 * having processed it in order to avoid eloop from calling the handler again 100 * for the same event. 101 */ 102 int eloop_register_read_sock(int sock, eloop_sock_handler handler, 103 void *eloop_data, void *user_data); 104 105 /** 106 * eloop_unregister_read_sock - Unregister handler for read events 107 * @sock: File descriptor number for the socket 108 * 109 * Unregister a read socket notifier that was previously registered with 110 * eloop_register_read_sock(). 111 */ 112 void eloop_unregister_read_sock(int sock); 113 114 /** 115 * eloop_register_sock - Register handler for socket events 116 * @sock: File descriptor number for the socket 117 * @type: Type of event to wait for 118 * @handler: Callback function to be called when the event is triggered 119 * @eloop_data: Callback context data (eloop_ctx) 120 * @user_data: Callback context data (sock_ctx) 121 * Returns: 0 on success, -1 on failure 122 * 123 * Register an event notifier for the given socket's file descriptor. The 124 * handler function will be called whenever the that event is triggered for the 125 * socket. The handler function is responsible for clearing the event after 126 * having processed it in order to avoid eloop from calling the handler again 127 * for the same event. 128 */ 129 int eloop_register_sock(int sock, eloop_event_type type, 130 eloop_sock_handler handler, 131 void *eloop_data, void *user_data); 132 133 /** 134 * eloop_unregister_sock - Unregister handler for socket events 135 * @sock: File descriptor number for the socket 136 * @type: Type of event for which sock was registered 137 * 138 * Unregister a socket event notifier that was previously registered with 139 * eloop_register_sock(). 140 */ 141 void eloop_unregister_sock(int sock, eloop_event_type type); 142 143 /** 144 * eloop_register_event - Register handler for generic events 145 * @event: Event to wait (eloop implementation specific) 146 * @event_size: Size of event data 147 * @handler: Callback function to be called when event is triggered 148 * @eloop_data: Callback context data (eloop_data) 149 * @user_data: Callback context data (user_data) 150 * Returns: 0 on success, -1 on failure 151 * 152 * Register an event handler for the given event. This function is used to 153 * register eloop implementation specific events which are mainly targetted for 154 * operating system specific code (driver interface and l2_packet) since the 155 * portable code will not be able to use such an OS-specific call. The handler 156 * function will be called whenever the event is triggered. The handler 157 * function is responsible for clearing the event after having processed it in 158 * order to avoid eloop from calling the handler again for the same event. 159 * 160 * In case of Windows implementation (eloop_win.c), event pointer is of HANDLE 161 * type, i.e., void*. The callers are likely to have 'HANDLE h' type variable, 162 * and they would call this function with eloop_register_event(h, sizeof(h), 163 * ...). 164 */ 165 int eloop_register_event(void *event, size_t event_size, 166 eloop_event_handler handler, 167 void *eloop_data, void *user_data); 168 169 /** 170 * eloop_unregister_event - Unregister handler for a generic event 171 * @event: Event to cancel (eloop implementation specific) 172 * @event_size: Size of event data 173 * 174 * Unregister a generic event notifier that was previously registered with 175 * eloop_register_event(). 176 */ 177 void eloop_unregister_event(void *event, size_t event_size); 178 179 /** 180 * eloop_register_timeout - Register timeout 181 * @secs: Number of seconds to the timeout 182 * @usecs: Number of microseconds to the timeout 183 * @handler: Callback function to be called when timeout occurs 184 * @eloop_data: Callback context data (eloop_ctx) 185 * @user_data: Callback context data (sock_ctx) 186 * Returns: 0 on success, -1 on failure 187 * 188 * Register a timeout that will cause the handler function to be called after 189 * given time. 190 */ 191 int eloop_register_timeout(unsigned int secs, unsigned int usecs, 192 eloop_timeout_handler handler, 193 void *eloop_data, void *user_data); 194 195 /** 196 * eloop_cancel_timeout - Cancel timeouts 197 * @handler: Matching callback function 198 * @eloop_data: Matching eloop_data or %ELOOP_ALL_CTX to match all 199 * @user_data: Matching user_data or %ELOOP_ALL_CTX to match all 200 * Returns: Number of cancelled timeouts 201 * 202 * Cancel matching <handler,eloop_data,user_data> timeouts registered with 203 * eloop_register_timeout(). ELOOP_ALL_CTX can be used as a wildcard for 204 * cancelling all timeouts regardless of eloop_data/user_data. 205 */ 206 int eloop_cancel_timeout(eloop_timeout_handler handler, 207 void *eloop_data, void *user_data); 208 209 /** 210 * eloop_is_timeout_registered - Check if a timeout is already registered 211 * @handler: Matching callback function 212 * @eloop_data: Matching eloop_data 213 * @user_data: Matching user_data 214 * Returns: 1 if the timeout is registered, 0 if the timeout is not registered 215 * 216 * Determine if a matching <handler,eloop_data,user_data> timeout is registered 217 * with eloop_register_timeout(). 218 */ 219 int eloop_is_timeout_registered(eloop_timeout_handler handler, 220 void *eloop_data, void *user_data); 221 222 /** 223 * eloop_register_signal - Register handler for signals 224 * @sig: Signal number (e.g., SIGHUP) 225 * @handler: Callback function to be called when the signal is received 226 * @user_data: Callback context data (signal_ctx) 227 * Returns: 0 on success, -1 on failure 228 * 229 * Register a callback function that will be called when a signal is received. 230 * The callback function is actually called only after the system signal 231 * handler has returned. This means that the normal limits for sighandlers 232 * (i.e., only "safe functions" allowed) do not apply for the registered 233 * callback. 234 * 235 * Signals are 'global' events and there is no local eloop_data pointer like 236 * with other handlers. The global user_data pointer registered with 237 * eloop_init() will be used as eloop_ctx for signal handlers. 238 */ 239 int eloop_register_signal(int sig, eloop_signal_handler handler, 240 void *user_data); 241 242 /** 243 * eloop_register_signal_terminate - Register handler for terminate signals 244 * @handler: Callback function to be called when the signal is received 245 * @user_data: Callback context data (signal_ctx) 246 * Returns: 0 on success, -1 on failure 247 * 248 * Register a callback function that will be called when a process termination 249 * signal is received. The callback function is actually called only after the 250 * system signal handler has returned. This means that the normal limits for 251 * sighandlers (i.e., only "safe functions" allowed) do not apply for the 252 * registered callback. 253 * 254 * Signals are 'global' events and there is no local eloop_data pointer like 255 * with other handlers. The global user_data pointer registered with 256 * eloop_init() will be used as eloop_ctx for signal handlers. 257 * 258 * This function is a more portable version of eloop_register_signal() since 259 * the knowledge of exact details of the signals is hidden in eloop 260 * implementation. In case of operating systems using signal(), this function 261 * registers handlers for SIGINT and SIGTERM. 262 */ 263 int eloop_register_signal_terminate(eloop_signal_handler handler, 264 void *user_data); 265 266 /** 267 * eloop_register_signal_reconfig - Register handler for reconfig signals 268 * @handler: Callback function to be called when the signal is received 269 * @user_data: Callback context data (signal_ctx) 270 * Returns: 0 on success, -1 on failure 271 * 272 * Register a callback function that will be called when a reconfiguration / 273 * hangup signal is received. The callback function is actually called only 274 * after the system signal handler has returned. This means that the normal 275 * limits for sighandlers (i.e., only "safe functions" allowed) do not apply 276 * for the registered callback. 277 * 278 * Signals are 'global' events and there is no local eloop_data pointer like 279 * with other handlers. The global user_data pointer registered with 280 * eloop_init() will be used as eloop_ctx for signal handlers. 281 * 282 * This function is a more portable version of eloop_register_signal() since 283 * the knowledge of exact details of the signals is hidden in eloop 284 * implementation. In case of operating systems using signal(), this function 285 * registers a handler for SIGHUP. 286 */ 287 int eloop_register_signal_reconfig(eloop_signal_handler handler, 288 void *user_data); 289 290 /** 291 * eloop_run - Start the event loop 292 * 293 * Start the event loop and continue running as long as there are any 294 * registered event handlers. This function is run after event loop has been 295 * initialized with event_init() and one or more events have been registered. 296 */ 297 void eloop_run(void); 298 299 /** 300 * eloop_terminate - Terminate event loop 301 * 302 * Terminate event loop even if there are registered events. This can be used 303 * to request the program to be terminated cleanly. 304 */ 305 void eloop_terminate(void); 306 307 /** 308 * eloop_destroy - Free any resources allocated for the event loop 309 * 310 * After calling eloop_destroy(), other eloop_* functions must not be called 311 * before re-running eloop_init(). 312 */ 313 void eloop_destroy(void); 314 315 /** 316 * eloop_terminated - Check whether event loop has been terminated 317 * Returns: 1 = event loop terminate, 0 = event loop still running 318 * 319 * This function can be used to check whether eloop_terminate() has been called 320 * to request termination of the event loop. This is normally used to abort 321 * operations that may still be queued to be run when eloop_terminate() was 322 * called. 323 */ 324 int eloop_terminated(void); 325 326 /** 327 * eloop_wait_for_read_sock - Wait for a single reader 328 * @sock: File descriptor number for the socket 329 * 330 * Do a blocking wait for a single read socket. 331 */ 332 void eloop_wait_for_read_sock(int sock); 333 334 /** 335 * eloop_get_user_data - Get global user data 336 * Returns: user_data pointer that was registered with eloop_init() 337 */ 338 void * eloop_get_user_data(void); 339 340 #endif /* ELOOP_H */ 341