2 * UCW Library -- Main Loop
4 * (c) 2004--2005 Martin Mares <mj@ucw.cz>
6 * This software may be freely distributed and used according to the terms
7 * of the GNU Lesser General Public License.
10 #ifndef _UCW_MAINLOOP_H
11 #define _UCW_MAINLOOP_H
13 #include "ucw/clists.h"
20 * The descriptions of structures contain some fields marked with `[*]`.
21 * These are the only ones that are intended to be manipulated by the user.
22 * The remaining fields serve for internal use only and you must initialize them
31 * This part allows you to get the current time and request
32 * to have your function called when the time comes.
35 extern timestamp_t main_now; /** Current time in milliseconds since the UNIX epoch. See @main_get_time(). **/
36 extern ucw_time_t main_now_seconds; /** Current time in seconds since the epoch. **/
37 extern clist main_timer_list, main_file_list, main_hook_list, main_process_list;
40 * This is a description of a timer.
41 * You fill in a handler function, any user-defined data you wish to pass
42 * to the handler, and then you invoke @timer_add().
44 * The handler() function must either call @timer_del() to delete the timer,
45 * or call @timer_add() with a different expiration time.
50 void (*handler)(struct main_timer *tm); /* [*] Function to be called when the timer expires. */
51 void *data; /* [*] Data for use by the handler */
55 * Adds a new timer into the mainloop to be watched and called
56 * when it expires. It can also be used to modify an already running
57 * timer. It is permitted (and usual) to call this function from the
58 * timer's handler itself if you want the timer to trigger again.
60 * The @expire parameter is absolute, just add <<var_main_now,`main_now`>> if you need a relative timer.
62 void timer_add(struct main_timer *tm, timestamp_t expires);
64 * Removes a timer from the active ones. It is permitted (and usual) to call
65 * this function from the timer's handler itself if you want to deactivate
68 void timer_del(struct main_timer *tm);
71 * Forces refresh of <<var_main_now,`main_now`>>. You do not usually
72 * need to call this, since it is called every time the loop polls for
73 * changes. It is here if you need extra precision or some of the
74 * hooks takes a long time.
76 void main_get_time(void);
80 * Activity on file descriptors
81 * ----------------------------
83 * You can let the mainloop watch over a set of file descriptors
86 * //TODO: This probably needs some example how the handlers can be
87 * //used, describe the use of this part of module.
92 int fd; /* [*] File descriptor */
93 int (*read_handler)(struct main_file *fi); /* [*] To be called when ready for reading/writing; must call file_chg() afterwards */
94 int (*write_handler)(struct main_file *fi);
95 void (*error_handler)(struct main_file *fi, int cause); /* [*] Handler to call on errors */
96 void *data; /* [*] Data for use by the handlers */
97 byte *rbuf; /* Read/write pointers for use by file_read/write */
101 void (*read_done)(struct main_file *fi); /* [*] Called when file_read is finished; rpos < rlen if EOF */
102 void (*write_done)(struct main_file *fi); /* [*] Called when file_write is finished */
103 struct main_timer timer;
104 struct pollfd *pollfd;
107 enum main_file_err_cause {
113 void file_add(struct main_file *fi);
114 void file_chg(struct main_file *fi);
115 void file_del(struct main_file *fi);
116 void file_read(struct main_file *fi, void *buf, uns len);
117 void file_write(struct main_file *fi, void *buf, uns len);
118 void file_set_timeout(struct main_file *fi, timestamp_t expires);
119 void file_close_all(void); /* Close all known main_file's; frequently used after fork() */
126 * The hooks can be called whenever the mainloop perform an iteration.
127 * You can shutdown the mainloop from within them or request next call
128 * only when the loop is idle (for background operations).
132 * A hook. It contains the function to call and some user data.
134 * The handler() must return one value from
135 * <<enum_main_hook_return,`main_hook_return`>>.
139 int (*handler)(struct main_hook *ho); /* [*] Hook function; returns HOOK_xxx */
140 void *data; /* [*] For use by the handler */
144 * Return value of the hook handler().
145 * Specifies what should happen next.
147 enum main_hook_return {
148 HOOK_IDLE, /* Call again when the main loop becomes idle again */
149 HOOK_RETRY, /* Call again as soon as possible */
150 HOOK_DONE = -1, /* Shut down the main loop if all hooks return this value */
151 HOOK_SHUTDOWN = -2 /* Shut down the main loop immediately */
155 * Inserts a new hook into the loop.
157 void hook_add(struct main_hook *ho);
159 * Removes an existing hook from the loop.
161 void hook_del(struct main_hook *ho);
168 * The main loop can watch child processes and notify you,
169 * when some of them terminates.
173 * Description of a watched process.
174 * You fill in the handler() and `data`.
175 * The rest is set with @process_fork().
177 struct main_process {
179 int pid; /* Process id (0=not running) */
180 int status; /* Exit status (-1=fork failed) */
181 char status_msg[EXIT_STATUS_MSG_SIZE];
182 void (*handler)(struct main_process *mp); /* [*] Called when the process exits; process_del done automatically */
183 void *data; /* [*] For use by the handler */
187 * Asks the mainloop to watch this process.
188 * As it is done automatically in @process_fork(), you need this only
189 * if you removed the process previously by @process_del().
191 void process_add(struct main_process *mp);
193 * Removes the process from the watched set. This is done
194 * automatically, when the process terminates, so you need it only
195 * when you do not want to watch a running process any more.
197 void process_del(struct main_process *mp);
199 * Forks and fills the @mp with information about the new process.
201 * If the fork() succeeds, it:
203 * - Returns 0 in the child.
204 * - Returns 1 in the parent and calls @process_add() on it.
206 * In the case of unsuccessful fork(), it:
208 * - Fills in the `status_msg` and sets `status` to -1.
209 * - Calls the handler() as if the process terminated.
212 int process_fork(struct main_process *mp);
216 * Control of the mainloop
217 * -----------------------
219 * These functions control the mainloop as a whole.
222 extern uns main_shutdown; /** Setting this to nonzero forces the @main_loop() function to terminate. **/
223 void main_init(void); /** Initializes the mainloop structures. Call before any `*_add` function. **/
225 * Start the mainloop.
226 * It will watch the provided objects and call callbacks.
227 * Terminates when someone sets <<var_main_shutdown,`main_shutdown`>>
228 * to nonzero, when all <<hook,hooks>> return
229 * <<enum_main_hook_return,`HOOK_DONE`>> or at last one <<hook,hook>>
230 * returns <<enum_main_hook_return,`HOOK_SHUTDOWN`>>.
232 void main_loop(void);
233 void main_debug(void); /** Prints a lot of debug information about current status of the mainloop. **/