From c075e867311c77dfb7171241597e613290d1f62b Mon Sep 17 00:00:00 2001 From: Andre Date: Tue, 13 Jun 2006 05:15:52 +0200 Subject: [PATCH] doxify missing bits This makes the documentation complete again. --- sched.c | 93 +++++++++++++++++++++++++++++++++++++++++++++++++++++--- sched.h | 26 ++++++++-------- stdin.c | 6 ++-- stdin.h | 2 +- stdout.c | 7 ++--- stdout.h | 2 +- 6 files changed, 111 insertions(+), 25 deletions(-) diff --git a/sched.c b/sched.c index c5b2c5ea..6b893d33 100644 --- a/sched.c +++ b/sched.c @@ -1,3 +1,23 @@ +/* + * Copyright (C) 2006 Andre Noll + * + * 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 #include "para.h" #include "ipc.h" @@ -7,10 +27,16 @@ #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 8a6ed1a8..ebd38a8c 100644 --- 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 b86fbbb9..cb13250e 100644 --- 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 a36b9887..ee03922e 100644 --- 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; diff --git a/stdout.c b/stdout.c index 25402b8d..1c1435a3 100644 --- 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. */ diff --git a/stdout.h b/stdout.h index 1fe09f1d..e8d9d255 100644 --- 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; }; -- 2.39.2