Home | History | Annotate | Download | only in utils
      1 /*
      2  * Event loop
      3  * Copyright (c) 2002-2006, Jouni Malinen <j (at) 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_sock_requeue - Requeue sockets
    317  *
    318  * Requeue sockets after forking because some implementations require this,
    319  * such as epoll and kqueue.
    320  */
    321 int eloop_sock_requeue(void);
    322 
    323 /**
    324  * eloop_run - Start the event loop
    325  *
    326  * Start the event loop and continue running as long as there are any
    327  * registered event handlers. This function is run after event loop has been
    328  * initialized with event_init() and one or more events have been registered.
    329  */
    330 void eloop_run(void);
    331 
    332 /**
    333  * eloop_terminate - Terminate event loop
    334  *
    335  * Terminate event loop even if there are registered events. This can be used
    336  * to request the program to be terminated cleanly.
    337  */
    338 void eloop_terminate(void);
    339 
    340 /**
    341  * eloop_destroy - Free any resources allocated for the event loop
    342  *
    343  * After calling eloop_destroy(), other eloop_* functions must not be called
    344  * before re-running eloop_init().
    345  */
    346 void eloop_destroy(void);
    347 
    348 /**
    349  * eloop_terminated - Check whether event loop has been terminated
    350  * Returns: 1 = event loop terminate, 0 = event loop still running
    351  *
    352  * This function can be used to check whether eloop_terminate() has been called
    353  * to request termination of the event loop. This is normally used to abort
    354  * operations that may still be queued to be run when eloop_terminate() was
    355  * called.
    356  */
    357 int eloop_terminated(void);
    358 
    359 /**
    360  * eloop_wait_for_read_sock - Wait for a single reader
    361  * @sock: File descriptor number for the socket
    362  *
    363  * Do a blocking wait for a single read socket.
    364  */
    365 void eloop_wait_for_read_sock(int sock);
    366 
    367 #endif /* ELOOP_H */
    368