faux.sched: Documented sched.c

faux/sched/ev.c

@@ -10,6 +10,18 @@
 #include "faux/str.h"
 #include "faux/sched.h"
 
+
+/** @brief Callback function to compare two events by time.
+ *
+ * It's used for ordering within schedule list.
+ *
+ * @param [in] first First event to compare.
+ * @param [in] second Second event to compare.
+ * @return
+ * > 0 if first > second,
+ * 0 - equal,
+ * < 0 if first < second
+ */
 int faux_ev_compare(const void *first, const void *second)
 {
 	const faux_ev_t *f = (const faux_ev_t *)first;
@@ -19,6 +31,17 @@ int faux_ev_compare(const void *first, const void *second)
 }
 
 
+/** @brief Callback function to compare key and list item by ID.
+ *
+ * It's used to search for specified ID within schedule list.
+ *
+ * @param [in] key Pointer to key value
+ * @param [in] list_item Pointer to list item.
+ * @return
+ * > 0 if key > list_item,
+ * 0 - equal,
+ * < 0 if key < list_item
+ */
 int faux_ev_compare_id(const void *key, const void *list_item)
 {
 	int *f = (int *)key;
@@ -28,6 +51,17 @@ int faux_ev_compare_id(const void *key, const void *list_item)
 }
 
 
+/** @brief Callback function to compare key and list item by data pointer.
+ *
+ * It's used to search for specified data pointer within schedule list.
+ *
+ * @param [in] key Pointer to key value
+ * @param [in] list_item Pointer to list item.
+ * @return
+ * > 0 if key > list_item,
+ * 0 - equal,
+ * < 0 if key < list_item
+ */
 int faux_ev_compare_data(const void *key, const void *list_item)
 {
 	void *f = (void *)key;

faux/sched/sched.c

@@ -1,4 +1,18 @@
 /** @brief Mechanism to shedule events.
+ *
+ * It's an ordered list of events. Events are ordered by the time. The earlier
+ * events are closer to list head. The events can be one-time ("once") and
+ * periodic. Periodic events have period and number of cycles (can be infinite).
+ * User can schedule events specifying absolute time of future event or interval
+ * from now to the moment of event. Periodic events will be rescheduled
+ * automatically using specified period.
+ *
+ * User can get interval from now to next event time. User can get upcoming
+ * events one-by-one.
+ *
+ * Each scheduled event can has arbitrary ID and pointer to arbitrary data
+ * linked to this event. The ID can be used for type of event for
+ * example or something else. The linked data can be a service structure.
  */
 
 #include <sys/time.h>
@@ -14,7 +28,7 @@
 #include "faux/sched.h"
 
 
-/** @brief Allocates new sched (SCHedule EVent) object.
+/** @brief Allocates new sched object.
  *
  * Before working with sched object it must be allocated and initialized.
  *
@@ -52,6 +66,12 @@ void faux_sched_free(faux_sched_t *sched)
 }
 
 
+/** @brief Internal function to add existent event to scheduling list.
+ *
+ * @param [in] sched Allocated and initialized sched object.
+ * @param [in] ev Existent ev object.
+ * @return 0 - success, < 0 on error.
+ */
 static int _sched_ev(faux_sched_t *sched, faux_ev_t *ev)
 {
 	faux_list_node_t *node = NULL;
@@ -68,7 +88,7 @@ static int _sched_ev(faux_sched_t *sched, faux_ev_t *ev)
 	return 0;
 }
 
-/** @brief Internal function to add event to scheduling list.
+/** @brief Internal function to add constructed event to scheduling list.
  *
  * @param [in] sched Allocated and initialized sched object.
  * @param [in] time Absolute time of future event.
@@ -104,7 +124,7 @@ static int _sched(faux_sched_t *sched, const struct timespec *time,
 /** @brief Adds non-periodic event to scheduling list using absolute time.
  *
  * @param [in] sched Allocated and initialized sched object.
- * @param [in] time Absolute time of future event.
+ * @param [in] time Absolute time of future event (FAUX_SCHED_NOW for now).
  * @param [in] ev_id Event ID.
  * @param [in] data Pointer to arbitrary data linked to event.
  * @return 0 - success, < 0 on error.
@@ -198,6 +218,10 @@ int faux_sched_periodic_delayed(
  *
  * If event is in the past then return null interval.
  * If no events was scheduled then return -1.
+ *
+ * @param [in] sched Allocated and initialized sched object.
+ * @param [out] interval Calculated interval.
+ * @return 0 - success, < 0 on error or when there is no scheduled events.
  */
 int faux_sched_next_interval(faux_sched_t *sched, struct timespec *interval)
 {
@@ -220,7 +244,7 @@ int faux_sched_next_interval(faux_sched_t *sched, struct timespec *interval)
 
 /** @brief Remove all entries from the list.
  *
- *
+ * @param [in] sched Allocated and initialized sched object.
  */
 void faux_sched_empty(faux_sched_t *sched)
 {
@@ -236,6 +260,11 @@ void faux_sched_empty(faux_sched_t *sched)
  *
  * Pop (get and remove from list) timestamp if it's in the past.
  * If the timestamp is in the future then do nothing.
+ *
+ * @param [in] sched Allocated and initialized sched object.
+ * @param [out] ev_id ID of upcoming event.
+ * @param [out] data Data of upcoming event.
+ * @return 0 - success, < 0 on error.
  */
 int faux_sched_pop(faux_sched_t *sched, int *ev_id, void **data)
 {
@@ -268,7 +297,12 @@ int faux_sched_pop(faux_sched_t *sched, int *ev_id, void **data)
 	return 0;
 }
 
-
+/** @brief Removes all events with specified ID from list.
+ *
+ * @param [in] sched Allocated and initialized sched object.
+ * @param [in] id ID to remove.
+ * @return Number of removed entries.
+ */
 int faux_sched_remove_by_id(faux_sched_t *sched, int id)
 {
 	faux_list_node_t *node = NULL;
@@ -289,6 +323,12 @@ int faux_sched_remove_by_id(faux_sched_t *sched, int id)
 }
 
 
+/** @brief Removes all events with specified data pointer from list.
+ *
+ * @param [in] sched Allocated and initialized sched object.
+ * @param [in] data Data to search entries to remove.
+ * @return Number of removed entries.
+ */
 int faux_sched_remove_by_data(faux_sched_t *sched, void *data)
 {
 	faux_list_node_t *node = NULL;