ucw/mainloop.h

   1 /*
   2  *      UCW Library -- Main Loop
   3  *
   4  *      (c) 2004--2005 Martin Mares <mj@ucw.cz>
   5  *
   6  *      This software may be freely distributed and used according to the terms
   7  *      of the GNU Lesser General Public License.
   8  */
   9
  10 #ifndef _UCW_MAINLOOP_H
  11 #define _UCW_MAINLOOP_H
  12
  13 #include "ucw/clists.h"
  14
  15 /***
  16  * [[conventions]]
  17  * Conventions
  18  * -----------
  19  *
  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
  23  * to zeroes.
  24  ***/
  25
  26 /***
  27  * [[time]]
  28  * Time manipulation
  29  * -----------------
  30  *
  31  * This part allows you to get the current time and request
  32  * to have your function called when the time comes.
  33  ***/
  34
  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;
  38
  39 /**
  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().
  43  *
  44  * The handler() function must either call @timer_del() to delete the timer,
  45  * or call @timer_add() with a different expiration time.
  46  **/
  47 struct main_timer {
  48   cnode n;
  49   timestamp_t expires;
  50   void (*handler)(struct main_timer *tm);       /* [*] Function to be called when the timer expires. */
  51   void *data;                                   /* [*] Data for use by the handler */
  52 };
  53
  54 /**
  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.
  59  *
  60  * The @expire parameter is absolute, just add <<var_main_now,`main_now`>> if you need a relative timer.
  61  **/
  62 void timer_add(struct main_timer *tm, timestamp_t expires);
  63 /**
  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
  66  * the timer.
  67  **/
  68 void timer_del(struct main_timer *tm);
  69
  70 /**
  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.
  75  **/
  76 void main_get_time(void);
  77
  78 /***
  79  * [[file]]
  80  * Activity on file descriptors
  81  * ----------------------------
  82  *
  83  * You can let the mainloop watch over a set of file descriptors
  84  * for changes.
  85  *
  86  * //TODO: This probably needs some example how the handlers can be
  87  * //used, describe the use of this part of module.
  88  ***/
  89
  90 struct main_file {
  91   cnode n;
  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 */
  98   uns rpos, rlen;
  99   byte *wbuf;
 100   uns wpos, wlen;
 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;
 105 };
 106
 107 enum main_file_err_cause {
 108   MFERR_READ,
 109   MFERR_WRITE,
 110   MFERR_TIMEOUT
 111 };
 112
 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() */
 120
 121 /***
 122  * [[hooks]]
 123  * Loop hooks
 124  * ----------
 125  *
 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).
 129  ***/
 130
 131 /**
 132  * A hook. It contains the function to call and some user data.
 133  *
 134  * The handler() must return one value from
 135  * <<enum_main_hook_return,`main_hook_return`>>.
 136  **/
 137 struct main_hook {
 138   cnode n;
 139   int (*handler)(struct main_hook *ho);         /* [*] Hook function; returns HOOK_xxx */
 140   void *data;                                   /* [*] For use by the handler */
 141 };
 142
 143 /**
 144  * Return value of the hook handler().
 145  * Specifies what should happen next.
 146  **/
 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 */
 152 };
 153
 154 /**
 155  * Inserts a new hook into the loop.
 156  **/
 157 void hook_add(struct main_hook *ho);
 158 /**
 159  * Removes an existing hook from the loop.
 160  **/
 161 void hook_del(struct main_hook *ho);
 162
 163 /***
 164  * [[process]]
 165  * Child processes
 166  * ---------------
 167  *
 168  * The main loop can watch child processes and notify you,
 169  * when some of them terminates.
 170  ***/
 171
 172 /**
 173  * Description of a watched process.
 174  * You fill in the handler() and `data`.
 175  * The rest is set with @process_fork().
 176  **/
 177 struct main_process {
 178   cnode n;
 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 */
 184 };
 185
 186 /**
 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().
 190  **/
 191 void process_add(struct main_process *mp);
 192 /**
 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.
 196  */
 197 void process_del(struct main_process *mp);
 198 /**
 199  * Forks and fills the @mp with information about the new process.
 200  *
 201  * If the fork() succeeds, it:
 202  *
 203  * - Returns 0 in the child.
 204  * - Returns 1 in the parent and calls @process_add() on it.
 205  *
 206  * In the case of unsuccessful fork(), it:
 207  *
 208  * - Fills in the `status_msg` and sets `status` to -1.
 209  * - Calls the handler() as if the process terminated.
 210  * - Returns 1.
 211  **/
 212 int process_fork(struct main_process *mp);
 213
 214 /***
 215  * [[control]]
 216  * Control of the mainloop
 217  * -----------------------
 218  *
 219  * These functions control the mainloop as a whole.
 220  ***/
 221
 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. **/
 224 /**
 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`>>.
 231  **/
 232 void main_loop(void);
 233 void main_debug(void);                          /** Prints a lot of debug information about current status of the mainloop. **/
 234
 235 #endif