Consolidate receiver/filter/writer {pre,post}_select() docs.

[paraslash.git] / sched.h

diff --git a/sched.h b/sched.h
index d9e852447ec55c27e4fc77a86185fcaa4a68bd06..f89b89ffc012551e17febc9de463882eb5c678b6 100644 (file)
--- a/sched.h
+++ b/sched.h
@@ -11,6 +11,8 @@
  * function which is called from the scheduler main loop before it calls
  * select(). Similarly, each task must define a post_select function which is
  * called after the select call.
+ *
+ * \sa select(2), poll(2).
  */
 struct sched {
        /** Initial value (in milliseconds) before any pre_select call. */
@@ -36,18 +38,27 @@ struct task_info {
        /** Used for log messages and by \ref get_task_list(). */
        const char *name;
        /**
-        * The optional pre select method.
+        * Configure watch fds and impose an upper bound on the I/O timeout.
+        *
+        * If this is not NULL, the function is called at each iteration of the
+        * scheduler's main loop. Its purpose is to tell the scheduler that
+        * certain file descriptors should be monitored for readiness for I/O.
+        * The function may also lower the scheduler's timeout value (but shall
+        * never increase it) to impose an upper bound on the waiting time in
+        * case no file descriptors happen to be ready.
         *
-        * Its purpose is to add file descriptors to the fd sets of the
-        * scheduler and to decrease the select timeout if necessary.
+        * \sa \ref time.c.
         */
        void (*pre_select)(struct sched *s, void *context);
        /**
-        * The mandatory post select method.
+        * Perform I/O on file descriptors which are ready for I/O.
+        *
+        * This mandatory hook is called after the system call which monitors
+        * file descriptors returns. The function should perform non-blocking
+        * I/O on those file descriptors which are reported as being ready.
         *
-        * Its purpose is to evaluate and act upon the results of the previous
-        * select call. If this function returns a negative value, the
-        * scheduler unregisters the task.
+        * If this function returns a negative value, the scheduler unregisters
+        * the task.
         */
        int (*post_select)(struct sched *s, void *context);
        /**