Updated documentation and EVSCHED_TERM scheduling function.

Commit refs #799.

src/common/evsched.c

@@ -3,6 +3,31 @@
 
 #include "common/evsched.h"
 
+/*!
+ * \brief Set event timer to T (now) + dt miliseconds.
+ */
+static void evsched_settimer(event_t *e, int dt)
+{
+	if (!e) {
+		return;
+	}
+
+	/* Get absolute time T. */
+	gettimeofday(&e->tv, 0);
+
+	/* Add number of seconds. */
+	e->tv.tv_sec += dt / 1000;
+
+	/* Add the number of microseconds. */
+	e->tv.tv_usec += (dt % 1000) * 1000;
+
+	/* Check for overflow. */
+	while (e->tv.tv_usec > 999999) {
+		e->tv.tv_sec += 1;
+		e->tv.tv_usec -= 1 * 1000 * 1000;
+	}
+}
+
 evsched_t *evsched_new()
 {
 	evsched_t *s = malloc(sizeof(evsched_t));
@@ -153,7 +178,7 @@ int evsched_schedule(evsched_t *s, event_t *ev)
 	return 0;
 }
 
-event_t* evsched_schedule_cb(evsched_t *s, event_cb_t cb, void *data, int dt_msec)
+event_t* evsched_schedule_cb(evsched_t *s, event_cb_t cb, void *data, int dt)
 {
 	if (!s) {
 		return 0;
@@ -166,20 +191,7 @@ event_t* evsched_schedule_cb(evsched_t *s, event_cb_t cb, void *data, int dt_mse
 
 	e->cb = cb;
 	e->data = data;
-	gettimeofday(&e->tv, 0);
-
-	/* Add number of seconds. */
-	e->tv.tv_sec += dt_msec / 1000;
-
-	/* Add the number of microseconds. */
-	e->tv.tv_usec += (dt_msec % 1000) * 1000;
-
-	/* Check for overflow. */
-	while (e->tv.tv_usec > 999999) {
-		e->tv.tv_sec += 1;
-		e->tv.tv_usec -= 1 * 1000 * 1000;
-	}
-
+	evsched_settimer(e, dt);
 	if (evsched_schedule(s, e) != 0) {
 		evsched_event_free(s, e);
 		e = 0;
@@ -188,7 +200,7 @@ event_t* evsched_schedule_cb(evsched_t *s, event_cb_t cb, void *data, int dt_mse
 	return e;
 }
 
-event_t* evsched_schedule_term(evsched_t *s)
+event_t* evsched_schedule_term(evsched_t *s, int dt)
 {
 	if (!s) {
 		return 0;
@@ -199,7 +211,7 @@ event_t* evsched_schedule_term(evsched_t *s)
 		return 0;
 	}
 
-	gettimeofday(&e->tv, 0);
+	evsched_settimer(e, dt);
 	if (evsched_schedule(s, e) != 0) {
 		evsched_event_free(s, e);
 		e = 0;

src/common/evsched.h

@@ -5,6 +5,45 @@
  *
  * \brief Event scheduler.
  *
+ * Scheduler works with the same event_t type as event queue.
+ * It is also thread-safe so the scheduler can run in a separate thread
+ * while events can be enqueued from different threads.
+ *
+ * Guideline is, that the scheduler run loop should exit with
+ * a special event type EVSCHED_TERM.
+ *
+ * Example usage:
+ * \code
+ * evsched_t *s = evsched_new();
+ *
+ * // Schedule myfunc() after 1000ms
+ * evsched_schedule_cb(s, myfunc, data, 1000)
+ *
+ * // Schedule termination event after 1500ms
+ * evsched_schedule_term(s, 1500);
+ *
+ * // Event scheduler main loop
+ * while (1) {
+ *    // Wait for next scheduled event
+ *    event_t *ev = evsched_next();
+ *
+ *    // Break on termination event
+ *    if (ev->type == EVSCHED_TERM) {
+ *       evsched_event_free(s, ev);
+ *       break;
+ *    }
+ *
+ *    // Execute and discard event
+ *    if (ev->cb) {
+ *       ev->cb(ev);
+ *    }
+ *    evsched_event_free(s, ev); // Free executed event
+ * }
+ *
+ * // Delete event scheduler
+ * evsched_delete(s);
+ * \endcode
+ *
  * \addtogroup common_lib
  * @{
  */
@@ -109,12 +148,12 @@ int evsched_schedule(evsched_t *s, event_t *ev);
  * \param s Event scheduler.
  * \param cb Callback handler.
  * \param data Data for callback.
- * \param dt_msec Time difference in milliseconds from now.
+ * \param dt Time difference in milliseconds from now (dt is relative).
  *
  * \retval Event instance on success.
  * \retval NULL on error.
  */
-event_t* evsched_schedule_cb(evsched_t *s, event_cb_t cb, void *data, int dt_msec);
+event_t* evsched_schedule_cb(evsched_t *s, event_cb_t cb, void *data, int dt);
 
 /*!
  * \brief Schedule termination event.
@@ -122,11 +161,12 @@ event_t* evsched_schedule_cb(evsched_t *s, event_cb_t cb, void *data, int dt_mse
  * Special action for scheduler termination.
  *
  * \param s Event scheduler.
+ * \param dt Time difference in milliseconds from now (dt is relative).
  *
  * \retval Event instance on success.
  * \retval NULL on error.
  */
-event_t* evsched_schedule_term(evsched_t *s);
+event_t* evsched_schedule_term(evsched_t *s, int dt);
 
 /*!
  * \brief Cancel a scheduled event.