sched.h

   1 /* Copyright (C) 2006 Andre Noll <maan@tuebingen.mpg.de>, see file COPYING. */
   2
   3 /** \file sched.h Sched and task structures and exported symbols from sched.c. */
   4
   5
   6 /**
   7  * Paraslash's scheduler.
   8  *
   9  * Designed with KISS in mind. It maintains a list of task structures which is
  10  * extended when a new task is registered. Each task may define a pre_monitor
  11  * function which is called from the scheduler main loop before it calls
  12  * poll(2). Similarly, each task must define a post_monitor function which is
  13  * called after poll(2) returns.
  14  *
  15  * \sa select(2), poll(2).
  16  */
  17 struct sched {
  18         /** Initial value (in milliseconds) before any pre_monitor call. */
  19         int default_timeout;
  20         /** The timeout (also in milliseconds) for the next iteration. */
  21         int timeout;
  22         /** Passed to poll(2). */
  23         struct pollfd *pfd;
  24         /** Number of elements in the above array, passed to poll(2). */
  25         unsigned pfd_array_len;
  26         /** Number of fds registered for montitoring so far. */
  27         unsigned num_pfds;
  28         /** Maps fds to indices of the pfd array. */
  29         unsigned *pidx;
  30         /** Mumber of elements in the above pidx array. */
  31         unsigned pidx_array_len;
  32         /** If non-NULL, use this function instead of \ref xpoll(). */
  33         int (*poll_function)(struct pollfd *fds, nfds_t nfds, int timeout);
  34         /** Tasks which have been registered to the scheduler. */
  35         struct list_head task_list;
  36 };
  37
  38 struct task;
  39
  40 /** Information that must be supplied by callers of \ref task_register(). */
  41 struct task_info {
  42         /** Used for log messages and by \ref get_task_list(). */
  43         const char *name;
  44         /**
  45          * Configure watch fds and impose an upper bound on the I/O timeout.
  46          *
  47          * If this is not NULL, the function is called at each iteration of the
  48          * scheduler's main loop. Its purpose is to tell the scheduler that
  49          * certain file descriptors should be monitored for readiness for I/O.
  50          * The function may also lower the scheduler's timeout value (but shall
  51          * never increase it) to impose an upper bound on the waiting time in
  52          * case no file descriptors happen to be ready.
  53          *
  54          * \sa \ref time.c.
  55          */
  56         void (*pre_monitor)(struct sched *s, void *context);
  57         /**
  58          * Perform I/O on file descriptors which are ready for I/O.
  59          *
  60          * This mandatory hook is called after the system call which monitors
  61          * file descriptors returns. The function should perform non-blocking
  62          * I/O on those file descriptors which are reported as being ready.
  63          *
  64          * If this function returns a negative value, the scheduler unregisters
  65          * the task.
  66          */
  67         int (*post_monitor)(struct sched *s, void *context);
  68         /**
  69          * This pointer is saved when the task is registered. It is passed to
  70          * ->pre_monitor() and ->post_monitor(). Usually this is a pointer to the
  71          * struct owned by the caller which contains the task pointer.
  72          */
  73         void *context;
  74 };
  75
  76 /**
  77  * This is set by the scheduler at the beginning of its main loop.  It may be
  78  * used (read-only) from everywhere. As none of the functions called by the
  79  * scheduler are allowed to block, this value should be accurate enough so that
  80  * there is no need to call clock_gettime() directly.
  81  */
  82 extern const struct timeval *now;
  83
  84 struct task *task_register(struct task_info *info, struct sched *s);
  85 int schedule(struct sched *s);
  86 void sched_shutdown(struct sched *s);
  87 char *get_task_list(struct sched *s);
  88 void task_notify(struct task *t, int err);
  89 void task_notify_all(struct sched *s, int err);
  90 int task_get_notification(const struct task *t);
  91 int task_status(const struct task *t);
  92 int task_reap(struct task **tptr);
  93 void sched_min_delay(struct sched *s);
  94 void sched_request_timeout(struct timeval *to, struct sched *s);
  95 void sched_request_timeout_ms(long unsigned ms, struct sched *s);
  96 int sched_request_barrier(struct timeval *barrier, struct sched *s);
  97 int sched_request_barrier_or_min_delay(struct timeval *barrier, struct sched *s);
  98 void sched_monitor_readfd(int fd, struct sched *s);
  99 void sched_monitor_writefd(int fd, struct sched *s);
 100 bool sched_read_ok(int fd, const struct sched *s);
 101 bool sched_write_ok(int fd, const struct sched *s);