2 * UCW Library -- Main Loop
4 * (c) 2004--2011 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"
22 * First of all, let us take a look at the basic operations with main loop contexts.
25 /** The main loop context **/
27 timestamp_t now; /** [*] Current time in milliseconds since the UNIX epoch. See @main_get_time(). **/
28 ucw_time_t now_seconds; /** [*] Current time in seconds since the epoch. **/
29 timestamp_t idle_time; /** [*] Total time in milliseconds spent by waiting for events. **/
30 uns shutdown; /** [*] Setting this to nonzero forces the @main_loop() function to terminate. **/
32 clist file_active_list;
38 #ifdef CONFIG_UCW_EPOLL
39 int epoll_fd; /* File descriptor used for epoll */
40 struct epoll_event *epoll_events;
41 clist file_recalc_list;
43 uns poll_table_obsolete;
44 struct pollfd *poll_table;
45 struct main_file **poll_file_table;
47 struct main_timer **timer_table; /* Growing array containing the heap of timers */
48 sigset_t want_signals;
51 struct main_file *sig_pipe_file;
52 struct main_signal *sigchld_handler;
55 struct main_context *main_new(void); /** Create a new context. **/
58 * Delete a context, assuming it does have any event handlers attached. Does nothing if @m is NULL.
59 * It is allowed to call @main_delete() from a hook function of the same context, but you must
60 * never return to the main loop -- e.g., you can exit() the process instead.
62 void main_delete(struct main_context *m);
65 * Delete a context. If there are any event handlers attached, they are deactivated
66 * (but the responsibility to free the memory there were allocated from lies upon you).
67 * If there are any file handlers, the corresponding file descriptors are closed.
69 void main_destroy(struct main_context *m);
71 /** Switch the current context of the calling thread. Returns the previous current context. **/
72 struct main_context *main_switch_context(struct main_context *m);
74 /** Return the current context. Dies if there is none or if the context has been deleted. **/
75 struct main_context *main_current(void);
77 /** Initialize the main loop module and create a top-level context. **/
80 /** Deinitialize the main loop module, calling @main_delete() on the top-level context. **/
81 void main_cleanup(void);
84 * Deinitialize the main loop module, calling @main_destroy() on the top-level context.
85 * This is especially useful in a freshly forked-off child process.
87 void main_teardown(void);
90 * Start the event loop on the current context.
91 * It will watch the provided objects and call callbacks.
92 * Terminates when someone calls @main_shut_down(),
93 * or when all <<hook,hooks>> return <<enum_main_hook_return,`HOOK_DONE`>>
94 * or at last one <<hook,hook>> returns <<enum_main_hook_return,`HOOK_SHUTDOWN`>>.
98 /** Ask the main loop to terminate at the nearest occasion. **/
99 static inline void main_shut_down(void)
101 main_current()->shutdown = 1;
104 /** Show the current state of a given context (use @main_debug() for the current context). **/
105 void main_debug_context(struct main_context *m);
110 main_debug_context(main_current());
118 * The event loop provides the current time, measured as a 64-bit number
119 * of milliseconds since the system epoch (represented in the type `timestamp_t`).
121 * You can also register timers, which call a handler function at a given moment.
122 * The handler function must either call @timer_del() to delete the timer, or call
123 * @timer_add() with a different expiration time.
127 * Get the current timestamp cached in the current context. It is refreshed in every
128 * iteration of the event loop, or explicitly by calling @main_get_time().
130 static inline timestamp_t main_get_now(void)
132 return main_current()->now;
135 /** An analog of @main_get_now() returning the number of seconds since the system epoch. **/
136 static inline ucw_time_t main_get_now_seconds(void)
138 return main_current()->now_seconds;
142 * This is a description of a timer.
143 * You define the handler function and possibly user-defined data you wish
144 * to pass to the handler, and then you invoke @timer_add().
150 void (*handler)(struct main_timer *tm); /* [*] Function to be called when the timer expires. */
151 void *data; /* [*] Data for use by the handler */
155 * Add a new timer into the main loop to be watched and called
156 * when it expires. It can also be used to modify an already running
157 * timer. It is permitted (and usual) to call this function from the
158 * timer's handler itself if you want the timer to trigger again.
160 * The @expire parameter is absolute, use @timer_add_rel() for a relative version.
162 void timer_add(struct main_timer *tm, timestamp_t expires);
164 /** Like @timer_add(), but the expiration time is relative to the current time. **/
165 void timer_add_rel(struct main_timer *tm, timestamp_t expires_delta);
168 * Removes a timer from the active ones. It is permitted (and common) to call
169 * this function from the timer's handler itself if you want to deactivate
172 void timer_del(struct main_timer *tm);
175 * Forces refresh of the current timestamp cached in the active context.
176 * You usually do not need to call this, since it is called every time the
177 * loop polls for events. It is here if you need extra precision or some of the
178 * hooks takes a long time.
180 void main_get_time(void);
184 * Activity on file descriptors
185 * ----------------------------
187 * You can ask the main loop to watch a set of file descriptors for activity.
188 * (This is a generalization of the select() and poll() system calls. Internally,
189 * it uses either poll() or the more efficient epoll().)
191 * You create a <<struct_main_file,`struct main_file`>>, fill in a file descriptor
192 * and pointers to handler functions to be called when the descriptor becomes
193 * ready for reading and/or writing, and call @file_add(). When you need to
194 * modify the handlers (e.g., to set them to NULL if you are no longer interested
195 * in a given event), you should call @file_chg() to notify the main loop about
198 * From within the handler functions, you are allowed to call @file_chg() and even
201 * The return value of a handler function should be either <<enum_main_hook_return,`HOOK_RETRY`>>
202 * or <<enum_main_hook_return,`HOOK_IDLE`>>. <<enum_main_hook_return,`HOOK_RETRY`>>
203 * signals that the function would like to consume more data immediately
204 * (i.e., it wants to be called again soon, but the event loop can postpone it after
205 * processing other events to avoid starvation). <<enum_main_hook_return,`HOOK_IDLE`>>
206 * tells that the handler wants to be called when the descriptor becomes ready again.
208 * For backward compatibility, 0 can be used instead of <<enum_main_hook_return,`HOOK_IDLE`>>
209 * and 1 for <<enum_main_hook_return,`HOOK_RETRY`>>.
211 * If you want to read/write fixed-size blocks of data asynchronously, the
212 * <<blockio,Asynchronous block I/O>> interface could be more convenient.
216 * This structure describes a file descriptor to be watched and the handlers
217 * to be called when the descriptor is ready for reading and/or writing.
221 int fd; /* [*] File descriptor */
222 int (*read_handler)(struct main_file *fi); /* [*] To be called when ready for reading/writing; must call file_chg() afterwards */
223 int (*write_handler)(struct main_file *fi);
224 void *data; /* [*] Data for use by the handlers */
226 #ifdef CONFIG_UCW_EPOLL
227 uns last_want_events;
229 struct pollfd *pollfd;
234 * Insert a <<struct_main_file,`main_file`>> structure into the main loop to be
235 * watched for activity. You can call this at any time, even inside a handler
236 * (of course for a different file descriptor than the one of the handler).
238 * The file descriptor is automatically set to the non-blocking mode.
240 void file_add(struct main_file *fi);
242 * Tell the main loop that the file structure has changed. Call it whenever you
243 * change any of the handlers.
245 * Can be called only on active files (only the ones added by @file_add()).
247 void file_chg(struct main_file *fi);
249 * Removes a file from the watched set. If you want to close a descriptor,
250 * please use this function first.
252 * Can be called from a handler.
254 void file_del(struct main_file *fi);
258 * Asynchronous block I/O
259 * ----------------------
261 * If you are reading or writing fixed-size blocks of data, you can let the
262 * block I/O interface handle the boring routine of handling partial reads
263 * and writes for you.
265 * You just create <<struct_main_block_io,`struct main_block_io`>> and call
266 * @block_io_add() on it, which sets up some <<struct_main_file,`main_file`>>s internally.
267 * Then you can just call @block_io_read() or @block_io_write() to ask for
268 * reading or writing of a given block. When the operation is finished,
269 * your handler function is called.
271 * Additionally, the block I/O is equipped with a timer, which can be used
272 * to detect communication timeouts. The timer is not touched internally
273 * (except that it gets added and deleted at the right places), feel free
274 * to adjust it from your handler functions by @block_io_set_timeout().
275 * When the timer expires, the error handler is automatically called with
276 * <<enum_block_io_err_cause,`BIO_ERR_TIMEOUT`>>.
279 /** The block I/O structure. **/
280 struct main_block_io {
281 struct main_file file;
282 byte *rbuf; /* Read/write pointers for use by file_read/write */
286 void (*read_done)(struct main_block_io *bio); /* [*] Called when file_read is finished; rpos < rlen if EOF */
287 void (*write_done)(struct main_block_io *bio); /* [*] Called when file_write is finished */
288 void (*error_handler)(struct main_block_io *bio, int cause); /* [*] Handler to call on errors */
289 struct main_timer timer;
290 void *data; /* [*] Data for use by the handlers */
293 /** Activate a block I/O structure. **/
294 void block_io_add(struct main_block_io *bio, int fd);
296 /** Deactivate a block I/O structure. **/
297 void block_io_del(struct main_block_io *bio);
300 * Specifies when or why an error happened. This is passed to the error handler.
301 * `errno` is still set to the original source of error. The only exception
302 * is `BIO_ERR_TIMEOUT`, in which case `errno` is not set and the only possible
303 * cause of it is timeout of the timer associated with the block_io
304 * (see @block_io_set_timeout()).
306 enum block_io_err_cause {
313 * Ask the main loop to read @len bytes of data from @bio into @buf.
314 * It cancels any previous unfinished read requested in this way.
316 * When the read is done, the read_done() handler is called. If an EOF occurred,
317 * `rpos < rlen` (eg. not all data were read).
319 * Can be called from a handler.
321 * You can use a call with zero @len to cancel the current read, but all read data
322 * will be thrown away.
324 void block_io_read(struct main_block_io *bio, void *buf, uns len);
327 * Request that the main loop writes @len bytes of data from @buf to @bio.
328 * Cancels any previous unfinished write and overwrites `write_handler`.
330 * When it is written, the write_done() handler is called.
332 * Can be called from a handler.
334 * If you call it with zero @len, it will cancel the previous write, but note
335 * that some data may already be written.
337 void block_io_write(struct main_block_io *bio, void *buf, uns len);
340 * Sets a timer for a file @bio. If the timer is not overwritten or disabled
341 * until @expires_delta milliseconds, the file timeouts and error_handler() is called with
342 * <<enum_block_io_err_cause,`BIO_ERR_TIMEOUT`>>. A value of `0` stops the timer.
344 * Previous setting of the timeout on the same file will be overwritten.
346 * The use-cases for this are mainly sockets or pipes, when:
348 * - You want to drop inactive connections (no data comes in or out for a given time, not
349 * incomplete messages).
350 * - You want to enforce answer in a given time (for example authentication).
351 * - Watching maximum time for a whole connection.
353 void block_io_set_timeout(struct main_block_io *bio, timestamp_t expires_delta);
360 * The hooks are called whenever the main loop performs an iteration.
361 * You can shutdown the main loop from within them or request an iteration
362 * to happen without sleeping (just poll, no waiting for events).
366 * A hook. It contains the function to call and some user data.
368 * The handler() must return one value from
369 * <<enum_main_hook_return,`main_hook_return`>>.
371 * Fill with the hook and data and pass it to @hook_add().
375 int (*handler)(struct main_hook *ho); /* [*] Hook function; returns HOOK_xxx */
376 void *data; /* [*] For use by the handler */
380 * Return value of the hook handler().
381 * Specifies what should happen next.
383 * - `HOOK_IDLE` -- Let the loop sleep until something happens, call after that.
384 * - `HOOK_RETRY` -- Force the loop to perform another iteration without sleeping.
385 * This will cause calling of all the hooks again soon.
386 * - `HOOK_DONE` -- The loop will terminate if all hooks return this.
387 * - `HOOK_SHUTDOWN` -- Shuts down the loop.
389 * The `HOOK_IDLE` and `HOOK_RETRY` constants are also used as return values
392 enum main_hook_return {
400 * Inserts a new hook into the loop.
401 * The hook will be scheduled at least once before next sleep.
402 * May be called from inside a hook handler too.
404 void hook_add(struct main_hook *ho);
406 * Removes an existing hook from the loop.
407 * May be called from inside a hook handler (to delete itself or other hook).
409 void hook_del(struct main_hook *ho);
416 * The main loop can watch child processes and notify you,
417 * when some of them terminates.
421 * Description of a watched process.
422 * You fill in the handler() and `data`.
423 * The rest is set with @process_fork().
425 struct main_process {
427 int pid; /* Process id (0=not running) */
428 int status; /* Exit status (-1=fork failed) */
429 char status_msg[EXIT_STATUS_MSG_SIZE];
430 void (*handler)(struct main_process *mp); /* [*] Called when the process exits; process_del done automatically */
431 void *data; /* [*] For use by the handler */
435 * Asks the main loop to watch this process.
436 * As it is done automatically in @process_fork(), you need this only
437 * if you removed the process previously by @process_del().
439 void process_add(struct main_process *mp);
441 * Removes the process from the watched set. This is done
442 * automatically, when the process terminates, so you need it only
443 * when you do not want to watch a running process any more.
445 void process_del(struct main_process *mp);
447 * Forks and fills the @mp with information about the new process.
449 * If the fork() succeeds, it:
451 * - Returns 0 in the child.
452 * - Returns 1 in the parent and calls @process_add() on it.
454 * In the case of unsuccessful fork(), it:
456 * - Fills in the `status_msg` and sets `status` to -1.
457 * - Calls the handler() as if the process terminated.
460 int process_fork(struct main_process *mp);
467 void (*handler)(struct main_signal *ms);
471 void signal_add(struct main_signal *ms);
472 void signal_del(struct main_signal *ms);