From: Andre Noll <maan@systemlinux.org>
Date: Wed, 17 Feb 2010 05:16:10 +0000 (+0100)
Subject: sched: Add missing documentation for timeout-request functions.
X-Git-Tag: v0.4.2~52
X-Git-Url: http://git.tue.mpg.de/?a=commitdiff_plain;h=80ee0bc028e45161c35b33a479cb375a4c5f76ba;p=paraslash.git

sched: Add missing documentation for timeout-request functions.
---

diff --git a/sched.c b/sched.c
index b6efb1ae..4c9f14a8 100644
--- a/sched.c
+++ b/sched.c
@@ -25,7 +25,7 @@ static int initialized;
 static struct timeval now_struct;
 struct timeval *now = &now_struct;
 
-/**
+/*
  * Remove a task from the scheduler.
  *
  * \param t The task to remove.
@@ -137,7 +137,7 @@ again:
 	goto again;
 }
 
-/**
+/*
  * Initialize the paraslash scheduler.
  */
 static void init_sched(void)
@@ -199,7 +199,7 @@ void sched_shutdown(void)
  *
  * 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.
+ * The result is dynamically allocated and must be freed by the caller.
  */
 char *get_task_list(void)
 {
@@ -261,18 +261,46 @@ int kill_task(char *id)
 	return -E_NO_SUCH_TASK;
 }
 
+/**
+ * Set the select timeout to the minimal possible value.
+ *
+ * \param s Pointer to the scheduler struct.
+ *
+ * This causes the next select() call to return immediately.
+ */
 void sched_min_delay(struct sched *s)
 {
 	s->timeout.tv_sec = 0;
 	s->timeout.tv_usec = 1;
 }
 
+/**
+ * Impose an upper bound for the timeout of the next select() call.
+ *
+ * \param timeout Maximal allowed timeout.
+ * \param s Pointer to the scheduler struct.
+ *
+ * If the current scheduler timeout is already smaller than \a timeout, this
+ * function does nothing. Otherwise the timeout for the next select() call is
+ * set to the given value.
+ *
+ * \sa sched_request_timeout_ms().
+ */
 void sched_request_timeout(struct timeval *timeout, struct sched *s)
 {
 	if (tv_diff(&s->timeout, timeout, NULL) > 0)
 		s->timeout = *timeout;
 }
 
+/**
+ * Force the next select() call to return before the given amount of milliseconds.
+ *
+ * \param ms The maximal allowed timeout in milliseconds.
+ * \param s Pointer to the scheduler struct.
+ *
+ * Like sched_request_timeout() this imposes an upper bound on the timeout
+ * value for the next select() call.
+ */
 void sched_request_timeout_ms(long unsigned ms, struct sched *s)
 {
 	struct timeval tv;
@@ -280,6 +308,16 @@ void sched_request_timeout_ms(long unsigned ms, struct sched *s)
 	sched_request_timeout(&tv, s);
 }
 
+/**
+ * Force the next select() call to return before the given future time.
+ *
+ * \param barrier Absolute time before select() should return.
+ * \param s Pointer to the scheduler struct.
+ *
+ * If \a barrier is in the past, this function does nothing.
+ *
+ * \sa sched_request_barrier_or_min_delay().
+ */
 void sched_request_barrier(struct timeval *barrier, struct sched *s)
 {
 	struct timeval diff;
@@ -289,6 +327,16 @@ void sched_request_barrier(struct timeval *barrier, struct sched *s)
 	sched_request_timeout(&diff, s);
 }
 
+/**
+ * Force the next select() call to return before the given time.
+ *
+ * \param barrier Absolute time before select() should return.
+ * \param s Pointer to the scheduler struct.
+ *
+ * If \a barrier is in the past, this function requests a minimal timeout.
+ *
+ * \sa sched_min_delay(), sched_request_barrier().
+ */
 void sched_request_barrier_or_min_delay(struct timeval *barrier, struct sched *s)
 {
 	struct timeval diff;