2 * UCW Library -- Main Loop
4 * (c) 2004--2012 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;
39 #ifdef CONFIG_UCW_EPOLL
40 int epoll_fd; /* File descriptor used for epoll */
41 struct epoll_event *epoll_events;
42 clist file_recalc_list;
44 uns poll_table_obsolete;
45 struct pollfd *poll_table;
46 struct main_file **poll_file_table;
48 struct main_timer **timer_table; /* Growing array containing the heap of timers */
49 sigset_t want_signals;
52 struct main_file *sig_pipe_file;
53 struct main_signal *sigchld_handler;
56 struct main_context *main_new(void); /** Create a new context. **/
59 * Delete a context, assuming it does have any event handlers attached. Does nothing if @m is NULL.
60 * It is allowed to call @main_delete() from a hook function of the same context, but you must
61 * never return to the main loop -- e.g., you can exit() the process instead.
63 void main_delete(struct main_context *m);
66 * Delete a context. If there are any event handlers attached, they are deactivated
67 * (but the responsibility to free the memory there were allocated from lies upon you).
68 * If there are any file handlers, the corresponding file descriptors are closed.
70 void main_destroy(struct main_context *m);
72 /** Switch the current context of the calling thread. Returns the previous current context. **/
73 struct main_context *main_switch_context(struct main_context *m);
75 /** Return the current context. Dies if there is none or if the context has been deleted. **/
76 struct main_context *main_current(void);
78 /** Initialize the main loop module and create a top-level context. **/
81 /** Deinitialize the main loop module, calling @main_delete() on the top-level context. **/
82 void main_cleanup(void);
85 * Deinitialize the main loop module, calling @main_destroy() on the top-level context.
86 * This is especially useful in a freshly forked-off child process.
88 void main_teardown(void);
91 * Start the event loop on the current context.
92 * It will watch the provided objects and call callbacks.
93 * Terminates when someone calls @main_shut_down(),
94 * or when all <<hook,hooks>> return <<enum_main_hook_return,`HOOK_DONE`>>
95 * or at last one <<hook,hook>> returns <<enum_main_hook_return,`HOOK_SHUTDOWN`>>.
100 * Perform a single iteration of the main loop.
101 * Check if there are any events ready and process them.
102 * If there are none, do not wait.
104 void main_step(void);
106 /** Ask the main loop to terminate at the nearest occasion. **/
107 static inline void main_shut_down(void)
109 main_current()->shutdown = 1;
113 * Show the current state of a given context (use @main_debug() for the current context).
114 * Available only if LibUCW has been compiled with `CONFIG_DEBUG`.
116 void main_debug_context(struct main_context *m);
121 main_debug_context(main_current());
129 * The event loop provides the current time, measured as a 64-bit number
130 * of milliseconds since the system epoch (represented in the type `timestamp_t`).
132 * You can also register timers, which call a handler function at a given moment.
133 * The handler function must either call @timer_del() to delete the timer, or call
134 * @timer_add() with a different expiration time.
138 * Get the current timestamp cached in the current context. It is refreshed in every
139 * iteration of the event loop, or explicitly by calling @main_get_time().
141 static inline timestamp_t main_get_now(void)
143 return main_current()->now;
146 /** An analog of @main_get_now() returning the number of seconds since the system epoch. **/
147 static inline ucw_time_t main_get_now_seconds(void)
149 return main_current()->now_seconds;
153 * This is a description of a timer.
154 * You define the handler function and possibly user-defined data you wish
155 * to pass to the handler, and then you invoke @timer_add().
161 void (*handler)(struct main_timer *tm); /* [*] Function to be called when the timer expires. */
162 void *data; /* [*] Data for use by the handler */
166 * Add a new timer into the main loop to be watched and called
167 * when it expires. It can also be used to modify an already running
168 * timer. It is permitted (and usual) to call this function from the
169 * timer's handler itself if you want the timer to trigger again.
171 * The @expire parameter is absolute, use @timer_add_rel() for a relative version.
173 void timer_add(struct main_timer *tm, timestamp_t expires);
175 /** Like @timer_add(), but the expiration time is relative to the current time. **/
176 void timer_add_rel(struct main_timer *tm, timestamp_t expires_delta);
179 * Removes a timer from the active ones. It is permitted (and common) to call
180 * this function from the timer's handler itself if you want to deactivate
181 * the timer. Removing an already removed timer does nothing.
183 void timer_del(struct main_timer *tm);
185 /** Tells whether a timer is running. **/
186 static inline int timer_is_active(struct main_timer *tm)
188 return !!tm->expires;
192 * Forces refresh of the current timestamp cached in the active context.
193 * You usually do not need to call this, since it is called every time the
194 * loop polls for events. It is here if you need extra precision or some of the
195 * hooks takes a long time.
197 void main_get_time(void);
199 /** Show current state of a timer. Available only if LibUCW has been compiled with `CONFIG_DEBUG`. **/
200 void timer_debug(struct main_timer *tm);
207 * The hooks are called whenever the main loop performs an iteration.
208 * You can shutdown the main loop from within them or request an iteration
209 * to happen without sleeping (just poll, no waiting for events).
213 * A hook. It contains the function to call and some user data.
215 * The handler() must return one value from
216 * <<enum_main_hook_return,`main_hook_return`>>.
218 * Fill with the hook and data and pass it to @hook_add().
222 int (*handler)(struct main_hook *ho); /* [*] Hook function; returns HOOK_xxx */
223 void *data; /* [*] For use by the handler */
227 * Return value of the hook handler().
228 * Specifies what should happen next.
230 * - `HOOK_IDLE` -- Let the loop sleep until something happens, call after that.
231 * - `HOOK_RETRY` -- Force the loop to perform another iteration without sleeping.
232 * This will cause calling of all the hooks again soon.
233 * - `HOOK_DONE` -- The loop will terminate if all hooks return this.
234 * - `HOOK_SHUTDOWN` -- Shuts down the loop.
236 * The `HOOK_IDLE` and `HOOK_RETRY` constants are also used as return values
239 enum main_hook_return {
247 * Inserts a new hook into the loop.
248 * The hook will be scheduled at least once before next sleep.
249 * May be called from inside a hook handler too.
250 * Adding an already added hook is permitted and if the hook has been run,
251 * it will be run again before next sleep.
253 void hook_add(struct main_hook *ho);
256 * Removes an existing hook from the loop.
257 * May be called from inside a hook handler (to delete itself or another hook).
258 * Removing an already removed hook does nothing.
260 void hook_del(struct main_hook *ho);
262 /** Tells if a hook is active (i.e., added). **/
263 static inline int hook_is_active(struct main_hook *ho)
265 return clist_is_linked(&ho->n);
268 /** Show current state of a hook. Available only if LibUCW has been compiled with `CONFIG_DEBUG`. **/
269 void hook_debug(struct main_hook *ho);
274 * Activity on file descriptors
275 * ----------------------------
277 * You can ask the main loop to watch a set of file descriptors for activity.
278 * (This is a generalization of the select() and poll() system calls. Internally,
279 * it uses either poll() or the more efficient epoll().)
281 * You create a <<struct_main_file,`struct main_file`>>, fill in a file descriptor
282 * and pointers to handler functions to be called when the descriptor becomes
283 * ready for reading and/or writing, and call @file_add(). When you need to
284 * modify the handlers (e.g., to set them to NULL if you are no longer interested
285 * in a given event), you should call @file_chg() to notify the main loop about
288 * From within the handler functions, you are allowed to call @file_chg() and even
291 * The return value of a handler function should be either <<enum_main_hook_return,`HOOK_RETRY`>>
292 * or <<enum_main_hook_return,`HOOK_IDLE`>>. <<enum_main_hook_return,`HOOK_RETRY`>>
293 * signals that the function would like to consume more data immediately
294 * (i.e., it wants to be called again soon, but the event loop can postpone it after
295 * processing other events to avoid starvation). <<enum_main_hook_return,`HOOK_IDLE`>>
296 * tells that the handler wants to be called when the descriptor becomes ready again.
298 * For backward compatibility, 0 can be used instead of <<enum_main_hook_return,`HOOK_IDLE`>>
299 * and 1 for <<enum_main_hook_return,`HOOK_RETRY`>>.
301 * If you want to read/write fixed-size blocks of data asynchronously, the
302 * <<blockio,Asynchronous block I/O>> interface could be more convenient.
306 * This structure describes a file descriptor to be watched and the handlers
307 * to be called when the descriptor is ready for reading and/or writing.
311 int fd; /* [*] File descriptor */
312 int (*read_handler)(struct main_file *fi); /* [*] To be called when ready for reading/writing; must call file_chg() afterwards */
313 int (*write_handler)(struct main_file *fi);
314 void *data; /* [*] Data for use by the handlers */
316 #ifdef CONFIG_UCW_EPOLL
317 uns last_want_events;
319 struct pollfd *pollfd;
324 * Insert a <<struct_main_file,`main_file`>> structure into the main loop to be
325 * watched for activity. You can call this at any time, even inside a handler
326 * (of course for a different file descriptor than the one of the handler).
328 * The file descriptor is automatically set to the non-blocking mode.
330 void file_add(struct main_file *fi);
333 * Tell the main loop that the file structure has changed. Call it whenever you
334 * change any of the handlers.
336 * Can be called only on active files (only the ones added by @file_add()).
338 void file_chg(struct main_file *fi);
341 * Removes a file from the watched set. If you want to close a descriptor,
342 * please use this function first.
344 * Can be called from a handler.
345 * Removing an already removed file does nothing.
347 void file_del(struct main_file *fi);
349 /** Tells if a file is active (i.e., added). **/
350 static inline int file_is_active(struct main_file *fi)
352 return clist_is_linked(&fi->n);
355 /** Show current state of a file. Available only if LibUCW has been compiled with `CONFIG_DEBUG`. **/
356 void file_debug(struct main_file *fi);
360 * Asynchronous block I/O
361 * ----------------------
363 * If you are reading or writing fixed-size blocks of data, you can let the
364 * block I/O interface handle the boring routine of handling partial reads
365 * and writes for you.
367 * You just create <<struct_main_block_io,`struct main_block_io`>> and call
368 * @block_io_add() on it, which sets up some <<struct_main_file,`main_file`>>s internally.
369 * Then you can just call @block_io_read() or @block_io_write() to ask for
370 * reading or writing of a given block. When the operation is finished,
371 * your handler function is called.
373 * Additionally, the block I/O is equipped with a timer, which can be used
374 * to detect communication timeouts. The timer is not touched internally
375 * (except that it gets added and deleted at the right places), feel free
376 * to adjust it from your handler functions by @block_io_set_timeout().
377 * When the timer expires, the error handler is automatically called with
378 * <<enum_block_io_err_cause,`BIO_ERR_TIMEOUT`>>.
381 /** The block I/O structure. **/
382 struct main_block_io {
383 struct main_file file;
384 byte *rbuf; /* Read/write pointers for use by file_read/write */
388 void (*read_done)(struct main_block_io *bio); /* [*] Called when file_read is finished; rpos < rlen if EOF */
389 void (*write_done)(struct main_block_io *bio); /* [*] Called when file_write is finished */
390 void (*error_handler)(struct main_block_io *bio, int cause); /* [*] Handler to call on errors */
391 struct main_timer timer;
392 void *data; /* [*] Data for use by the handlers */
395 /** Activate a block I/O structure. **/
396 void block_io_add(struct main_block_io *bio, int fd);
398 /** Deactivate a block I/O structure. Calling twice is safe. **/
399 void block_io_del(struct main_block_io *bio);
402 * Specifies when or why an error happened. This is passed to the error handler.
403 * `errno` is still set to the original source of error. The only exception
404 * is `BIO_ERR_TIMEOUT`, in which case `errno` is not set and the only possible
405 * cause of it is timeout of the timer associated with the block_io
406 * (see @block_io_set_timeout()).
408 enum block_io_err_cause {
415 * Ask the main loop to read @len bytes of data from @bio into @buf.
416 * It cancels any previous unfinished read requested in this way.
418 * When the read is done, the read_done() handler is called. If an EOF occurred,
419 * `rpos < rlen` (eg. not all data were read).
421 * Can be called from a handler.
423 * You can use a call with zero @len to cancel the current read, but all read data
424 * will be thrown away.
426 void block_io_read(struct main_block_io *bio, void *buf, uns len);
429 * Request that the main loop writes @len bytes of data from @buf to @bio.
430 * Cancels any previous unfinished write and overwrites `write_handler`.
432 * When it is written, the write_done() handler is called.
434 * Can be called from a handler.
436 * If you call it with zero @len, it will cancel the previous write, but note
437 * that some data may already be written.
439 void block_io_write(struct main_block_io *bio, void *buf, uns len);
442 * Sets a timer for a file @bio. If the timer is not overwritten or disabled
443 * until @expires_delta milliseconds, the file timeouts and error_handler() is called with
444 * <<enum_block_io_err_cause,`BIO_ERR_TIMEOUT`>>. A value of `0` stops the timer.
446 * Previous setting of the timeout on the same file will be overwritten.
448 * The use-cases for this are mainly sockets or pipes, when:
450 * - You want to drop inactive connections (no data comes in or out for a given time, not
451 * incomplete messages).
452 * - You want to enforce answer in a given time (for example authentication).
453 * - Watching maximum time for a whole connection.
455 void block_io_set_timeout(struct main_block_io *bio, timestamp_t expires_delta);
457 /** Tells if a @bio is active (i.e., added). **/
458 static inline int block_io_is_active(struct main_block_io *bio)
460 return file_is_active(&bio->file);
465 * Asynchronous record I/O
466 * -----------------------
468 * Record-based I/O is another front-end to the main loop file operations.
469 * Unlike its older cousin `main_block_io`, it is able to process records
470 * of variable length.
472 * To set it up, you create <<struct_main_rec_io,`struct main_rec_io`>> and call
473 * @rec_io_add() on it, which sets up some <<struct_main_file,`main_file`>>s internally.
475 * To read data from the file, call @rec_io_start_read() first. Whenever any data
476 * arrive from the file, they are appended to an internal buffer and the `read_handler`
477 * hook is called. The hook checks if the buffer already contains a complete record.
478 * If it is so, it processes the record and returns the number of bytes consumed.
479 * Otherwise, it returns 0 to tell the buffering machinery that more data are needed.
480 * When the read handler decides to destroy the `main_rec_io`, it must return `~0U`.
482 * On the write side, `main_rec_io` maintains a buffer keeping all data that should
483 * be written to the file. The @rec_io_write() function appends data to this buffer
484 * and it is written on background. A simple flow-control mechanism can be asked
485 * for: when more than `write_throttle_read` data are buffered for writing, reading
486 * is temporarily suspended.
488 * Additionally, the record I/O is equipped with a timer, which can be used
489 * to detect communication timeouts. The timer is not touched internally
490 * (except that it gets added and deleted at the right places), feel free
491 * to adjust it from your handler functions by @rec_io_set_timeout().
493 * All important events are passed to the `notify_handler`: errors when
494 * reading or writing, timeouts, the write buffer becoming empty, ... See
495 * <<enum_rec_io_notify_status,`enum rec_io_notify_status`>> for a complete list.
498 /** The record I/O structure. **/
500 struct main_file file;
502 byte *read_rec_start; /* [*] Start of current record */
503 uns read_avail; /* [*] How much data is available */
504 uns read_prev_avail; /* [*] How much data was available in previous read_handler */
505 uns read_buf_size; /* [*] Read buffer size allocated (can be set before rec_io_add()) */
506 uns read_started; /* Reading requested by user */
507 uns read_running; /* Reading really runs (read_started && not stopped by write_throttle_read) */
508 uns read_rec_max; /* [*] Maximum record size (0=unlimited) */
509 clist busy_write_buffers;
510 clist idle_write_buffers;
511 uns write_buf_size; /* [*] Write buffer size allocated (can be set before rec_io_add()) */
512 uns write_watermark; /* [*] How much data are waiting to be written */
513 uns write_throttle_read; /* [*] If more than write_throttle_read bytes are buffered, stop reading; 0=no stopping */
514 uns (*read_handler)(struct main_rec_io *rio); /* [*] Called whenever more bytes are read; returns 0 (want more) or number of bytes eaten */
515 int (*notify_handler)(struct main_rec_io *rio, int status); /* [*] Called to notify about errors and other events */
516 /* Returns either HOOK_RETRY or HOOK_IDLE. */
517 struct main_timer timer;
518 struct main_hook start_read_hook; /* Used internally to defer rec_io_start_read() */
519 void *data; /* [*] Data for use by the handlers */
522 /** Activate a record I/O structure. **/
523 void rec_io_add(struct main_rec_io *rio, int fd);
525 /** Deactivate a record I/O structure. Calling twice is safe. **/
526 void rec_io_del(struct main_rec_io *rio);
531 * When there were some data in the buffer (e.g., because @rec_io_stop_read()
532 * was called from the `read_handler`), it is processed as if it were read
533 * from the file once again. That is, `read_prev_avail` is reset to 0 and
534 * the `read_handler` is called to process all buffered data.
536 void rec_io_start_read(struct main_rec_io *rio);
538 /** Stop reading. **/
539 void rec_io_stop_read(struct main_rec_io *rio);
541 /** Analogous to @block_io_set_timeout(). **/
542 void rec_io_set_timeout(struct main_rec_io *bio, timestamp_t expires_delta);
544 void rec_io_write(struct main_rec_io *rio, void *data, uns len);
547 * An auxiliary function used for parsing of lines. When called in the @read_handler,
548 * it searches for the end of line character. When a complete line is found, the length
549 * of the line (including the end of line character) is returned. Otherwise, it returns zero.
551 uns rec_io_parse_line(struct main_rec_io *rio);
554 * Specifies what kind of error or other event happened, when the @notify_handler
555 * is called. In case of I/O errors, `errno` is still set.
557 * Upon @RIO_ERR_READ, @RIO_ERR_RECORD_TOO_LARGE and @RIO_EVENT_EOF, reading is stopped
558 * automatically. Upon @RIO_ERR_WRITE, writing is stopped. Upon @RIO_ERR_TIMEOUT, only the
559 * timer is deactivated.
561 * In all cases, the notification handler is allowed to call @rec_io_del(), but it
562 * must return @HOOK_IDLE in such cases.
564 enum rec_io_notify_status {
565 RIO_ERR_READ = -1, /* read() returned an error, errno set */
566 RIO_ERR_WRITE = -2, /* write() returned an error, errno set */
567 RIO_ERR_TIMEOUT = -3, /* A timeout has occurred */
568 RIO_ERR_RECORD_TOO_LARGE = -4, /* Read: read_rec_max has been exceeded */
569 RIO_EVENT_ALL_WRITTEN = 1, /* All buffered data has been written */
570 RIO_EVENT_PART_WRITTEN = 2, /* Some buffered data has been written, but more remains */
571 RIO_EVENT_EOF = 3, /* Read: EOF seen */
574 /** Tells if a @rio is active (i.e., added). **/
575 static inline int rec_io_is_active(struct main_rec_io *rio)
577 return file_is_active(&rio->file);
585 * The main loop can watch child processes and notify you,
586 * when some of them terminates.
590 * Description of a watched process.
591 * You fill in the handler() and `data`.
592 * The rest is set with @process_fork().
594 struct main_process {
596 int pid; /* Process id (0=not running) */
597 int status; /* Exit status (-1=fork failed) */
598 char status_msg[EXIT_STATUS_MSG_SIZE];
599 void (*handler)(struct main_process *mp); /* [*] Called when the process exits; process_del done automatically */
600 void *data; /* [*] For use by the handler */
604 * Asks the main loop to watch this process.
605 * As it is done automatically in @process_fork(), you need this only
606 * if you removed the process previously by @process_del().
608 void process_add(struct main_process *mp);
611 * Removes the process from the watched set. This is done
612 * automatically, when the process terminates, so you need it only
613 * when you do not want to watch a running process any more.
614 * Removing an already removed process does nothing.
616 void process_del(struct main_process *mp);
619 * Forks and fills the @mp with information about the new process.
621 * If the fork() succeeds, it:
623 * - Returns 0 in the child.
624 * - Returns 1 in the parent and calls @process_add() on it.
626 * In the case of unsuccessful fork(), it:
628 * - Fills in the `status_msg` and sets `status` to -1.
629 * - Calls the handler() as if the process terminated.
632 int process_fork(struct main_process *mp);
634 /** Tells if a process is active (i.e., added). **/
635 static inline int process_is_active(struct main_process *mp)
637 return clist_is_linked(&mp->n);
640 /** Show current state of a process. Available only if LibUCW has been compiled with `CONFIG_DEBUG`. **/
641 void process_debug(struct main_process *pr);
645 * Synchronous delivery of signals
646 * -------------------------------
648 * UNIX signals are delivered to processes in an asynchronous way: when a signal
649 * arrives (and it is not blocked), the process is interrupted and the corresponding
650 * signal handler function is called. However, most data structures and even most
651 * system library calls are not safe with respect to interrupts, so most program
652 * using signals contain subtle race conditions and may fail once in a long while.
654 * To avoid this problem, the event loop can be asked for synchronous delivery
655 * of signals. When a signal registered with @signal_add() arrives, it wakes up
656 * the loop (if it is not already awake) and it is processed in the same way
657 * as all other events.
659 * When used in a multi-threaded program, the signals are delivered to the thread
660 * which is currently using the particular main loop context. If the context is not
661 * current in any thread, the signals are blocked.
663 * As usually with UNIX signals, multiple instances of a single signal can be
664 * merged and delivered only once. (Some implementations of the main loop can even
665 * drop a signal completely during very intensive signal traffic, when an internal
666 * signal queue overflows.)
669 /** Description of a signal to catch. **/
672 int signum; /* [*] Signal to catch */
673 void (*handler)(struct main_signal *ms); /* [*] Called when the signal arrives */
674 void *data; /* [*] For use by the handler */
677 /** Request a signal to be caught and delivered synchronously. **/
678 void signal_add(struct main_signal *ms);
680 /** Cancel a request for signal catching. Calling twice is safe. **/
681 void signal_del(struct main_signal *ms);
683 /** Tells if a signal catcher is active (i.e., added). **/
684 static inline int signal_is_active(struct main_signal *ms)
686 return clist_is_linked(&ms->n);
689 /** Show current state of a signal catcher. Available only if LibUCW has been compiled with `CONFIG_DEBUG`. **/
690 void signal_debug(struct main_signal *sg);