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 * @signal_ctx: Registered callback context data (user_data from 69 * eloop_register_signal(), eloop_register_signal_terminate(), or 70 * eloop_register_signal_reconfig() call) 71 */ 72 typedef void (*eloop_signal_handler)(int sig, void *signal_ctx); 73 74 /** 75 * eloop_init() - Initialize global event loop data 76 * Returns: 0 on success, -1 on failure 77 * 78 * This function must be called before any other eloop_* function. 79 */ 80 int eloop_init(void); 81 82 /** 83 * eloop_register_read_sock - Register handler for read events 84 * @sock: File descriptor number for the socket 85 * @handler: Callback function to be called when data is available for reading 86 * @eloop_data: Callback context data (eloop_ctx) 87 * @user_data: Callback context data (sock_ctx) 88 * Returns: 0 on success, -1 on failure 89 * 90 * Register a read socket notifier for the given file descriptor. The handler 91 * function will be called whenever data is available for reading from the 92 * socket. The handler function is responsible for clearing the event after 93 * having processed it in order to avoid eloop from calling the handler again 94 * for the same event. 95 */ 96 int eloop_register_read_sock(int sock, eloop_sock_handler handler, 97 void *eloop_data, void *user_data); 98 99 /** 100 * eloop_unregister_read_sock - Unregister handler for read events 101 * @sock: File descriptor number for the socket 102 * 103 * Unregister a read socket notifier that was previously registered with 104 * eloop_register_read_sock(). 105 */ 106 void eloop_unregister_read_sock(int sock); 107 108 /** 109 * eloop_register_sock - Register handler for socket events 110 * @sock: File descriptor number for the socket 111 * @type: Type of event to wait for 112 * @handler: Callback function to be called when the event is triggered 113 * @eloop_data: Callback context data (eloop_ctx) 114 * @user_data: Callback context data (sock_ctx) 115 * Returns: 0 on success, -1 on failure 116 * 117 * Register an event notifier for the given socket's file descriptor. The 118 * handler function will be called whenever the that event is triggered for the 119 * socket. The handler function is responsible for clearing the event after 120 * having processed it in order to avoid eloop from calling the handler again 121 * for the same event. 122 */ 123 int eloop_register_sock(int sock, eloop_event_type type, 124 eloop_sock_handler handler, 125 void *eloop_data, void *user_data); 126 127 /** 128 * eloop_unregister_sock - Unregister handler for socket events 129 * @sock: File descriptor number for the socket 130 * @type: Type of event for which sock was registered 131 * 132 * Unregister a socket event notifier that was previously registered with 133 * eloop_register_sock(). 134 */ 135 void eloop_unregister_sock(int sock, eloop_event_type type); 136 137 /** 138 * eloop_register_event - Register handler for generic events 139 * @event: Event to wait (eloop implementation specific) 140 * @event_size: Size of event data 141 * @handler: Callback function to be called when event is triggered 142 * @eloop_data: Callback context data (eloop_data) 143 * @user_data: Callback context data (user_data) 144 * Returns: 0 on success, -1 on failure 145 * 146 * Register an event handler for the given event. This function is used to 147 * register eloop implementation specific events which are mainly targetted for 148 * operating system specific code (driver interface and l2_packet) since the 149 * portable code will not be able to use such an OS-specific call. The handler 150 * function will be called whenever the event is triggered. The handler 151 * function is responsible for clearing the event after having processed it in 152 * order to avoid eloop from calling the handler again for the same event. 153 * 154 * In case of Windows implementation (eloop_win.c), event pointer is of HANDLE 155 * type, i.e., void*. The callers are likely to have 'HANDLE h' type variable, 156 * and they would call this function with eloop_register_event(h, sizeof(h), 157 * ...). 158 */ 159 int eloop_register_event(void *event, size_t event_size, 160 eloop_event_handler handler, 161 void *eloop_data, void *user_data); 162 163 /** 164 * eloop_unregister_event - Unregister handler for a generic event 165 * @event: Event to cancel (eloop implementation specific) 166 * @event_size: Size of event data 167 * 168 * Unregister a generic event notifier that was previously registered with 169 * eloop_register_event(). 170 */ 171 void eloop_unregister_event(void *event, size_t event_size); 172 173 /** 174 * eloop_register_timeout - Register timeout 175 * @secs: Number of seconds to the timeout 176 * @usecs: Number of microseconds to the timeout 177 * @handler: Callback function to be called when timeout occurs 178 * @eloop_data: Callback context data (eloop_ctx) 179 * @user_data: Callback context data (sock_ctx) 180 * Returns: 0 on success, -1 on failure 181 * 182 * Register a timeout that will cause the handler function to be called after 183 * given time. 184 */ 185 int eloop_register_timeout(unsigned int secs, unsigned int usecs, 186 eloop_timeout_handler handler, 187 void *eloop_data, void *user_data); 188 189 /** 190 * eloop_cancel_timeout - Cancel timeouts 191 * @handler: Matching callback function 192 * @eloop_data: Matching eloop_data or %ELOOP_ALL_CTX to match all 193 * @user_data: Matching user_data or %ELOOP_ALL_CTX to match all 194 * Returns: Number of cancelled timeouts 195 * 196 * Cancel matching <handler,eloop_data,user_data> timeouts registered with 197 * eloop_register_timeout(). ELOOP_ALL_CTX can be used as a wildcard for 198 * cancelling all timeouts regardless of eloop_data/user_data. 199 */ 200 int eloop_cancel_timeout(eloop_timeout_handler handler, 201 void *eloop_data, void *user_data); 202 203 /** 204 * eloop_is_timeout_registered - Check if a timeout is already registered 205 * @handler: Matching callback function 206 * @eloop_data: Matching eloop_data 207 * @user_data: Matching user_data 208 * Returns: 1 if the timeout is registered, 0 if the timeout is not registered 209 * 210 * Determine if a matching <handler,eloop_data,user_data> timeout is registered 211 * with eloop_register_timeout(). 212 */ 213 int eloop_is_timeout_registered(eloop_timeout_handler handler, 214 void *eloop_data, void *user_data); 215 216 /** 217 * eloop_register_signal - Register handler for signals 218 * @sig: Signal number (e.g., SIGHUP) 219 * @handler: Callback function to be called when the signal is received 220 * @user_data: Callback context data (signal_ctx) 221 * Returns: 0 on success, -1 on failure 222 * 223 * Register a callback function that will be called when a signal is received. 224 * The callback function is actually called only after the system signal 225 * handler has returned. This means that the normal limits for sighandlers 226 * (i.e., only "safe functions" allowed) do not apply for the registered 227 * callback. 228 */ 229 int eloop_register_signal(int sig, eloop_signal_handler handler, 230 void *user_data); 231 232 /** 233 * eloop_register_signal_terminate - Register handler for terminate signals 234 * @handler: Callback function to be called when the signal is received 235 * @user_data: Callback context data (signal_ctx) 236 * Returns: 0 on success, -1 on failure 237 * 238 * Register a callback function that will be called when a process termination 239 * signal is received. The callback function is actually called only after the 240 * system signal handler has returned. This means that the normal limits for 241 * sighandlers (i.e., only "safe functions" allowed) do not apply for the 242 * registered callback. 243 * 244 * This function is a more portable version of eloop_register_signal() since 245 * the knowledge of exact details of the signals is hidden in eloop 246 * implementation. In case of operating systems using signal(), this function 247 * registers handlers for SIGINT and SIGTERM. 248 */ 249 int eloop_register_signal_terminate(eloop_signal_handler handler, 250 void *user_data); 251 252 /** 253 * eloop_register_signal_reconfig - Register handler for reconfig signals 254 * @handler: Callback function to be called when the signal is received 255 * @user_data: Callback context data (signal_ctx) 256 * Returns: 0 on success, -1 on failure 257 * 258 * Register a callback function that will be called when a reconfiguration / 259 * hangup signal is received. The callback function is actually called only 260 * after the system signal handler has returned. This means that the normal 261 * limits for sighandlers (i.e., only "safe functions" allowed) do not apply 262 * for the registered callback. 263 * 264 * This function is a more portable version of eloop_register_signal() since 265 * the knowledge of exact details of the signals is hidden in eloop 266 * implementation. In case of operating systems using signal(), this function 267 * registers a handler for SIGHUP. 268 */ 269 int eloop_register_signal_reconfig(eloop_signal_handler handler, 270 void *user_data); 271 272 /** 273 * eloop_run - Start the event loop 274 * 275 * Start the event loop and continue running as long as there are any 276 * registered event handlers. This function is run after event loop has been 277 * initialized with event_init() and one or more events have been registered. 278 */ 279 void eloop_run(void); 280 281 /** 282 * eloop_terminate - Terminate event loop 283 * 284 * Terminate event loop even if there are registered events. This can be used 285 * to request the program to be terminated cleanly. 286 */ 287 void eloop_terminate(void); 288 289 /** 290 * eloop_destroy - Free any resources allocated for the event loop 291 * 292 * After calling eloop_destroy(), other eloop_* functions must not be called 293 * before re-running eloop_init(). 294 */ 295 void eloop_destroy(void); 296 297 /** 298 * eloop_terminated - Check whether event loop has been terminated 299 * Returns: 1 = event loop terminate, 0 = event loop still running 300 * 301 * This function can be used to check whether eloop_terminate() has been called 302 * to request termination of the event loop. This is normally used to abort 303 * operations that may still be queued to be run when eloop_terminate() was 304 * called. 305 */ 306 int eloop_terminated(void); 307 308 /** 309 * eloop_wait_for_read_sock - Wait for a single reader 310 * @sock: File descriptor number for the socket 311 * 312 * Do a blocking wait for a single read socket. 313 */ 314 void eloop_wait_for_read_sock(int sock); 315 316 #endif /* ELOOP_H */ 317