/* Copyright (C) 2006 Andre Noll <maan@tuebingen.mpg.de>, see file COPYING. */
-/** \file sched.h Sched and task structures and exported symbols from sched.c. */
+/** \file sched.h The paraslash scheduler
+ *
+ * The scheduler maintains a list of task structures where each list element
+ * represents a task that has been registered to the scheduler by calling
+ * \ref task_register(). At each iteration of main loop, the scheduler
+ * calls the pre-monitor functions to set up two file descriptor sets and to
+ * compute the timeout for the subsequent call to poll(2). The post-monitor
+ * functions are called after poll(2) returns. They are supposed to perform
+ * read/write operations if the poll(2) call indicated that the file descriptor
+ * is ready for I/O.
+ *
+ * Inter-task communication is possible through a notification API also
+ * described here.
+ *
+ * The functions declared here are implemented in \ref sched.c. All paraslash
+ * executables employ the scheduler.
+ */
- /** Describes a scheduler instance. */
- struct sched {
- /** Initial value (in milliseconds) before any pre_monitor call. */
- int default_timeout;
- /** The timeout (also in milliseconds) for the next iteration. */
- int timeout;
- /** Passed to poll(2). */
- struct pollfd *pfd;
- /** Number of elements in the above array, passed to poll(2). */
- unsigned pfd_array_len;
- /** Number of fds registered for monitoring so far. */
- unsigned num_pfds;
- /** Maps fds to indices of the pfd array. */
- unsigned *pidx;
- /** Number of elements in the above pidx array. */
- unsigned pidx_array_len;
- /** If non-NULL, use this function instead of \ref xpoll(). */
- int (*poll_function)(struct pollfd *fds, nfds_t nfds, int timeout);
- /** Tasks which have been registered to the scheduler. */
- struct list_head task_list;
- };
+ struct sched;
-/** Information that must be supplied by callers of \ref task_register(). */
+/**
+ * Information that must be supplied by callers of \ref task_register().
+ *
+ * The structure may be safely discarded after the task has been registered.
+ */
struct task_info {
/** Used for log messages and by \ref get_task_list(). */
const char *name;