src/utils/eloop.h

   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 */