3 * Copyright (c) 2002-2005, Jouni Malinen <jkmaline@cc.hut.fi>
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.
9 * Alternatively, this software may be distributed under the terms of BSD
12 * See README and COPYING for more details.
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
26 /* Magic number for eloop_cancel_timeout() */
27 #define ELOOP_ALL_CTX (void *) -1
30 * eloop_init() - Initialize global event loop data
31 * @user_data: Pointer to global data passed as eloop_ctx to signal handlers
33 * This function must be called before any other eloop_* function. user_data
34 * can be used to configure a global (to the process) pointer that will be
35 * passed as eloop_ctx parameter to signal handlers.
37 void eloop_init(void *user_data);
40 * eloop_register_read_sock - Register handler for read events
41 * @sock: File descriptor number for the socket
42 * @handler: Callback function to be called when data is available for reading
43 * @eloop_data: Callback context data (eloop_ctx)
44 * @user_data: Callback context data (sock_ctx)
45 * Returns: 0 on success, -1 on failure
47 * Register a read socket notifier for the given file descriptor. The handler
48 * function will be called whenever data is available for reading from the
51 int eloop_register_read_sock(int sock,
52 void (*handler)(int sock, void *eloop_ctx,
54 void *eloop_data, void *user_data);
57 * eloop_unregister_read_sock - Unregister handler for read events
58 * @sock: File descriptor number for the socket
60 * Unregister a read socket notifier that was previously registered with
61 * eloop_register_read_sock().
63 void eloop_unregister_read_sock(int sock);
66 * eloop_register_timeout - Register timeout
67 * @secs: Number of seconds to the timeout
68 * @usecs: Number of microseconds to the timeout
69 * @handler: Callback function to be called when timeout occurs
70 * @eloop_data: Callback context data (eloop_ctx)
71 * @user_data: Callback context data (sock_ctx)
72 * Returns: 0 on success, -1 on failure
74 * Register a timeout that will cause the handler function to be called after
77 int eloop_register_timeout(unsigned int secs, unsigned int usecs,
78 void (*handler)(void *eloop_ctx, void *timeout_ctx),
79 void *eloop_data, void *user_data);
82 * eloop_cancel_timeout - Cancel timeouts
83 * @handler: Matching callback function
84 * @eloop_data: Matching eloop_data or %ELOOP_ALL_CTX to match all
85 * @user_data: Matching user_data or %ELOOP_ALL_CTX to match all
86 * Returns: Number of cancelled timeouts
88 * Cancel matching <handler,eloop_data,user_data> timeouts registered with
89 * eloop_register_timeout(). ELOOP_ALL_CTX can be used as a wildcard for
90 * cancelling all timeouts regardless of eloop_data/user_data.
92 int eloop_cancel_timeout(void (*handler)(void *eloop_ctx, void *sock_ctx),
93 void *eloop_data, void *user_data);
96 * eloop_register_signal - Register handler for signals
97 * @sig: Signal number (e.g., SIGHUP)
98 * @handler: Callback function to be called when the signal is received
99 * @user_data: Callback context data (signal_ctx)
100 * Returns: 0 on success, -1 on failure
102 * Register a callback function that will be called when a signal is received.
103 * The calback function is actually called only after the system signal handler
104 * has returned. This means that the normal limits for sighandlers (i.e., only
105 * "safe functions" allowed) do not apply for the registered callback.
107 * Signals are 'global' events and there is no local eloop_data pointer like
108 * with other handlers. The global user_data pointer registered with
109 * eloop_init() will be used as eloop_ctx for signal handlers.
111 int eloop_register_signal(int sig,
112 void (*handler)(int sig, void *eloop_ctx,
117 * eloop_run - Start the event loop
119 * Start the event loop and continue running as long as there are any
120 * registered event handlers. This function is run after event loop has been
121 * initialized with event_init() and one or more events have been registered.
123 void eloop_run(void);
126 * eloop_terminate - Terminate event loop
128 * Terminate event loop even if there are registered events. This can be used
129 * to request the program to be terminated cleanly.
131 void eloop_terminate(void);
134 * eloop_destroy - Free any resources allocated for the event loop
136 * After calling eloop_destoy(), other eloop_* functions must not be called
137 * before re-running eloop_init().
139 void eloop_destroy(void);
142 * eloop_terminated - Check whether event loop has been terminated
143 * Returns: 1 = event loop terminate, 0 = event loop still running
145 * This function can be used to check whether eloop_terminate() has been called
146 * to request termination of the event loop. This is normally used to abort
147 * operations that may still be queued to be run when eloop_terminate() was
150 int eloop_terminated(void);