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