3 * Copyright (c) 2002-2006, Jouni Malinen <j@w1.fi>
5 * This software may be distributed under the terms of the BSD license.
6 * See README for more details.
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
26 * ELOOP_ALL_CTX - eloop_cancel_timeout() magic number to match all timeouts
28 #define ELOOP_ALL_CTX (void *) -1
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
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)
48 typedef void (*eloop_sock_handler)(int sock, void *eloop_ctx, void *sock_ctx);
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)
55 typedef void (*eloop_event_handler)(void *eloop_data, void *user_ctx);
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)
62 typedef void (*eloop_timeout_handler)(void *eloop_data, void *user_ctx);
65 * eloop_signal_handler - eloop signal event callback type
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)
71 typedef void (*eloop_signal_handler)(int sig, void *signal_ctx);
74 * eloop_init() - Initialize global event loop data
75 * Returns: 0 on success, -1 on failure
77 * This function must be called before any other eloop_* function.
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
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
95 int eloop_register_read_sock(int sock, eloop_sock_handler handler,
96 void *eloop_data, void *user_data);
99 * eloop_unregister_read_sock - Unregister handler for read events
100 * @sock: File descriptor number for the socket
102 * Unregister a read socket notifier that was previously registered with
103 * eloop_register_read_sock().
105 void eloop_unregister_read_sock(int sock);
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
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.
122 int eloop_register_sock(int sock, eloop_event_type type,
123 eloop_sock_handler handler,
124 void *eloop_data, void *user_data);
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
131 * Unregister a socket event notifier that was previously registered with
132 * eloop_register_sock().
134 void eloop_unregister_sock(int sock, eloop_event_type type);
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
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.
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),
158 int eloop_register_event(void *event, size_t event_size,
159 eloop_event_handler handler,
160 void *eloop_data, void *user_data);
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
167 * Unregister a generic event notifier that was previously registered with
168 * eloop_register_event().
170 void eloop_unregister_event(void *event, size_t event_size);
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
181 * Register a timeout that will cause the handler function to be called after
184 int eloop_register_timeout(unsigned int secs, unsigned int usecs,
185 eloop_timeout_handler handler,
186 void *eloop_data, void *user_data);
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
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.
199 int eloop_cancel_timeout(eloop_timeout_handler handler,
200 void *eloop_data, void *user_data);
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
210 * Cancel matching <handler,eloop_data,user_data> timeout registered with
211 * eloop_register_timeout() and return the remaining time left.
213 int eloop_cancel_timeout_one(eloop_timeout_handler handler,
214 void *eloop_data, void *user_data,
215 struct os_reltime *remaining);
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
224 * Determine if a matching <handler,eloop_data,user_data> timeout is registered
225 * with eloop_register_timeout().
227 int eloop_is_timeout_registered(eloop_timeout_handler handler,
228 void *eloop_data, void *user_data);
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
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.
243 int eloop_deplete_timeout(unsigned int req_secs, unsigned int req_usecs,
244 eloop_timeout_handler handler, void *eloop_data,
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
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.
260 int eloop_replenish_timeout(unsigned int req_secs, unsigned int req_usecs,
261 eloop_timeout_handler handler, void *eloop_data,
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
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
277 int eloop_register_signal(int sig, eloop_signal_handler handler,
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
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.
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.
297 int eloop_register_signal_terminate(eloop_signal_handler handler,
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
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.
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.
317 int eloop_register_signal_reconfig(eloop_signal_handler handler,
321 * eloop_run - Start the event loop
323 * Start the event loop and continue running as long as there are any
324 * registered event handlers. This function is run after event loop has been
325 * initialized with event_init() and one or more events have been registered.
327 void eloop_run(void);
330 * eloop_terminate - Terminate event loop
332 * Terminate event loop even if there are registered events. This can be used
333 * to request the program to be terminated cleanly.
335 void eloop_terminate(void);
338 * eloop_destroy - Free any resources allocated for the event loop
340 * After calling eloop_destroy(), other eloop_* functions must not be called
341 * before re-running eloop_init().
343 void eloop_destroy(void);
346 * eloop_terminated - Check whether event loop has been terminated
347 * Returns: 1 = event loop terminate, 0 = event loop still running
349 * This function can be used to check whether eloop_terminate() has been called
350 * to request termination of the event loop. This is normally used to abort
351 * operations that may still be queued to be run when eloop_terminate() was
354 int eloop_terminated(void);
357 * eloop_wait_for_read_sock - Wait for a single reader
358 * @sock: File descriptor number for the socket
360 * Do a blocking wait for a single read socket.
362 void eloop_wait_for_read_sock(int sock);