doxify missing bits

This makes the documentation complete again.

diff --git a/sched.c b/sched.c
index c5b2c5ea1b4badf8b5f2e02fe94a03c9cdb6421f..6b893d33c9ccb2b07c65fcb8fd02ac168d7bc6f8 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 <sys/time.h>
 #include "para.h"
 #include "ipc.h"


@@ -7,10 +27,16 @@
 #include "string.h"
 #include "error.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;
 
 static struct timeval now_struct;

+

 struct timeval *now = &now_struct;
 
 static void sched_preselect(struct sched *s)
 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)
 {
 
 int sched(struct sched *s)
 {
 


@@ -63,7 +102,17 @@ again:
        goto 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) {
 {
        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);
        }
                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);
 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);
 };
 
                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);
 };
 
 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;
 void sched_shutdown(void)
 {
        struct task *t, *tmp;


@@ -103,6 +168,15 @@ void sched_shutdown(void)
                unregister_task(t);
 };
 
                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;
 char *get_task_list(void)
 {
        struct task *t, *tmp;


@@ -125,6 +199,17 @@ char *get_task_list(void)
        return msg;
 }
 
        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;
 int kill_task(char *id)
 {
        struct task *t, *tmp;

diff --git a/sched.h b/sched.h
index 8a6ed1a80fb9fca7493f311bbf9116234c19bdb3..ebd38a8ceb8dbf8cfbe7a6fe6982f8baeaa37845 100644 (file)
--- a/sched.h
+++ b/sched.h
@@ -16,7 +16,7 @@
  *     Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111, USA.
  */
 
  *     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.
  *
  * 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
  * 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;
 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);
        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);
        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;
        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;
 
  */
 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);
 void unregister_task(struct task *t);
 int sched(struct sched *s);
 void init_sched(void);

diff --git a/stdin.c b/stdin.c
index b86fbbb9a635448a10f6375915fa6620bfb9fc1d..cb13250e269874399eb6892eac73242d80adc0ac 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
  * \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)
  * 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
  *
  * \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.
  */
  * 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 a36b98879fd5c6c17b10140dda4ea64175d88964..ee03922e06bd06fe2bc21d4f447a72766fe13e9c 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;
        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;
        int check_fd;
        /** the task structure */
        struct task task;

diff --git a/stdout.c b/stdout.c
index 25402b8d259fbecb8e0d9fc7b3fab2d799b07884..1c1435a321dedaf445b39a0a1ad8791d024d636d 100644 (file)
--- a/stdout.c
+++ b/stdout.c
@@ -26,7 +26,6 @@
 #include "error.h"
 #include "stdout.h"
 
 #include "error.h"
 #include "stdout.h"
 

-

 /**
  * the pre_select function of the stdout task
  *
 /**
  * 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
  * \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)
 {
  */
 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
  *
  * \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.
  */
  * appeears to be writable, the data loaded in the input buffer is written to
  * stdout.
  */

diff --git a/stdout.h b/stdout.h
index 1fe09f1d07e915d4de24fbcb2b7a9af113d65fb8..e8d9d255cf75e8baedef649d750af1b4e909c3ae 100644 (file)
--- a/stdout.h
+++ b/stdout.h
@@ -34,7 +34,7 @@ struct stdout_task {
        int eof;
        /** the task structure */
        struct task 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;
 };
 
        int check_fd;
 };