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  * @user_ctx: Registered callback context data (user_data)
49  */
50 typedef void (*eloop_event_handler)(void *eloop_ctx, void *user_ctx);
51 
52 /**
53  * eloop_timeout_handler - eloop timeout event callback type
54  * @eloop_ctx: Registered callback context data (eloop_data)
55  * @user_ctx: Registered callback context data (user_data)
56  */
57 typedef void (*eloop_timeout_handler)(void *eloop_ctx, 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