doxify missing bits
authorAndre <maan@p133.(none)>
Tue, 13 Jun 2006 03:15:52 +0000 (05:15 +0200)
committerAndre <maan@p133.(none)>
Tue, 13 Jun 2006 03:15:52 +0000 (05:15 +0200)
This makes the documentation complete again.

sched.c
sched.h
stdin.c
stdin.h
stdout.c
stdout.h

diff --git a/sched.c b/sched.c
index c5b2c5e..6b893d3 100644 (file)
--- a/sched.c
+++ b/sched.c
@@ -1,3 +1,23 @@
+/*
+ * Copyright (C) 2006 Andre Noll <maan@systemlinux.org>
+ *
+ *     This program is free software; you can redistribute it and/or modify
+ *     it under the terms of the GNU General Public License as published by
+ *     the Free Software Foundation; either version 2 of the License, or
+ *     (at your option) any later version.
+ *
+ *     This program is distributed in the hope that it will be useful,
+ *     but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *     GNU General Public License for more details.
+ *
+ *     You should have received a copy of the GNU General Public License
+ *     along with this program; if not, write to the Free Software
+ *     Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111, USA.
+ */
+
+/** \file sched.c paraslash's scheduling functions */
+
 #include <sys/time.h>
 #include "para.h"
 #include "ipc.h"
 #include "string.h"
 #include "error.h"
 
-struct list_head pre_select_list;
-struct list_head post_select_list;
+/**
+ * The scheduler manages two lists of tasks.  The pre_select list contains
+ * pointers to functions that are called before calling select() from the main
+ * loop. Similarly, \a post_select_list is a list of function pointers each of
+ * which is called after the select call.
+ */
+struct list_head pre_select_list, post_select_list;
 
 static struct timeval now_struct;
+
 struct timeval *now = &now_struct;
 
 static void sched_preselect(struct sched *s)
@@ -42,6 +68,19 @@ static void sched_post_select(struct sched *s)
        }
 }
 
+/**
+ * the core function for all paraslash programs
+ *
+ * Short and sweet. It updates the global \a now pointer, calls all registered
+ * pre_select hooks which may set the timeout and add any file descriptors to
+ * the fd sets of \a s.  Next, it calls para_select() and makes the result available
+ * to the registered tasks by calling their post_select hook.
+ *
+ * \return Zero if no more tasks are left in either of the two lists, negative
+ * if para_select returned an error.
+ *
+ * \sa task, now.
+ */
 int sched(struct sched *s)
 {
 
@@ -63,7 +102,17 @@ again:
        goto again;
 }
 
-void *register_task(struct task *t)
+/**
+ * add a task to the scheduler
+ *
+ * \param t the task to add
+ *
+ * If the pre_select pointer of \a t is not \p NULL, it is added to
+ * the pre_select list of the scheduler. Same goes for post_select.
+ *
+ * \sa task::pre_select, task::post_select
+ */
+void register_task(struct task *t)
 {
        PARA_INFO_LOG("registering %s (%p)\n", t->status, t);
        if (t->pre_select) {
@@ -74,9 +123,16 @@ void *register_task(struct task *t)
                PARA_DEBUG_LOG("post_select: %p\n", &t->pre_select);
                list_add(&t->post_select_node, &post_select_list);
        }
-       return t;
 }
 
+/**
+ * remove a task from the scheduler
+ *
+ * \param t the task to remove
+ *
+ * If the pre_select pointer of \a t is not \p NULL, it is removed from
+ * the pre_select list of the scheduler. Same goes for \a post_select.
+ */
 void unregister_task(struct task *t)
 {
        PARA_INFO_LOG("unregistering %s (%p)\n", t->status, t);
@@ -86,12 +142,21 @@ void unregister_task(struct task *t)
                list_del(&t->post_select_node);
 };
 
+/**
+ * initialize the paraslash scheduler
+ */
 void init_sched(void)
 {
        INIT_LIST_HEAD(&pre_select_list);
        INIT_LIST_HEAD(&post_select_list);
 };
 
+/**
+ * unregister all tasks
+ *
+ * This will cause \a sched() to return immediately because both the
+ * \a pre_select_list and the \a post_select_list are empty.
+ */
 void sched_shutdown(void)
 {
        struct task *t, *tmp;
@@ -103,6 +168,15 @@ void sched_shutdown(void)
                unregister_task(t);
 };
 
+/**
+ * get the list of all registered tasks.
+ *
+ * \return the task list
+ *
+ * Each entry of the list contains an identifier which is simply a hex number
+ * that may be used in \a kill_task() to terminate the task.
+ * The result ist dynamically allocated and must be freed by the caller.
+ */
 char *get_task_list(void)
 {
        struct task *t, *tmp;
@@ -125,6 +199,17 @@ char *get_task_list(void)
        return msg;
 }
 
