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