From 0c7015a6d8d2b3bf021c216b24d7062cd7375a71 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Wed, 14 Aug 2013 23:43:53 +0000 Subject: -playing with doxygen groups --- src/include/gnunet_scheduler_lib.h | 90 ++++++++++++++++++++------------------ 1 file changed, 47 insertions(+), 43 deletions(-) (limited to 'src/include/gnunet_scheduler_lib.h') diff --git a/src/include/gnunet_scheduler_lib.h b/src/include/gnunet_scheduler_lib.h index c482a000c..110c0ce77 100644 --- a/src/include/gnunet_scheduler_lib.h +++ b/src/include/gnunet_scheduler_lib.h @@ -22,6 +22,8 @@ * @file include/gnunet_scheduler_lib.h * @brief API to schedule computations using continuation passing style * @author Christian Grothoff + * @defgroup scheduler Event loop (scheduler) + * @{ */ #ifndef GNUNET_SCHEDULER_LIB_H @@ -198,29 +200,29 @@ typedef void (*GNUNET_SCHEDULER_Task) (void *cls, /** * Signature of the select function used by the scheduler. - * GNUNET_NETWORK_socket_select matches it. + * #GNUNET_NETWORK_socket_select matches it. * * @param cls closure * @param rfds set of sockets to be checked for readability * @param wfds set of sockets to be checked for writability * @param efds set of sockets to be checked for exceptions * @param timeout relative value when to return - * @return number of selected sockets, GNUNET_SYSERR on error + * @return number of selected sockets, #GNUNET_SYSERR on error */ typedef int (*GNUNET_SCHEDULER_select) (void *cls, - struct GNUNET_NETWORK_FDSet * rfds, - struct GNUNET_NETWORK_FDSet * wfds, - struct GNUNET_NETWORK_FDSet * efds, + struct GNUNET_NETWORK_FDSet *rfds, + struct GNUNET_NETWORK_FDSet *wfds, + struct GNUNET_NETWORK_FDSet *efds, struct GNUNET_TIME_Relative timeout); /** * Initialize and run scheduler. This function will return when all * tasks have completed. On systems with signals, receiving a SIGTERM - * (and other similar signals) will cause "GNUNET_SCHEDULER_shutdown" + * (and other similar signals) will cause #GNUNET_SCHEDULER_shutdown * to be run after the active task is complete. As a result, SIGTERM * causes all active tasks to be scheduled with reason - * "GNUNET_SCHEDULER_REASON_SHUTDOWN". (However, tasks added + * #GNUNET_SCHEDULER_REASON_SHUTDOWN. (However, tasks added * afterwards will execute normally!). Note that any particular * signal will only shut down one scheduler; applications should * always only create a single scheduler. @@ -249,7 +251,7 @@ GNUNET_SCHEDULER_shutdown (void); * dropped (if the decision should be made based on the number of * tasks ready to run). * - * * @param p priority-level to query, use KEEP to query the level + * @param p priority-level to query, use KEEP to query the level * of the current task, use COUNT to get the sum over * all priority levels * @return number of tasks pending right now @@ -263,7 +265,7 @@ GNUNET_SCHEDULER_get_load (enum GNUNET_SCHEDULER_Priority p); * started. Will return the same value as * the GNUNET_SCHEDULER_TaskContext's reason field. * - * * @return reason(s) why the current task is run + * @return reason(s) why the current task is run */ enum GNUNET_SCHEDULER_Reason GNUNET_SCHEDULER_get_reason (void); @@ -273,7 +275,7 @@ GNUNET_SCHEDULER_get_reason (void); * Cancel the task with the specified identifier. * The task must not yet have run. * - * * @param task id of the task to cancel + * @param task id of the task to cancel * @return the closure of the callback of the cancelled task */ void * @@ -285,7 +287,7 @@ GNUNET_SCHEDULER_cancel (GNUNET_SCHEDULER_TaskIdentifier task); * similar to the other "add" functions except that there is no delay * and the reason code can be specified. * - * * @param task main function of the task + * @param task main function of the task * @param task_cls closure of task * @param reason reason for task invocation */ @@ -300,7 +302,7 @@ GNUNET_SCHEDULER_add_continuation (GNUNET_SCHEDULER_Task task, void *task_cls, * and the reason code can be specified. * * @param task main function of the task - * @param task_cls closure for 'main' + * @param task_cls closure for @a task * @param reason reason for task invocation * @param priority priority to use for the task */ @@ -313,11 +315,11 @@ GNUNET_SCHEDULER_add_continuation_with_priority (GNUNET_SCHEDULER_Task task, voi /** * Schedule a new task to be run with a specified priority. * - * * @param prio how important is the new task? + * @param prio how important is the new task? * @param task main function of the task - * @param task_cls closure of task + * @param task_cls closure of @a task * @return unique task identifier for the job - * only valid until "task" is started! + * only valid until @a task is started! */ GNUNET_SCHEDULER_TaskIdentifier GNUNET_SCHEDULER_add_with_priority (enum GNUNET_SCHEDULER_Priority prio, @@ -328,10 +330,10 @@ GNUNET_SCHEDULER_add_with_priority (enum GNUNET_SCHEDULER_Priority prio, * Schedule a new task to be run as soon as possible. The task * will be run with the DEFAULT priority. * - * * @param task main function of the task - * @param task_cls closure of task + * @param task main function of the task + * @param task_cls closure of @a task * @return unique task identifier for the job - * only valid until "task" is started! + * only valid until @a task is started! */ GNUNET_SCHEDULER_TaskIdentifier GNUNET_SCHEDULER_add_now (GNUNET_SCHEDULER_Task task, void *task_cls); @@ -345,11 +347,11 @@ GNUNET_SCHEDULER_add_now (GNUNET_SCHEDULER_Task task, void *task_cls); * not count for the 'lifeness' of the process. This API is only * useful in a few special cases. * - * @param lifeness GNUNET_YES if the task counts for lifeness, GNUNET_NO if not. + * @param lifeness #GNUNET_YES if the task counts for lifeness, #GNUNET_NO if not. * @param task main function of the task - * @param task_cls closure of task + * @param task_cls closure of @a task * @return unique task identifier for the job - * only valid until "task" is started! + * only valid until @a task is started! */ GNUNET_SCHEDULER_TaskIdentifier GNUNET_SCHEDULER_add_now_with_lifeness (int lifeness, @@ -363,11 +365,11 @@ GNUNET_SCHEDULER_add_now_with_lifeness (int lifeness, * will be run with the DEFAULT priority. * * * @param delay when should this operation time out? Use - * GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown" + * #GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown" * @param task main function of the task - * @param task_cls closure of task + * @param task_cls closure of @a task * @return unique task identifier for the job - * only valid until "task" is started! + * only valid until @a task is started! */ GNUNET_SCHEDULER_TaskIdentifier GNUNET_SCHEDULER_add_delayed (struct GNUNET_TIME_Relative delay, @@ -379,12 +381,12 @@ GNUNET_SCHEDULER_add_delayed (struct GNUNET_TIME_Relative delay, * will be scheduled for execution once the delay has expired. * * @param delay when should this operation time out? Use - * GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown" + * #GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown" * @param priority priority to use for the task * @param task main function of the task - * @param task_cls closure of task + * @param task_cls closure of @a task * @return unique task identifier for the job - * only valid until "task" is started! + * only valid until @a task is started! */ GNUNET_SCHEDULER_TaskIdentifier GNUNET_SCHEDULER_add_delayed_with_priority (struct GNUNET_TIME_Relative delay, @@ -400,12 +402,12 @@ GNUNET_SCHEDULER_add_delayed_with_priority (struct GNUNET_TIME_Relative delay, * socket operation is ready. It will be run with the DEFAULT priority. * * * @param delay when should this operation time out? Use - * GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown" + * #GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown" * @param rfd read file-descriptor * @param task main function of the task - * @param task_cls closure of task + * @param task_cls closure of @a task * @return unique task identifier for the job - * only valid until "task" is started! + * only valid until @a task is started! */ GNUNET_SCHEDULER_TaskIdentifier GNUNET_SCHEDULER_add_read_net (struct GNUNET_TIME_Relative delay, @@ -422,13 +424,13 @@ GNUNET_SCHEDULER_add_read_net (struct GNUNET_TIME_Relative delay, * will be run with the DEFAULT priority. * * @param delay when should this operation time out? Use - * GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown" + * #GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown" * @param priority priority to use for the task * @param rfd read file-descriptor * @param task main function of the task - * @param task_cls closure of task + * @param task_cls closure of @a task * @return unique task identifier for the job - * only valid until "task" is started! + * only valid until @a task is started! */ GNUNET_SCHEDULER_TaskIdentifier GNUNET_SCHEDULER_add_read_net_with_priority (struct GNUNET_TIME_Relative delay, @@ -445,12 +447,12 @@ GNUNET_SCHEDULER_add_read_net_with_priority (struct GNUNET_TIME_Relative delay, * socket operation is ready. It will be run with the DEFAULT priority. * * * @param delay when should this operation time out? Use - * GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown" + * #GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown" * @param wfd write file-descriptor * @param task main function of the task - * @param task_cls closure of task + * @param task_cls closure of @a task * @return unique task identifier for the job - * only valid until "task" is started! + * only valid until @a task is started! */ GNUNET_SCHEDULER_TaskIdentifier GNUNET_SCHEDULER_add_write_net (struct GNUNET_TIME_Relative delay, @@ -466,10 +468,10 @@ GNUNET_SCHEDULER_add_write_net (struct GNUNET_TIME_Relative delay, * socket operation is ready. It will be run with the DEFAULT priority. * * * @param delay when should this operation time out? Use - * GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown" + * #GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown" * @param rfd read file-descriptor * @param task main function of the task - * @param task_cls closure of task + * @param task_cls closure of @a task * @return unique task identifier for the job * only valid until "task" is started! */ @@ -487,12 +489,12 @@ GNUNET_SCHEDULER_add_read_file (struct GNUNET_TIME_Relative delay, * socket operation is ready. It will be run with the DEFAULT priority. * * * @param delay when should this operation time out? Use - * GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown" + * #GNUNET_TIME_UNIT_FOREVER_REL for "on shutdown" * @param wfd write file-descriptor * @param task main function of the task - * @param task_cls closure of task + * @param task_cls closure of @a task * @return unique task identifier for the job - * only valid until "task" is started! + * only valid until @a task is started! */ GNUNET_SCHEDULER_TaskIdentifier GNUNET_SCHEDULER_add_write_file (struct GNUNET_TIME_Relative delay, @@ -518,12 +520,12 @@ GNUNET_SCHEDULER_add_write_file (struct GNUNET_TIME_Relative delay, * * * @param prio how important is this task? - * @param delay how long should we wait? Use GNUNET_TIME_UNIT_FOREVER_REL for "forever", + * @param delay how long should we wait? Use #GNUNET_TIME_UNIT_FOREVER_REL for "forever", * which means that the task will only be run after we receive SIGTERM * @param rs set of file descriptors we want to read (can be NULL) * @param ws set of file descriptors we want to write (can be NULL) * @param task main function of the task - * @param task_cls closure of task + * @param task_cls closure of @a task * @return unique task identifier for the job * only valid until "task" is started! */ @@ -545,6 +547,8 @@ GNUNET_SCHEDULER_set_select (GNUNET_SCHEDULER_select new_select, void *new_select_cls); +/** @} */ /* end of group scheduler */ + #if 0 /* keep Emacsens' auto-indent happy */ { #endif -- cgit v1.2.3