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