libeap/src/utils/eloop.h

   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  * @sock_ctx: Registered callback context data (user_data)
  49  */
  50 typedef void (*eloop_event_handler)(void *eloop_data, void *user_ctx);
  51
  52 /**
  53  * eloop_timeout_handler - eloop timeout event callback type
  54  * @eloop_ctx: Registered callback context data (eloop_data)
  55  * @sock_ctx: Registered callback context data (user_data)
  56  */
  57 typedef void (*eloop_timeout_handler)(void *eloop_data, 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 int eloop_register_timeout(unsigned int secs, unsigned int usecs,
 180                            eloop_timeout_handler handler,
 181                            void *eloop_data, void *user_data);
 182
 183 /**
 184  * eloop_cancel_timeout - Cancel timeouts
 185  * @handler: Matching callback function
 186  * @eloop_data: Matching eloop_data or %ELOOP_ALL_CTX to match all
 187  * @user_data: Matching user_data or %ELOOP_ALL_CTX to match all
 188  * Returns: Number of cancelled timeouts
 189  *
 190  * Cancel matching <handler,eloop_data,user_data> timeouts registered with
 191  * eloop_register_timeout(). ELOOP_ALL_CTX can be used as a wildcard for
 192  * cancelling all timeouts regardless of eloop_data/user_data.
 193  */
 194 int eloop_cancel_timeout(eloop_timeout_handler handler,
 195                          void *eloop_data, void *user_data);
 196
 197 /**
 198  * eloop_cancel_timeout_one - Cancel a single timeout
 199  * @handler: Matching callback function
 200  * @eloop_data: Matching eloop_data
 201  * @user_data: Matching user_data
 202  * @remaining: Time left on the cancelled timer
 203  * Returns: Number of cancelled timeouts
 204  *
 205  * Cancel matching <handler,eloop_data,user_data> timeout registered with
 206  * eloop_register_timeout() and return the remaining time left.
 207  */
 208 int eloop_cancel_timeout_one(eloop_timeout_handler handler,
 209                              void *eloop_data, void *user_data,
 210                              struct os_reltime *remaining);
 211
 212 /**
 213  * eloop_is_timeout_registered - Check if a timeout is already registered
 214  * @handler: Matching callback function
 215  * @eloop_data: Matching eloop_data
 216  * @user_data: Matching user_data
 217  * Returns: 1 if the timeout is registered, 0 if the timeout is not registered
 218  *
 219  * Determine if a matching <handler,eloop_data,user_data> timeout is registered
 220  * with eloop_register_timeout().
 221  */
 222 int eloop_is_timeout_registered(eloop_timeout_handler handler,
 223                                 void *eloop_data, void *user_data);
 224
 225 /**
 226  * eloop_deplete_timeout - Deplete a timeout that is already registered
 227  * @req_secs: Requested number of seconds to the timeout
 228  * @req_usecs: Requested number of microseconds to the timeout
 229  * @handler: Matching callback function
 230  * @eloop_data: Matching eloop_data
 231  * @user_data: Matching user_data
 232  * Returns: 1 if the timeout is depleted, 0 if no change is made, -1 if no
 233  * timeout matched
 234  *
 235  * Find a registered matching <handler,eloop_data,user_data> timeout. If found,
 236  * deplete the timeout if remaining time is more than the requested time.
 237  */
 238 int eloop_deplete_timeout(unsigned int req_secs, unsigned int req_usecs,
 239                           eloop_timeout_handler handler, void *eloop_data,
 240                           void *user_data);
 241
 242 /**
 243  * eloop_replenish_timeout - Replenish 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 replenished, 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  * replenish the timeout if remaining time is less than the requested time.
 254  */
 255 int eloop_replenish_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_register_signal - Register handler for signals
 261  * @sig: Signal number (e.g., SIGHUP)
 262  * @handler: Callback function to be called when the signal is received
 263  * @user_data: Callback context data (signal_ctx)
 264  * Returns: 0 on success, -1 on failure
 265  *
 266  * Register a callback function that will be called when a signal is received.
 267  * The callback function is actually called only after the system signal
 268  * handler has returned. This means that the normal limits for sighandlers
 269  * (i.e., only "safe functions" allowed) do not apply for the registered
 270  * callback.
 271  */
 272 int eloop_register_signal(int sig, eloop_signal_handler handler,
 273                           void *user_data);
 274
 275 /**
 276  * eloop_register_signal_terminate - Register handler for terminate signals
 277  * @handler: Callback function to be called when the signal is received
 278  * @user_data: Callback context data (signal_ctx)
 279  * Returns: 0 on success, -1 on failure
 280  *
 281  * Register a callback function that will be called when a process termination
 282  * signal is received. The callback function is actually called only after the
 283  * system signal handler has returned. This means that the normal limits for
 284  * sighandlers (i.e., only "safe functions" allowed) do not apply for the
 285  * registered callback.
 286  *
 287  * This function is a more portable version of eloop_register_signal() since
 288  * the knowledge of exact details of the signals is hidden in eloop
 289  * implementation. In case of operating systems using signal(), this function
 290  * registers handlers for SIGINT and SIGTERM.
 291  */
 292 int eloop_register_signal_terminate(eloop_signal_handler handler,
 293                                     void *user_data);
 294
 295 /**
 296  * eloop_register_signal_reconfig - Register handler for reconfig signals
 297  * @handler: Callback function to be called when the signal is received
 298  * @user_data: Callback context data (signal_ctx)
 299  * Returns: 0 on success, -1 on failure
 300  *
 301  * Register a callback function that will be called when a reconfiguration /
 302  * hangup signal is received. The callback function is actually called only
 303  * after the system signal handler has returned. This means that the normal
 304  * limits for sighandlers (i.e., only "safe functions" allowed) do not apply
 305  * for the registered callback.
 306  *
 307  * This function is a more portable version of eloop_register_signal() since
 308  * the knowledge of exact details of the signals is hidden in eloop
 309  * implementation. In case of operating systems using signal(), this function
 310  * registers a handler for SIGHUP.
 311  */
 312 int eloop_register_signal_reconfig(eloop_signal_handler handler,
 313                                    void *user_data);
 314
 315 /**
 316  * eloop_run - Start the event loop
 317  *
 318  * Start the event loop and continue running as long as there are any
 319  * registered event handlers. This function is run after event loop has been
 320  * initialized with event_init() and one or more events have been registered.
 321  */
 322 void eloop_run(void);
 323
 324 /**
 325  * eloop_terminate - Terminate event loop
 326  *
 327  * Terminate event loop even if there are registered events. This can be used
 328  * to request the program to be terminated cleanly.
 329  */
 330 void eloop_terminate(void);
 331
 332 /**
 333  * eloop_destroy - Free any resources allocated for the event loop
 334  *
 335  * After calling eloop_destroy(), other eloop_* functions must not be called
 336  * before re-running eloop_init().
 337  */
 338 void eloop_destroy(void);
 339
 340 /**
 341  * eloop_terminated - Check whether event loop has been terminated
 342  * Returns: 1 = event loop terminate, 0 = event loop still running
 343  *
 344  * This function can be used to check whether eloop_terminate() has been called
 345  * to request termination of the event loop. This is normally used to abort
 346  * operations that may still be queued to be run when eloop_terminate() was
 347  * called.
 348  */
 349 int eloop_terminated(void);
 350
 351 /**
 352  * eloop_wait_for_read_sock - Wait for a single reader
 353  * @sock: File descriptor number for the socket
 354  *
 355  * Do a blocking wait for a single read socket.
 356  */
 357 void eloop_wait_for_read_sock(int sock);
 358
 359 #endif /* ELOOP_H */