Merge branch 'maint'
[paraslash.git] / 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);