+/**
+ * simulate an error for the given task
+ *
+ * \param id the task identifier
+ *
+ * Find the task identified by \a id, set the tasks' return value to
+ * \p -E_TASK_KILLED and call the event handler of the task.
+ *
+ * \return Positive on sucess, negative if \a id does not correspond to a
+ * registered task.
+ */
 int kill_task(char *id)
 {
        struct task *t, *tmp;
diff --git a/sched.h b/sched.h
index 8a6ed1a..ebd38a8 100644 (file)
--- a/sched.h
+++ b/sched.h
@@ -16,7 +16,7 @@
  *     Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111, USA.
  */
 
-/** \file sched.c Paraslash's task and scheduling functions */
+/** \file sched.h sched and task structures and exported symbols from sched.c */
 
 
 /**
@@ -47,13 +47,6 @@ struct sched {
  * before registering a task to the scheduler, the task structure must be
  * filled in properly by the caller.
  *
- * The  pre_select or the post_select pointer, but not both may be NULL.  Once
- * a task is registered, its pre_select and post_select function gets called
- * from the scheduler's mainloop. The purpose of the pre_select loop is to add
- * file descriptors to the fd sets of the scheduler and to decrease the select
- * timeout if neccessary. The post_select function may then evaluate these fd
- * sets and act upon the results.
-
  * If one of these functions return a negative value via \a t->ret the
  * (optional) event_handler gets called (it may also be called in case another
  * event happend). In many cases the only possible event is an error or an eof
@@ -65,11 +58,20 @@ struct sched {
 struct task {
        /** pointer to the struct this task is embedded in */
        void *private_data;
-       /** pre_select hook */
+       /**
+        * the pre select hook of \a t
+        *
+        * Its purpose is to add file descriptors to the fd sets of the
+        * scheduler and to decrease the select timeout if neccessary.
+        */
        void (*pre_select)(struct sched *s, struct task *t);
-       /** post_select hook */
+       /**
+        * the postselect hook of \a t
+        *
+        * evaluate and act upon the results of the previous select call.
+        */
        void (*post_select)(struct sched *s, struct task *t);
-       /** gets called */
+       /** gets called if pre_select or post_select returned an error */
        void (*event_handler)(struct task *t);
        /** pre_select() and post_select store their return value here */
        int ret;
@@ -89,7 +91,7 @@ struct task {
  */
 extern struct timeval *now;
 
-void *register_task(struct task *t);
+void register_task(struct task *t);
 void unregister_task(struct task *t);
 int sched(struct sched *s);
 void init_sched(void);
diff --git a/stdin.c b/stdin.c
index b86fbbb..cb13250 100644 (file)
--- a/stdin.c
+++ b/stdin.c
@@ -33,7 +33,7 @@
  * \param t the task structure of the stdin task
  *
  * This function is always successful. If there is space left in the
- * buffer of the stdin task, it adds \a STDIN_FILENO to the read fd set
+ * buffer of the stdin task, it adds \p STDIN_FILENO to the read fd set
  * of \a s.
  */
 void stdin_pre_select(struct sched *s, struct task *t)
@@ -59,8 +59,8 @@ static void stdin_default_event_handler(struct task *t)
  * \param s the scheduler this task was registered to
  * \param t the task structure of the stdin task
  *
- * This function checks if \a STDIN_FILENO was included by in the read fd set
- * of \a s during the previous pre_select call.  If yes, and STDIN_FILENO
+ * This function checks if \p STDIN_FILENO was included by in the read fd set
+ * of \a s during the previous pre_select call.  If yes, and \p STDIN_FILENO
  * appeears to be readable, data is read from stdin into the buffer of the
  * stdin task.
  */
diff --git a/stdin.h b/stdin.h
index a36b988..ee03922 100644 (file)
--- a/stdin.h
+++ b/stdin.h
@@ -28,7 +28,7 @@ struct stdin_task {
        size_t bufsize;
        /** number of bytes currently loaded in \a buf */
        size_t loaded;
-       /** whether STDIN_FILENO was included in the read fd set */
+       /** whether \p STDIN_FILENO was included in the read fd set */
        int check_fd;
        /** the task structure */
        struct task task;
index 25402b8..1c1435a 100644 (file)
--- a/stdout.c
+++ b/stdout.c
@@ -26,7 +26,6 @@
 #include "error.h"
 #include "stdout.h"
 
-
 /**
  * the pre_select function of the stdout task
  *
@@ -34,7 +33,7 @@
  * \param t the task structure of the stdout task
  *
  * This function is always successful. If there is data available in the input
- * buffer, it adds \a STDOUT_FILENO to the write fd set of \a s.
+ * buffer, it adds \p STDOUT_FILENO to the write fd set of \a s.
  */
 void stdout_pre_select(struct sched *s, struct task *t)
 {
@@ -60,8 +59,8 @@ void stdout_pre_select(struct sched *s, struct task *t)
  * \param s the scheduler this task was registered to
  * \param t the task structure of the stdout task
  *
- * This function checks if \a STDOUT_FILENO was included by in the write fd set
- * of \a s during the previous pre_select call.  If yes, and STDOUT_FILENO
+ * This function checks if \p STDOUT_FILENO was included by in the write fd set
+ * of \a s during the previous pre_select call.  If yes, and \p STDOUT_FILENO
  * appeears to be writable, the data loaded in the input buffer is written to
  * stdout.
  */
index 1fe09f1..e8d9d25 100644 (file)
--- a/stdout.h
+++ b/stdout.h
@@ -34,7 +34,7 @@ struct stdout_task {
        int eof;
        /** the task structure */
        struct task task;
-       /** whether STDOUT_FILENO was included in the write fd set */
+       /** whether \p STDOUT_FILENO was included in the write fd set */
        int check_fd;
 };