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  * select(). Similarly, each task must define a post_monitor function which is
  13  * called after the select call.
  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 select call. */
  21         int timeout;
  22         /** fds that should be watched for readability. */
  23         fd_set rfds;
  24         /** fds that should be watched for writability. */
  25         fd_set wfds;
  26         /** Highest numbered file descriptor in any of the above fd sets. */
  27         int max_fileno;
  28         /** If non-NULL, use this function instead of para_select. */
  29         int (*select_function)(int, fd_set *, fd_set *, int timeout);
  30         /** Tasks which have been registered to the scheduler. */
  31         struct list_head task_list;
  32 };
  33
  34 struct task;
  35
  36 /** Information that must be supplied by callers of \ref task_register(). */
  37 struct task_info {
  38         /** Used for log messages and by \ref get_task_list(). */
  39         const char *name;
  40         /**
  41          * Configure watch fds and impose an upper bound on the I/O timeout.
  42          *
  43          * If this is not NULL, the function is called at each iteration of the
  44          * scheduler's main loop. Its purpose is to tell the scheduler that
  45          * certain file descriptors should be monitored for readiness for I/O.
  46          * The function may also lower the scheduler's timeout value (but shall
  47          * never increase it) to impose an upper bound on the waiting time in
  48          * case no file descriptors happen to be ready.
  49          *
  50          * \sa \ref time.c.
  51          */
  52         void (*pre_monitor)(struct sched *s, void *context);
  53         /**
  54          * Perform I/O on file descriptors which are ready for I/O.
  55          *
  56          * This mandatory hook is called after the system call which monitors
  57          * file descriptors returns. The function should perform non-blocking
  58          * I/O on those file descriptors which are reported as being ready.
  59          *
  60          * If this function returns a negative value, the scheduler unregisters
  61          * the task.
  62          */
  63         int (*post_monitor)(struct sched *s, void *context);
  64         /**
  65          * This pointer is saved when the task is registered. It is passed to
  66          * ->pre_monitor() and ->post_monitor(). Usually this is a pointer to the
  67          * struct owned by the caller which contains the task pointer.
  68          */
  69         void *context;
  70 };
  71
  72 /**
  73  * This is set by the scheduler at the beginning of its main loop.  It may be
  74  * used (read-only) from everywhere. As none of the functions called by the
  75  * scheduler are allowed to block, this value should be accurate enough so that
  76  * there is no need to call clock_gettime() directly.
  77  */
  78 extern const struct timeval *now;
  79
  80 struct task *task_register(struct task_info *info, struct sched *s);
  81 int schedule(struct sched *s);
  82 void sched_shutdown(struct sched *s);
  83 char *get_task_list(struct sched *s);
  84 void task_notify(struct task *t, int err);
  85 void task_notify_all(struct sched *s, int err);
  86 int task_get_notification(const struct task *t);
  87 int task_status(const struct task *t);
  88 int task_reap(struct task **tptr);
  89 void sched_min_delay(struct sched *s);
  90 void sched_request_timeout(struct timeval *to, struct sched *s);
  91 void sched_request_timeout_ms(long unsigned ms, struct sched *s);
  92 int sched_request_barrier(struct timeval *barrier, struct sched *s);
  93 int sched_request_barrier_or_min_delay(struct timeval *barrier, struct sched *s);
  94 void sched_monitor_readfd(int fd, struct sched *s);
  95 void sched_monitor_writefd(int fd, struct sched *s);
  96
  97 static inline bool sched_read_ok(int fd, const struct sched *s)
  98 {
  99         return FD_ISSET(fd, &s->rfds);
 100 }
 101
 102 static inline bool sched_write_ok(int fd, const struct sched *s)
 103 {
 104         return FD_ISSET(fd, &s->wfds);
 105 }